Section 3c - C Functions

ATMI C Function Reference

tpkey_close(3c)

Name

tpkey_close()—Closes a previously opened key handle.

Synopsis

#include <atmi.h>
int tpkey_close(TPKEY hKey, long flags)

Description

tpkey_close() releases a previously opened key handle and all resources associated with it. Any sensitive information, such as the principal's private key, is erased from memory.

Key handles can be opened in one of two ways:

By an explicit call to tpkey_open()
As output from tpenvelope()

It is the application's responsibility to release key resources by calling tpkey_close(). Once a process closes a key, the process can no longer use the key handle to register a message buffer for digital signature or encryption. If the process opened the key using tpkey_open() with the TPKEY_AUTOSIGN or TPKEY_AUTOENCRYPT flag specified, the key handle no longer applies to future communication operations after the key is closed.

Even though a key is closed, however, the key handle continues to be valid for any associated signature or encryption request registered before the key was closed. When the last buffer associated with a closed key is freed or overwritten, resources attributable to the key are released.

The flags argument is reserved for future use and must be set to 0.

Return Values

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 not a valid key.

[TPESYSTEM]

An error occurred. Consult the system error log file for details.