|
|
tpkey_open(3c)
Name
tpkey_open() - open a key handle for digital signature generation, message encryption, or message decryption
Synopsis
#include <atmi.h>
int tpkey_open(TPKEY *hKey, char *principal_name, char *location, char *identity_proof, long proof_len, long flags)
Description
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.
Calling tpkey_open() with the principal's name and the TPKEY_DECRYPT flag returns a handle to the principal's private key and 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.
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.
Return Values
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.
Errors
See Also
tpkey_close(3c), tpkey_getinfo(3c), tpkey_setinfo(3c)
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|