Parameters

The parameters for CSNBFFXE.

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

The number of keywords you supplied in the rule_array parameter. The value must be 3.

rule_array


Direction:	Input
Type:	String

The rule_array contains keywords that provide control information to the callable service. The keywords must be in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on the right with blanks.

Table 1. Rule array keywords for Format Preserving Algorithms Encipher control information
Rule array keywords for Format Preserving Algorithms Encipher control information. This table contains two columns: Keyword and Meaning, and it contains rows for Encryption method format (one, required), Encryption Algorithm process (one, required), and Alphabet (one, required).
Keyword	Description
*Encryption method format (one, required)*
FF1	Specifies to use the FPE FF1 algorithm to encrypt the data (original FFX).
FF2	Specifies to use the FPE FF2 algorithm to encrypt the data (original VAES).
FF2.1	Specifies to use the FPE FF2.1 algorithm to encrypt the data (new version of VAES).
*Encryption Algorithm process (one, required)*
AES	Speciﬁes use of the AES ciphering algorithm.
*Alphabet (one, required)*
BASE10	Specifies that the input data will be 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 ENCRYPT 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 E

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 encryption 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 encryption 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 encryption calculations. When the alphabet_length is zero, this parameter is ignored.

plaintext_length


Direction:	Input
Type:	Integer

Specifies the length in bytes of the plaintext 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:

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

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

104/log2(10) = 31

plaintext


Direction:	Input
Type:	String

The input clear text.

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.

ciphertext_length


Direction:	Input/Output
Type:	Integer

Specifies the length in bytes of the ciphertext parameter.

On input, the value is the size of the buffer to receive the output ciphertext. The value must be at least the same the plaintext_length.

On output, the value is the length of the data returned in the ciphertext parameter.

ciphertext


Direction:	Output
Type:	String

The enciphered text returned.