Parameters

The parameters for CSNBFFXD.

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. The value must be 3.

rule_array


Direction:	Input
Type:	String array

Keywords that provide control information to the verb. The rule_array keywords are described in Table 1.

Table 1. Keywords for Format Preserving Algorithms Decipher control information
Keywords for Format Preserving Algorithms Decipher control information
Keyword	Description
*Encryption method format* (one required)
FF1	Specifies to use the FPE FF1 algorithm to decrypt the data (original FFX).
FF2	Specifies to use the FPE FF2 algorithm to decrypt the data (original VAES).
FF2.1	Specifies to use the FPE FF2.1 algorithm to decrypt the data (new version of VAES).
*Encryption algorithm* (one required)
AES	Specifies to use the AES ciphering algorithm.
*Alphabet* (one required)
BASE10	Specifies that the input data is only BASE-10 ASCII represented in binary form. Valid ASCII values are '0' through '9' (X'30' through X'39'). This applies to the tweak as well as the alphabet.
CUSTOM	Specifies that the caller can provide the alphabet for the input data as well as the tweak. The tweak alphabet is optional. The input data, tweak, and alphabets are ASCII character sets.

key_identifier_length


Direction:	Input
Type:	Integer

Specifies the length in bytes of the key_identifier parameter. If the key_identifier contains a label, the length must be 64. Otherwise, the value must be between the actual length of the token and 9992.

key_identifier


Direction:	Input/Output
Type:	String

The identifier of the key to decrypt the clear text. The key identifier is an operational token or the key label of an operational token in key storage. For a CCA token, the key must be an AES CIPHER key with key attributes DECRYPT and the desired enciphering mode of FF1, FF2, or FF2.1.

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

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

When the FF1 keyword is specified, this key can be either a 128-bit or a 256-bit key. When the FF2 or FF2.1 keyword is specified, this key must be a 128-bit key.

If the token supplied was encrypted under the old master key, the token is returned encrypted under the current master key.

tweak_length


Direction:	Input
Type:	Integer

Specifies the length in bytes of the tweak parameter.

For the FF1 keyword

The value can be between 0 and 512 inclusive.

For the FF2 or FF2.1 keyword

Minimum can be 0 and the maximum must satisfy this formula depending on the tweak_alphabet_length value:

(tweak _length x lg2(tweak_alphabet_length)) <= (15 – 2) x 8

tweak


Direction:	Input
Type:	String

The data to be used as the tweak value in the decryption calculations. When the tweak_length is zero, this parameter is ignored.

tweak_alphabet_length


Direction:	Input
Type:	Integer

Specifies the length in bytes of the tweak_alphabet parameter. The value must be zero when the BASE10 keyword is specified.

When the CUSTOM keyword is specified:

For the FF1 keyword: The value must be 256.

For the FF2 or FF2.1 keyword: The value must be between 8 and 256 inclusive.

tweak_alphabet


Direction:	Input
Type:	String

The tweak alphabet data to be used in the decryption calculations. When the tweak_alphabet_length is zero, this parameter is ignored.

alphabet_length


Direction:	Input
Type:	Integer

Specifies the length in bytes of the alphabet parameter. The value must be zero when the BASE10 keyword is specified. Otherwise, the value may be zero or between 8 and 256 inclusive.

alphabet


Direction:	Input
Type:	String

The alphabet data to be used in the decryption calculations. When the alphabet_length is zero, this parameter is ignored.

ciphertext_length


Direction:	Input
Type:	Integer

Specifies the length in bytes of the ciphertext parameter.

For the FF1 keyword

The value must be between 2 and 504.

For the FF2 or FF2.1 keyword

The minimum is 2 and the maximum must satisfy this formula depending on the alphabet_length value:

(ciphertext_length * lg2(alphabet_length))/2 <= (15-1) * 8

For example, when the alphabet_length is 10, the maximum ciphertext_length is 31.

104/log2(10) = 31

ciphertext


Direction:	Input
Type:	String

The encrypted text to be decrypted.

reserved1_length


Direction:	Input
Type:	Integer

Length in bytes of the reserved1 parameter. The value must be 0.

reserved1


Direction:	Input/Output
Type:	String

This parameter is ignored.

reserved2_length


Direction:	Input
Type:	Integer

Length in bytes of the reserved2 parameter. The value must be 0.

reserved2


Direction:	Input/Output
Type:	String

This parameter is ignored.

plaintext_length


Direction:	Input/Output
Type:	Integer

Specifies the length in bytes of the plaintext parameter. On input, the value is the size of the buffer to receive the output plaintext. The value must be at least the same as the ciphertext_length. On output, the value is the length of the data returned in the plaintext parameter.

plaintext


Direction:	Output
Type:	String

The deciphered text returned.