ATMI C Function Reference
tpkey_open()
—Opens a key handle for digital signature generation, message encryption, or message decryption.
#include <atmi.h>
int tpkey_open(TPKEY *hKey
, char *principal_name
, char *location
, char *identity_proof
, longproof_len
, longflags
)
tpkey_open()
makes a key handle available to the calling process. A key handle represents a specific principal's key and the information associated with it.
A key may be used for one or more of the following purposes:
Calling tpkey_open()
with the principal's name and either the TPKEY_SIGNATURE
or TPKEY_AUTOSIGN
flag returns a handle to the principal's private key and digital certificate.
Signature verification does not require a call to tpkey_open()
; the verifying process uses the public key specified in the digital certificate accompanying the digitally signed message to verify the signature.
Calling tpkey_open()
with the principal's name and either the TPKEY_ENCRYPT
or TPKEY_AUTOENCRYPT
flag returns a handle to the principal's public key via the principal's digital certificate.
The key handle returned by tpkey_open()
is stored in *hKey
, the value of which cannot be NULL.
The principal_name
input parameter specifies the key owner's identity. If the value of principal_name
is a NULL pointer or an empty string, a default identity is assumed. The default identity may be based on the current login session, the current operating system account, or another attribute such as a local hardware device.
The file location of a key may be passed into the location
parameter. If the underlying key management provider does not require a location parameter, the value of this parameter may be NULL.
To authenticate the identity of principal_name
, proof material such as a password or pass phrase may be required. If required, the proof material should be referenced by identity_proof
. Otherwise, the value of this parameter may be NULL.
The length of the proof material (in bytes) is specified by proof_len
. If proof_len
is 0, identity_proof
is assumed to be a NULL-terminated character string.
The type of key access required for a key's mode of operation is specified by the flags
parameter:
Whenever this process transmits a message buffer, the public key software uses the signer's private key to generate a digital signature and then attaches the digital signature to the buffer. TPKEY_SIGNATURE
is implied.
Whenever this process transmits a message buffer, the public key software encrypts the message content, uses the recipient's public key to generate an encryption envelope, and then attaches the encryption envelope to the buffer. TPKEY_ENCRYPT
is implied.
Any combination of one or more of these flag values is allowed. If a key is used only for encryption (TPKEY_ENCRYPT
), identity_proof
is not required and may be set to NULL.
Upon successful completion, *hKey
is set to a value that represents this key, for use by other functions such as tpsign()
and tpseal()
.
On failure, this function returns -1 and sets tperrno
to indicate the error condition.
Invalid arguments were given. For example, the value of hKey
is NULL or the flags
parameter is not set correctly.
Permission failure. The cryptographic service provider was not able to access a private key for this principal, given the proof information and current environment.