Section 3c - C Functions

ATMI C Function Reference

tpkey_open(3c)

Name

tpkey_open()—Opens 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:

Generating a digital signature, which protects a typed message buffer's content and proves that a specific principal originated the message. (A principal may be a person or a process.) This type of key is a private key and is available only to the key's owner.

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.

Verifying a digital signature, which proves that a typed message buffer's content remains unaltered and that a specific principal originated the message.

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.

Encrypting a message buffer destined for a specific principal. This type of key is available to any process with access to the principal's public key and digital certificate.

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.

Decrypting a message buffer intended for a specific principal. This type of key is a private key and is available only to the key's owner.

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:

TPKEY_SIGNATURE:

This private key is available to generate digital signatures.

TPKEY_AUTOSIGN:

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.

TPKEY_ENCRYPT:

This public key is available to identify the recipient of an encrypted message.

TPKEY_AUTOENCRYPT:

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.

TPKEY_DECRYPT:

This private key is available for decryption.

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

[TPEINVAL]

Invalid arguments were given. For example, the value of hKey is NULL or the flags parameter is not set correctly.

[TPEPERM]

Permission failure. The cryptographic service provider was not able to access a private key for this principal, given the proof information and current environment.

[TPESYSTEM]

A system error occurred. Consult the systems error log file for details.