ATMI C Function Reference
tpenvelope()
—Accesses the digital signature and encryption information associated with a typed message buffer.
#include <atmi.h>
int tpenvelope(char *data
, longlen
, intoccurrence
, TPKEY *outputkey
, long *status
, char *timestamp
, longflags
)
tpenvelope()
provides access to the following types of digital signature and encryption information associated with a typed message buffer:
A sending process explicitly registers a digital signature request for a message buffer by calling tpsign()
, or implicitly registers a digital signature request for a message buffer by calling tpkey_open()
with the TPKEY_AUTOSIGN
flag specified.
Just before the message buffer is sent, the public key software generates and attaches a digital signature to the message buffer for each digital-signature registration request; a digital signature enables a receiving process to verify the signer (originator) of the message.
A sending process explicitly registers an encryption (seal) request for a message buffer by calling tpseal()
, or implicitly registers an encryption (seal) request for a message buffer by calling tpkey_open()
with the TPKEY_AUTOENCRYPT
flag specified.
Signature and encryption information is available to both sending and receiving processes. In a sending 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. Failures in decryption or signature verification might prevent message delivery, in which case the receiving process never receives the message buffer and therefore has no knowledge of the message buffer.
data
must point to a valid typed message buffer either (1) previously allocated by a process calling tpalloc()
or (2) delivered by the system to a receiving process. If the message buffer is self-describing, len
is ignored (and may be 0). Otherwise, len
must contain the length of data in data
.
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 indicates which item is requested. When the value of occurrence
is beyond the position of the last item, tpenvelope()
fails with the TPENOENT
error condition. All items may be examined by calling tpenvelope()
repeatedly until TPENOENT
is returned.
The handle to the key associated with a digital-signature registration request, digital signature, encryption registration request, or encryption envelope is returned via outputkey
. The key handle returned is a separate copy of the original key opened by calling tpkey_open()
. Properties of the key, such as the PRINCIPAL
attribute parameter, can be obtained by calling tpkey_getinfo()
. It is the caller's responsibility to release key handle outputkey
by calling tpkey_close()
.
Note: If outputkey
is NULL, no key handle is returned.
The status
output parameter reports the state of the digital-signature registration request, digital signature, encryption registration request, or encryption envelope. If the value of the status is not NULL, it is set to one of the following states:
A digital signature has been requested on behalf of the signer principal associated with the corresponding private key, and will be generated when the message buffer is transmitted from this process.
The digital signature is not valid because the signer's digital certificate was issued by an unknown Certification Authority (CA).
An encryption (seal) has been requested for the recipient principal associated with the corresponding public key, and will be performed when the message buffer is transmitted from this process.
The timestamp
output parameter contains the digital signature's timestamp according to the local clock on the machine where the digital signature was generated. The integrity of this value is protected by the associated digital signature. The memory location indicated by timestamp
is set to the NULL-terminated signature time in format YYYYMMDDHHMMSS
, where YYYY
=year, MM
=month, DD
=day, HH
=hour, MM
=minute, and SS
=second. timestamp
may be NULL, in which case no value is returned. Encryption seals do not contain timestamps, and the memory location indicated by timestamp
is unchanged.
The flags
parameter may be set to one of the following values:
TPKEY_REMOVE
-The item at position occurrence
is removed (that is, it is no longer associated with the buffer). Output parameters outputkey
, status
, and timestamp
related to the item are captured before the item is removed. Items at subsequent positions are shifted down by one, so there are never any gaps in the numbering of occurrence
.TPKEY_REMOVEALL
-All items associated with the message buffer are removed. The output parameters outputkey
, status
, and timestamp
are not returned.TPKEY_VERIFY
-All digital signatures associated with the message buffer are reverified. The status of a signature may change after reverification. For example, if a message buffer has been modified by a receiving process, the status of the originator's signature changes from TPSIGN_OK
to TPSIGN_TAMPERED_MESSAGE
.On failure, this function returns -1
and sets tperrno
to indicate the error condition.
Invalid arguments were given. For example, the value of data
is NULL or the value assigned to flags
is unrecognized.
tpkey_close(3c)
, tpkey_getinfo(3c)
, tpkey_open(3c)
, tpseal(3c)
, tpsign(3c)