|
|
tpenvelope(3c)
Name
tpenvelope() - access the digital signature and encryption information associated with a typed message buffer
Synopsis
#include <atmi.h>
int tpenvelope(char *data, long len, int occurrence, TPKEY *outputkey, long *status, char *timestamp, long flags)
Description
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.
Just before the message buffer is sent, the public key software encrypts the message content and attaches an encryption envelope to the message buffer for each encryption registration request; an encryption envelope enables a receiving process to decrypt the message.
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.
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:
On failure, this function returns -1 and sets tperrno() to indicate the error condition.
Errors
See Also
tpkey_close(3c), tpkey_getinfo(3c), tpkey_open(3c), tpseal(3c), tpsign(3c)
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|