Writing Security Code to Protect Data Integrity and Privacy


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Doc Home \| Security \| Topic List \| Previous \| Next \| Contents

Using BEA Tuxedo Security

Public key security comprises end-to-end digital signing and data encryption. Both features are supported by BEA Tuxedo ATMI functions. Applications protected by public key security are much safer for use across the Internet than programs in which this type of security is not used.

The capabilities that make end-to-end digital signing and data encryption possible are message-based digital signature and message-based encryption. Both capabilities are built upon the PKCS-7 standard, which is one of a set of Public-Key Cryptography Standards (PKCS) developed by RSA Laboratories in cooperation with several other leading communications companies.

Message-based digital signature ensures data integrity and non-repudiation by having the sending party bind proof of its identity to a specific message buffer. Message-based encryption protects the confidentiality of messages; only parties for whom messages are intended can decrypt and read them.

Because the unit of digital signing and encryption is a BEA Tuxedo message buffer, both capabilities are compatible with existing BEA Tuxedo programming interfaces and communication paradigms. It is possible for a message buffer to be both signed and encrypted. There is no required relationship between the number of digital signatures and the number of encryption envelopes associated with a message buffer.

Note: Each encryption envelope identifies a recipient of the message, and contains information needed by the recipient to decrypt the message.

ATMI for Public Key Security

The ATMI for public key security is a compact set of functions used to:

Open and close key resources
View and change key optional parameters
Sign and seal (encrypt) message buffers
Access the digital signature and encryption information associated with a message buffer
Convert a typed message buffer into an exportable, machine-independent string representation, which includes the generation of any digital signatures or encryption envelopes associated with the buffer

The ATMI for public key security is available in both C and COBOL implementations. The BEA Tuxedo COBOL language binding, however, does not support message buffers; thus, explicit signature, encryption, and query operations on individual buffers cannot be used in a COBOL application. However, key management interfaces do have a COBOL language binding, which enables signature generation in the AUTOSIGN mode and encryption-envelope generation in the AUTOENCRYPT mode. All operations related to automatic signature verification or automatic decryption apply to COBOL client and server processes.

Note: The COBOL TPKEYDEF record is used to manage public-private keys for performing message-based digital signature and encryption operations. See COBOL Language ATMI Return Codes and Other Definitions in the introduction part of BEA Tuxedo COBOL Function Reference for a description of the TPKEYDEF record.

The following tables summarize the ATMI for public key security. Each function is also documented in BEA Tuxedo C Function Reference / BEA Tuxedo COBOL Function Reference.

C Functions in ATMI for Public Key Security

Use this function . . .
To . . .

tpkey_open(3c)

Open a key handle for digital signature generation, message encryption, or message decryption. Keys are represented and manipulated via handles. A handle has data associated with it that is used by the ATMI to locate or access the item named by the handle.

A key may play one or more of the following roles:

Signature Generation
The key identifies the calling process as being authorized to generate a digital signature under the principal's identity. (A principal may be a person or a process.) Calling tpkey_open() with the principal's name and either the TPKEY_SIGNATURE or TPKEY_AUTOSIGN flag returns a handle to the principal's private key and digital certificate.
Signature Verification
The key represents the principal associated with a digital signature. Signature verification does not require a call to tpkey_open(); the verifying process uses the public key specified in the digital certificate accompanying the digitally signed message to verify the signature.
Encryption
The key represents the intended principal of an encrypted message. Calling tpkey_open() with the principal's name and either the TPKEY_ENCRYPT or TPKEY_AUTOENCRYPT flag returns a handle to the principal's public key via the principal's digital certificate.
Decryption
The key identifies the calling process as being authorized to decrypt a private message for the intended principal. Calling tpkey_open() with the principal's name and the TPKEY_DECRYPT flag returns a handle to the principal's private key and digital certificate.

tpkey_getinfo(3c)

Get information associated with a key handle. Some information is specific to a cryptographic service provider, but the following set of attributes is supported by all providers:

