tpenvelope(3c)

Name

tpenvelope()—Accesses 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:

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:

Return Values

On failure, this function returns -1 and sets tperrno() to indicate the error condition.

Errors

See Also