ATMI COBOL Function Reference
TPKEYOPEN()
- open a key handle for digital signature generation, message encryption, or message decryption
01
TPKEYDEF-REC
.
COPY TPKEYDEF.
01TPSTATUS-REC
.
COPY TPSTATUS.
CALL "TPKEYOPEN" USINGTPKEYDEF-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.
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
.
Whenever this process transmits a message, the public key software uses the signer's private key to generate a digital signature and then attaches the digital signature to the message.
Whenever this process transmits a message, the public key software encrypts the message, uses the recipient's public key to generate an encryption envelope, and then attaches the encryption envelope to the message.
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:
Permission failure. The cryptographic service provider was not able to access a private key for this principal, given the proof information and current environment.