PRINCIPAL
The name of the principal associated with the specified key (key handle). A principal may be a person or a process, depending on how an application developer sets up public key security. Any principal specified in an application's UBBCONFIG file using the SEC_PRINCIPAL_NAME parameter become the identity of one or more system processes. (See Specifying Principal Names and Initializing Decryption Keys Through the Plug-ins for more detail.)
PKENCRYPT_ALG
An ASN.1 Distinguished Encoding Rules (DER) object identifier of the public key algorithm used by the key for public key encryption. See the tpkey_getinfo(3c) reference page for details.
PKENCRYPT_BITS
The key length of the public key algorithm (RSA modulus size). The value must be within the range of 512 to 2048 bits, inclusive.
SIGNATURE_ALG
An ASN.1 DER object identifier of the digital signature algorithm used by the key for digital signature. See the tpkey_getinfo(3c) reference page for details.
SIGNATURE_BITS
The key length of the digital signature algorithm (RSA modulus size). The value must be within the range of 512 to 2048 bits, inclusive.
ENCRYPT_ALG
An ASN.1 DER object identifier of the symmetric key algorithm used by the key for bulk data encryption. See the tpkey_getinfo(3c) reference page for details.
ENCRYPT_BITS
The key length of the symmetric key algorithm. The value must be within the range of 40 to 128 bits, inclusive.
DIGEST_ALG
An ASN.1 DER object identifier of the message digest algorithm used by the key for digital signature. See the tpkey_getinfo(3c) reference page for details.
PROVIDER
The name of the cryptographic service provider.
VERSION
The version number of the cryptographic service provider's software.

tpkey_setinfo(3c)

Set optional attribute parameters associated with a key handle. A core set of key handle attributes is identified in the preceding description of tpkey_getinfo(). Other attributes, specific to a certain cryptographic service provider, may also be available.

tpkey_close(3c)

Close a previously opened key handle. A key handle may be opened explicitly using tpkey_open(), or implicitly (automatically) using tpenvelope().

tpsign(3c)

Mark a typed message buffer for digital signature. The public key software generates the digital signature just before the message is sent.

tpseal(3c)

Mark a typed message buffer for encryption. The public key software encrypts the message just before the message is sent.

tpenvelope(3c)

Access the digital signature and encryption information associated with a typed message buffer. tpenvelope() returns status information about the digital signatures and encryption envelopes attached to a particular message buffer. It also returns the key handle associated with each digital signature or encryption envelope. The key handle for a digital signature identifies the signer, and the key handle for an encryption envelope identifies the recipient of the message.

tpexport(3c)

Convert a typed message buffer into an exportable, machine-independent (externalized) string representation. tpexport() generates any digital signatures or encryption envelopes associated with a typed message buffer just before it converts that buffer into an externalized string representation.

An externalized string representation can be transmitted between processes, machines, or domains through any communication mechanism. It can be archived on permanent storage.

tpimport(3c)

Convert an externalized string representation back into a typed message buffer. During the conversion, tpimport() decrypts the message, if necessary, and verifies any associated digital signatures.

COBOL Routines in ATMI for Public Key Security

Use this routine . . .
To . . .

TPKEYOPEN(3cbl)

Open a key handle for digital signature generation, message encryption, or message decryption. Keys are represented and manipulated via handles. A handle has data associated with it that is used by the ATMI to locate or access the item named by the handle.

A key may play one or more of the following roles:

Signature Generation
The key identifies the calling process as being authorized to generate a digital signature under the principal's identity. (A principal can be a person or a process.) 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
The key represents the principal associated with a digital signature. 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.
Encryption
The key represents the intended principal of an encrypted message. 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; the encryption envelope enables the receiving process to decrypt the message.
Decryption
The key identifies the calling process as being authorized to decrypt a private message for the intended principal. Calling TPKEYOPEN() with the principal's name and the TPKEY-DECRYPT setting returns a handle to the principal's private key and digital certificate.

TPKEYGETINFO(3cbl)

Get information associated with a key handle. Some information is specific to a cryptographic service provider, but the following set of attributes is supported by all providers:

PRINCIPAL
The name of the principal associated with the specified key (key handle). A principal may be a person or a process, depending on how an application developer sets up public key security. Any principal specified in an application's UBBCONFIG file using the SEC_PRINCIPAL_NAME parameter become the identity of one or more system processes. (See Specifying Principal Names and Initializing Decryption Keys Through the Plug-ins for more detail.)
PKENCRYPT_ALG
An ASN.1 Distinguished Encoding Rules (DER) object identifier of the public key algorithm used by the key for public key encryption. See the TPKEYGETINFO(3cbl) reference page for details.
PKENCRYPT_BITS
The key length of the public key algorithm (RSA modulus size). The value must be within the range of 512 to 2048 bits, inclusive.
SIGNATURE_ALG
An ASN.1 DER object identifier of the digital signature algorithm used by the key for digital signature. See the TPKEYGETINFO(3cbl) reference page for details.
SIGNATURE_BITS
The key length of the digital signature algorithm (RSA modulus size). The value must be within the range of 512 to 2048 bits, inclusive.
ENCRYPT_ALG
An ASN.1 DER object identifier of the symmetric key algorithm used by the key for bulk data encryption. See the TPKEYGETINFO(3cbl) reference page for details.
ENCRYPT_BITS
The key length of the symmetric key algorithm. The value must be within the range of 40 to 128 bits, inclusive.
DIGEST_ALG
An ASN.1 DER object identifier of the message digest algorithm used by the key for digital signature. See the TPKEYGETINFO(3cbl) reference page for details.
PROVIDER
The name of the cryptographic service provider.
VERSION
The version number of the cryptographic service provider's software.

