|
|
|
|
|
|
Examining Digital Signature and Encryption Information
The public key software maintains the order in which:
A process obtains this information by calling the tpenvelope() function with the target message buffer as an argument. tpenvelope() is described on the tpenvelope(3c) reference page in the BEA Tuxedo ATMI C Function Reference.
There may be multiple occurrences of digital-signature registration requests, digital signatures, encryption registration requests, and encryption envelopes associated with a message buffer. The occurrences are stored in sequence, with the first item at the zero position and subsequent items in consecutive positions. The occurrence input parameter for tpenvelope() indicates which item is being requested. When the value of occurrence is beyond the position of the last item, tpenvelope() fails with the TPENOENT error condition. A process can examine all items by calling tpenvelope() repeatedly until TPENOENT is returned.
In an originating process, digital signature and encryption information is generally in a pending state, waiting until the message is sent. In a receiving process, digital signatures have already been verified, and encryption and decryption have already been performed.
What Happens When an Originating Process Calls tpenvelope
When an originating process calls tpenvelope() with the originating message buffer as an argument, tpenvelope() reports:
In addition to the status, tpenvelope() returns the key handle associated with a digital signature or encryption registration request. A process can call the tpkey_getinfo(3c) function with the key handle as an argument, to get more information about the key handle.
What Happens When a Receiving Process Calls tpenvelope
When a process receives a message buffer, it receives only the message content. Any digital signatures or encryption envelopes associated with the message buffer are not included. The receiving process must call tpenvelope() to obtain information about any attached digital signatures or encryption envelopes.
When a receiving process calls tpenvelope() with the received message buffer as an argument, tpenvelope() reports:
Digital signature has been verified.
Digital signature is not valid because the content of the message buffer has been altered.
Digital signature is not valid because the signer's digital certificate has been altered.
Digital signature is not valid because the signer's digital certificate has been revoked.
Digital signature is not valid because its timestamp is too far into the future.
Digital signature is not valid because the signer's digital certificate has expired.
Digital signature is not valid because its timestamp is too old.
Digital signature is not valid because the signer's digital certificate was issued by an unknown Certification Authority (CA).
Encryption envelope is valid.
Encryption envelope is not valid because the target recipient's digital certificate has been altered. (Target recipient will not receive the message buffer.)
Encryption envelope is not valid because the target recipient's digital certificate has been revoked. (Target recipient will not receive the message buffer.)
Encryption envelope is not valid because the target recipient's digital certificate has expired. (Target recipient will not receive the message buffer.)
Encryption envelope is not valid because the target recipient's digital certificate was issued by an unknown CA. (Target recipient will not receive the message buffer.)
In addition to the status, tpenvelope() returns the key handle associated with a digital signature or encryption envelope. A process can call the tpkey_getinfo(3c) function with the key handle as an argument, to get more information about the key handle.
If a receiving process calls tpsign() to register a digital signature request after receiving the message buffer, tpenvelope() reports the status of the registration as TPSIGN_PENDING. Similarly, if a receiving process calls tpseal() to register an encryption (seal) request after receiving the message buffer, tpenvelope() reports the status of the registration as TPSEAL_PENDING.
If a receiving process modifies the content of a signed message buffer after receiving it, the attached signatures are no longer valid. As a result, tpenvelope() cannot verify the signatures, and reports a signature status of TPSIGN_TAMPERED_MESSAGE.
Understanding the Composite Signature Status
For a message buffer with multiple digital signatures, the public key software calls an internal function equivalent to tpenvelope() to examine the state of each digital signature. Then, by observing certain rules, the public key software forms a composite signature status. The rules for forming a composite signature status are shown in the following table.
Any incoming message buffer without a composite signature status of TPSIGN_OK or TPSIGN_UNKNOWN is discarded as if it were never received. If the SIGNATURE_REQUIRED parameter is set to Y (yes) in the ATMI application's UBBCONFIG file, then any incoming message buffer without a composite signature status of TPSIGN_OK is discarded as if it were never received. See Enforcing the Signature Policy for Incoming Messages for more detail.
An exception to the handling of signed message buffers described in the previous paragraph is the tpimport(3c) function. The tpimport(3c) function delivers an incoming message buffer regardless of the composite signature status.
Example Code for tpenvelope
The following example code shows how to use tpenvelope() to examine the digital signature and encryption information associated with a message buffer.
Using tpenvelope Example
main(argc, argv)
int argc;
char *argv[];
#endif
{
TPKEY tu_key;
TPKEY sdo_key;
TPKEY output_key;
char *sendbuf, *rcvbuf;
int ret;
int occurrence = 0;
long status;
char principal_name[PNAME_LEN];
long pname_len = PNAME_LEN;
int found = 0;
.
.
.
output_key = NULL;
ret = tpenvelope(rcvbuf, 0, occurrence, &output_key,
&status, NULL, 0); while (ret != -1) {
if (status == TPSIGN_OK) {
if (tpkey_getinfo(output_key, "PRINCIPAL",
principal_name, &pname_len, 0) == -1) {
(void) fprintf(stdout, "Unable to get information
about principal: %d(%s)\n",
tperrno, tpstrerror(tperrno));
tpfree(sendbuf);
tpfree(rcvbuf);
tpterm();
(void) tpkey_close(tu_key, 0);
(void) tpkey_close(sdo_key, 0);
(void) tpkey_close(output_key, 0);
exit(1);
}/* Do not forget to free resources */
(void) tpkey_close(output_key, 0);
output_key = NULL;
found = 1;
break;
}
/* Do not forget to free resources */
(void) tpkey_close(output_key, 0);
output_key = NULL;
occurrence++;
ret = tpenvelope(rcvbuf, 0, occurrence, &output_key,
&status, NULL, 0);
}
.
.
.
}
See Also
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|