TPKEYOPEN() - open a key handle for digital signature generation, message encryption, or message decryption
CALL "TPKEYOPEN" USING TPKEYDEF-REC TPSTATUS-REC.
TPKEYOPEN() 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 TPKEYOPEN() with the principal's name and the TPKEY-SIGNATURE and TPKEY-AUTOSIGN settings returns a handle to the principal's public key and enables signature generation in AUTOSIGN mode. The public key software generates and attaches the digital signature to the message just before the message is sent.
Signature verification does not require a call to TPKEYOPEN(); the verifying process uses the public key specified in the digital certificate accompanying the digitally signed message to verify the signature.
Calling TPKEYOPEN() with the principal's name and the TPKEY-ENCRYPT and TPKEY-AUTOENCRYPT settings returns a handle to the principal's public key (via the principal's digital certificate) and enables encryption in AUTOENCRYPT mode. The public key software encrypts the message and attaches an encryption envelope to the message just before the message is sent; the encryption envelope enables the receiving process to decrypt the message.
Calling TPKEYOPEN() with the principal's name and the TPKEY-DECRYPT setting returns a handle to the principal's private key and digital certificate.
The key handle returned by TPKEYOPEN() is stored in KEY-HANDLE in TPKEYDEF-REC.
The calling process must supply PRINCIPAL-NAME in TPKEYDEF-REC, which specifies the key owner's identity. This name may be padded at the end with SPACES or LOW-VALUES. If PRINCIPAL-NAME is all SPACES or LOW-VALUES, 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 calling process may have to supply LOCATION in TPKEYDEF-REC, which specifies the location of a key owner's identity. If the underlying provider does not require a location field, this field may be populated with SPACES or LOW-VALUES.
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 stored in IDENTITY-PROOF in TPKEYDEF-REC. Otherwise, this field may be populated with SPACES or LOW-VALUES.
The length of the proof material (in bytes) is specified by PROOF-LEN in TPKEYDEF-REC. If PROOF-LEN is 0,IDENTITY-PROOF is assumed to be a character string padded at the end with SPACES or LOW-VALUES, in which case trailing SPACES or LOW-VALUES are not considered part of the proof material.
There may be a choice of cryptographic service providers, based on the local machine's configuration and operating environment. If you need to choose one, set CRYPTO-PROVIDER in TPKEYDEF-REC to the name of the required provider. Otherwise, set this field to SPACES or LOW-VALUES, and a default provider will be assumed.
The type of key access required for a key's mode of operation is determined by specifying one or more of the following settings in TPKEYDEF-REC.
Various combinations of these settings are allowed. If a key is used only for encryption (TPKEY-ENCRYPT and TPKEY-AUTOENCRYPT), IDENTITY-PROOF is not required.
Upon successful completion, TPKEYOPEN() sets TP-STATUS in TPSTATUS-REC to [TPOK]. In addition, KEY-HANDLE in TPKEYDEF-REC is set to a value that represents this key, for use by other functions such as TPKEYGETINFO().
Upon failure, TPKEYOPEN() sets TP-STATUS in TPSTATUS-REC to one of the following values.
TPKEYCLOSE(3cbl), TPKEYGETINFO(3cbl), TPKEYSETINFO(3cbl)
Copyright © 2000 BEA Systems, Inc. All rights reserved.