TPKEYSETINFO(3cbl)

Set optional attribute parameters associated with a key handle. A core set of key handle attributes is identified in the preceding description of TPKEYGETINFO(). Other attributes, specific to a certain cryptographic service provider, may also be available.

TPKEYCLOSE(3cbl)

Close a key handle previously opened using TPKEYOPEN().

Use this function . . .	To . . .
tpkey_open(3c)	Open a key handle for digital signature generation, message encryption, or message decryption. Keys are represented and manipulated via handles. A handle has data associated with it that is used by the ATMI to locate or access the item named by the handle. A key may play one or more of the following roles: Signature Generation The key identifies the calling process as being authorized to generate a digital signature under the principal's identity. (A principal may be a person or a process.) Calling tpkey_open() with the principal's name and either the TPKEY_SIGNATURE or TPKEY_AUTOSIGN flag returns a handle to the principal's private key and digital certificate. Signature Verification The key represents the principal associated with a digital signature. Signature verification does not require a call to tpkey_open(); the verifying process uses the public key specified in the digital certificate accompanying the digitally signed message to verify the signature. Encryption The key represents the intended principal of an encrypted message. Calling tpkey_open() with the principal's name and either the TPKEY_ENCRYPT or TPKEY_AUTOENCRYPT flag returns a handle to the principal's public key via the principal's digital certificate. Decryption The key identifies the calling process as being authorized to decrypt a private message for the intended principal. Calling tpkey_open() with the principal's name and the TPKEY_DECRYPT flag returns a handle to the principal's private key and digital certificate.
tpkey_getinfo(3c)	Get information associated with a key handle. Some information is specific to a cryptographic service provider, but the following set of attributes is supported by all providers: PRINCIPAL The name of the principal associated with the specified key (key handle). A principal may be a person or a process, depending on how an application developer sets up public key security. Any principal specified in an application's UBBCONFIG file using the SEC_PRINCIPAL_NAME parameter become the identity of one or more system processes. (See Specifying Principal Names and Initializing Decryption Keys Through the Plug-ins for more detail.) PKENCRYPT_ALG An ASN.1 Distinguished Encoding Rules (DER) object identifier of the public key algorithm used by the key for public key encryption. See the tpkey_getinfo(3c) reference page for details. PKENCRYPT_BITS The key length of the public key algorithm (RSA modulus size). The value must be within the range of 512 to 2048 bits, inclusive. SIGNATURE_ALG An ASN.1 DER object identifier of the digital signature algorithm used by the key for digital signature. See the tpkey_getinfo(3c) reference page for details. SIGNATURE_BITS The key length of the digital signature algorithm (RSA modulus size). The value must be within the range of 512 to 2048 bits, inclusive. ENCRYPT_ALG An ASN.1 DER object identifier of the symmetric key algorithm used by the key for bulk data encryption. See the tpkey_getinfo(3c) reference page for details. ENCRYPT_BITS The key length of the symmetric key algorithm. The value must be within the range of 40 to 128 bits, inclusive. DIGEST_ALG An ASN.1 DER object identifier of the message digest algorithm used by the key for digital signature. See the tpkey_getinfo(3c) reference page for details. PROVIDER The name of the cryptographic service provider. VERSION The version number of the cryptographic service provider's software.
tpkey_setinfo(3c)	Set optional attribute parameters associated with a key handle. A core set of key handle attributes is identified in the preceding description of tpkey_getinfo(). Other attributes, specific to a certain cryptographic service provider, may also be available.
tpkey_close(3c)	Close a previously opened key handle. A key handle may be opened explicitly using tpkey_open(), or implicitly (automatically) using tpenvelope().
tpsign(3c)	Mark a typed message buffer for digital signature. The public key software generates the digital signature just before the message is sent.
tpseal(3c)	Mark a typed message buffer for encryption. The public key software encrypts the message just before the message is sent.
tpenvelope(3c)	Access the digital signature and encryption information associated with a typed message buffer. tpenvelope() returns status information about the digital signatures and encryption envelopes attached to a particular message buffer. It also returns the key handle associated with each digital signature or encryption envelope. The key handle for a digital signature identifies the signer, and the key handle for an encryption envelope identifies the recipient of the message.
tpexport(3c)	Convert a typed message buffer into an exportable, machine-independent (externalized) string representation. tpexport() generates any digital signatures or encryption envelopes associated with a typed message buffer just before it converts that buffer into an externalized string representation. An externalized string representation can be transmitted between processes, machines, or domains through any communication mechanism. It can be archived on permanent storage.
tpimport(3c)	Convert an externalized string representation back into a typed message buffer. During the conversion, tpimport() decrypts the message, if necessary, and verifies any associated digital signatures.

