BEA Logo BEA Tuxedo Release 7.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy


   Tuxedo Doc Home   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo COBOL Function Reference



TPKEYOPEN() - open a key handle for digital signature generation, message encryption, or message decryption






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:

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.


This private key is available to generate digital signatures.


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.


This public key is available to identify the recipient of an encrypted 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.


This private key is available for decryption.

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.

Return Values

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.


Invalid arguments were given. For example, the settings (flag) values are not set correctly.


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


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

See Also