TPKEYOPEN(3cbl)


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| COBOL Function Reference \| Local Topics \| Previous Topic \| Next Topic \| Contents

TPKEYOPEN(3cbl)

Name

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

Synopsis

01 TPKEYDEF-REC. 
   COPY TPKEYDEF.

01 TPSTATUS-REC. 
   COPY TPSTATUS.

CALL "TPKEYOPEN" USING TPKEYDEF-REC TPSTATUS-REC.

Description

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:

Automatically generating a digital signature, which protects a message'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 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.
Verifying a digital signature, which proves that a message's content remains unaltered and that a specific principal originated the message.
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.
Automatically encrypting a message 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 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.
Decrypting a message intended for a specific principal. This type of key is a private key and is available only to the key's owner.
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.

TPKEY-SIGNATURE:

This private key is available to generate digital signatures.

TPKEY-AUTOSIGN:

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.

TPKEY-ENCRYPT:

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

TPKEY-AUTOENCRYPT:

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.

TPKEY-DECRYPT:

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().

Errors

Upon failure, TPKEYOPEN() sets TP-STATUS in TPSTATUS-REC to one of the following values:

[TPEINVAL]

Invalid arguments were given. For example, the settings (flag) values are 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]

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