Use this routine . . .	To . . .
TPKEYOPEN(3cbl)	Open a key handle for digital signature generation, message encryption, or message decryption. Keys are represented and manipulated via handles. A handle has data associated with it that is used by the ATMI to locate or access the item named by the handle. A key may play one or more of the following roles: Signature Generation The key identifies the calling process as being authorized to generate a digital signature under the principal's identity. (A principal can be a person or a process.) 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 The key represents the principal associated with a digital signature. 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. Encryption The key represents the intended principal of an encrypted message. 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; the encryption envelope enables the receiving process to decrypt the message. Decryption The key identifies the calling process as being authorized to decrypt a private message for the intended principal. Calling TPKEYOPEN() with the principal's name and the TPKEY-DECRYPT setting returns a handle to the principal's private key and digital certificate.
TPKEYGETINFO(3cbl)	Get information associated with a key handle. Some information is specific to a cryptographic service provider, but the following set of attributes is supported by all providers: PRINCIPAL The name of the principal associated with the specified key (key handle). A principal may be a person or a process, depending on how an application developer sets up public key security. Any principal specified in an application's UBBCONFIG file using the SEC_PRINCIPAL_NAME parameter become the identity of one or more system processes. (See Specifying Principal Names and Initializing Decryption Keys Through the Plug-ins for more detail.) PKENCRYPT_ALG An ASN.1 Distinguished Encoding Rules (DER) object identifier of the public key algorithm used by the key for public key encryption. See the TPKEYGETINFO(3cbl) reference page for details. PKENCRYPT_BITS The key length of the public key algorithm (RSA modulus size). The value must be within the range of 512 to 2048 bits, inclusive. SIGNATURE_ALG An ASN.1 DER object identifier of the digital signature algorithm used by the key for digital signature. See the TPKEYGETINFO(3cbl) reference page for details. SIGNATURE_BITS The key length of the digital signature algorithm (RSA modulus size). The value must be within the range of 512 to 2048 bits, inclusive. ENCRYPT_ALG An ASN.1 DER object identifier of the symmetric key algorithm used by the key for bulk data encryption. See the TPKEYGETINFO(3cbl) reference page for details. ENCRYPT_BITS The key length of the symmetric key algorithm. The value must be within the range of 40 to 128 bits, inclusive. DIGEST_ALG An ASN.1 DER object identifier of the message digest algorithm used by the key for digital signature. See the TPKEYGETINFO(3cbl) reference page for details. PROVIDER The name of the cryptographic service provider. VERSION The version number of the cryptographic service provider's software.
TPKEYSETINFO(3cbl)	Set optional attribute parameters associated with a key handle. A core set of key handle attributes is identified in the preceding description of TPKEYGETINFO(). Other attributes, specific to a certain cryptographic service provider, may also be available.
TPKEYCLOSE(3cbl)	Close a key handle previously opened using TPKEYOPEN().

Recommended Uses of Public Key Security

Use tpkey_close() to release key handles used for digital signature generation or for data decryption as soon as they are no longer needed.
To inhibit replay attacks, generate digital signatures only on message buffers that contain details identifying a specific operation. For example, a buffer that contains the message "Your deposit is confirmed" is dangerously vague. An attacker who intercepts such a message can easily re-use it. On the other hand, a message that contains many operation-specific details is much safer. An attacker who intercepts a message such as the one that follows will not be able to re-use it easily: "John Smith's deposit of $100.00, account 987654321, confirmation code 123456789, 7/31/2001, is confirmed."