Parameters

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

key_identifier

Direction:	Input/Output
Type:	String

A string that is the internal CCA or TR-31 key token containing the data-encrypting key or the label of such a key in key storage to be used for deciphering the data. If the key is a CCA token, then it must be 64 bytes. For TR-31 tokens, it can be up to 9992 bytes. If the key token or key label contains a single-length key, single-DES decryption is performed. If the key token or key label contains a double-length or triple-length key, triple-DES decryption is performed.

Double length CIPHER and DECIPHER keys are also supported.

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

• TR-31 key usage: D0
• Algorithm: D or T
• TR-31 mode of key use: B or D

text_length

Direction:	Input/Output
Type:	Integer

On entry, you supply the length of the ciphertext. The maximum length of text is 214,783,647 bytes. A zero value for the text_length parameter is not valid. If the returned deciphered text (clear_text parameter) is a different length because of the removal of padding bytes, the value is updated to the length of the plaintext.

The application program passes the length of the ciphertext to the verb. The verb returns the length of the plaintext to your application program.

cipher_text

Direction:	Input
Type:	String

The text to be deciphered.

initialization_vector

Direction:	Input
Type:	String

The 8-byte supplied string for the cipher block chaining. The first block of the ciphertext is deciphered and XORed with the initial chaining vector (ICV) to get the first block of cleartext. The input block is the next ICV. To decipher the data, you must use the same ICV used when you enciphered the data.

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 1, 2, or 3.

rule_array

Direction:	Input
Type:	String array

An array of 8-byte keywords providing the processing control information. The array is positional. The first keyword in the array is the processing rule. You choose the processing rule you want the verb to use for deciphering the data. The second keyword is the ICV selection keyword. The third keyword (or the second if the ICV selection keyword is allowed to default) is the encryption algorithm to use. The rule_array keywords are described in Table 1.

Table 1. Keywords for Decipher control information

Keywords for Decipher control information

Keyword	Description
Processing Rule (One, required)
CBC	Performs ANSI X3.102 cipher block chaining. The data must be a multiple of eight bytes. An OCV is produced and placed in the chaining_vector parameter. If the ICV selection keyword CONTINUE is specified, the CBC OCV from the previous call is used as the ICV for this call.
CUSP	Performs Cryptographic Unit Support Program (CUSP) cipher block chaining.
IPS	Performs Information Protection System (IPS) cipher block chaining.
X9.23	Deciphers with cipher block chaining and text length reduced to the original value. This is compatible with the requirements in ANSI standard X9.23. The ciphertext length must be an exact multiple of eight bytes. Padding is removed from the plaintext.
ICV Selection (One, optional)
CONTINUE	This specifies taking the initialization vector from the output chaining vector (OCV) contained in the work area to which the chaining_vector parameter points. CONTINUE is valid only for the CBC processing rule.
INITIAL	This specifies taking the initialization vector from the initialization_vector parameter. INITIAL is the default value.
Encryption algorithm (Optional)
DES	This specifies using the data encryption standard and ignoring the token marking.

Ciphering methods describes the cipher processing rules in detail.

chaining_vector

Direction:	Input/Output
Type:	String

An 18-byte field CCA uses as a system work area. Your application program must not change the data in this string. The chaining vector holds the output chaining vector (OCV) from the caller. The OCV is the first eight bytes in the 18-byte string.

The direction is Output if the ICV selection keyword of the rule_array parameter is INITIAL. The direction is Input/Output if the ICV selection keyword of the rule_array parameter is CONTINUE.

clear_text

Direction:	Output
Type:	String

The field where the verb returns the deciphered text.