Parameters

For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.

rule_array_count

Direction:	Input
Type:	Integer

A pointer to an integer variable containing the number of elements in the rule_array variable. This value must be 0 or 1.

rule_array

Direction:	Input
Type:	String array

Keywords that provide control information to the verb. The processing method is the encryption mode used to encrypt the message. The rule_array keywords are described in Table 1.

Table 1. Keywords for Secure Messaging for Keys control information

Keywords for Secure Messaging for Keys control information

Keyword	Description
Enciphering mode (One, optional)
TDES-CBC	Use CBC mode to encipher the message. This is the default.
TDES-ECB	Use EBC mode to encipher the message.

input_key_identifier

Direction:	Input/Output
Type:	String

The internal or external CCA or TR-31 token, or the key label of an internal CCA or TR-31 token of a double length DES key. The key is recovered in the clear and placed in the text to be encrypted. For a CCA key, the control vector of the DES key must not prohibit export.

For a TR-31 key, it must have the following attributes:

• TR-31 key usage: * (any key usage)
• Algorithm: D or T
• TR-31 mode of key use: * (any mode of key use)
• Exportable: E or S

key_encrypting_key_identifier

Direction:	Input/Output
Type:	String

If the input_key_identifier parameter contains an internal token, then this parameter is a null token. If the input_key_identifier parameter contains an external token, this parameter is the internal CCA or TR-31 token or the key label of such a token that is used to decipher the input_key_identifier. For a CCA token, it must be an IMPORTER or EXPORTER.

For a TR-31 token, it must have the following attributes:

• TR-31 key usage: K0 or K1
• Algorithm: T
• TR-31 mode of key use: D or E

Note: Use K0 key usage if input_key_identifier is a CCA token. Otherwise use K1 if input_key_identifier is a TR-31 token.

If a key label is specified, the key label must be unique.

secmsg_key_identifier

Direction:	Input/Output
Type:	String

The internal CCA or TR-31 token or key label of a secure message key for encrypting keys. This key is used to encrypt the updated clear_text containing the recovered DES key.

For a TR-31 key token, it must have the following attributes:

• TR-31 key usage: K0
• Algorithm: T
• TR-31 mode of key use: E

text_length

Direction:	Input
Type:	Integer

The length of the clear_text parameter. Length must be a multiple of eight. Maximum length is 4096.

clear_text

Direction:	Input
Type:	String

Cleartext that contains the recovered DES key at the offset specified and is then encrypted. Any padding or formatting of the message must be done by the caller on input.

initialization_vector

Direction:	Input
Type:	String

The 8-byte supplied string for the TDES-CBC mode of encryption. The initialization_vector is XORed with the first eight bytes of clear_text before encryption. This field is ignored for TDES-ECB mode.

key_offset

Direction:	Input
Type:	Integer

The offset within the clear_text parameter at key_offset where the recovered clear input_key_identifier value is to be placed. The first byte of the clear_text field is offset 0.

key_offset_field_length

Direction:	Input
Type:	Integer

The length of the field within clear_text parameter at key_offset where the recovered clear input_key_identifier value is to be placed. Length must be a multiple of eight and is equal to the key length of the recovered key. The key must fit entirely within the clear_text.

enciphered_text

Direction:	Output
Type:	String

The field where the ciphertext is returned. The length of this field must be at least as long as the clear_text field.

output_chaining_vector

Direction:	Output
Type:	String

This field contains the last eight bytes of enciphered text and is used as the initialization_vector for the next encryption call if data needs to be chained for TDES-CBC mode. No data is returned for TDES-ECB.