Parameters

Edit online

The parameters for CSNBFFXT.

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

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

rule_array

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 Translate control information
Keyword Description
Input ciphertext format (one, required)
ICFF1 Specifies the input ciphertext was encrypted using FPE FF1 algorithm (original FFX).
ICFF2 Specifies the input ciphertext was encrypted using FPE FF2 algorithm (original VAES).
ICFF2.1 Specifies the input ciphertext was encrypted using FPE FF2.1 algorithm (new version of VAES).
Output ciphertext format (one, required)
OCFF1 Specifies the data is to be encrypted using FPE FF1 algorithm (original FFX).
OCFF2 Specifies the data is to be encrypted using FPE FF2 algorithm (original VAES).
OCFF2.1 Specifies the data is to be encrypted using FPE FF2.1 algorithm (new version of VAES).
Encryption Algorithm process (one, required)
AES Specifies use of the AES ciphering algorithm.
Input alphabet (one, required)
I-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.
I-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.
Output alphabet (one, required)
O-BASE10 Specifies that the output 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.
O-CUSTOM Specifies that the caller can provide the alphabet for the output data as well as the tweak. The tweak alphabet is optional. The output data, tweak, and alphabets are ASCII character sets.
input_key_identifier_length

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

input_key_identifier

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 ICFF1 keyword is specified, this key can be either a 128-bit or a 256-bit key. When the ICFF2 or ICFF2.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.

output_key_identifier_length

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

output_key_identifier

The identifier of the key to encrypt the plain 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 OCFF1 keyword is specified, this key can be either a 128-bit or a 256-bit key. When the OCFF2 or OCFF2.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.

input_tweak_length
Specifies the length in bytes of the input_tweak parameter.
For the ICFF1 keyword
The value can be between 0 and 512 inclusive.
For the ICFF2 or ICFF2.1 keyword
Minimum can be 0 and the maximum must satisfy this formula depending on the input_tweak_alphabet_length value:
(input_tweak _length x lg2(input_tweak_alphabet_length)) <= (15 – 2) x 8
input_tweak

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

input_tweak_alphabet_length

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

When the I-CUSTOM keyword is specified:
For the ICFF1 keyword
The value must be 256.
For the ICFF2 or ICFF2.1 keyword
The value must be between 8 and 256 inclusive.
input_tweak_alphabet

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

input_alphabet_length

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

input_alphabet

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

output_tweak_length
Specifies the length in bytes of the output_tweak parameter.
For the OCFF1 keyword
The value can be between 0 and 512 inclusive.
For the OCFF2 or OCFF2.1 keyword
Minimum can be 0 and the maximum must satisfy this formula depending on the output_tweak_alphabet_length value:
(output_tweak _length x lg2(output_tweak_alphabet_length)) <= (15 – 2) x 8
output_tweak

The data to be used as the tweak value in the output encryption calculations. When the output_tweak_length is zero, this parameter is ignored.

output_tweak_alphabet_length

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

When the O-CUSTOM keyword is specified:
For the OCFF1 keyword
The value must be 256.
For the OCFF2 or OCFF2.1 keyword
The value must be between 8 and 256 inclusive.
output_tweak_alphabet

The tweak alphabet data to be used in the output encryption calculations. When the output_tweak_alphabet_length is zero, this parameter is ignored.

output_alphabet_length

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

output_alphabet

The alphabet data to be used in the output encryption calculations. When the output_alphabet_length is zero, this parameter is ignored.

reserved1_length

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

reserved1

This parameter is ignored.

reserved2_length

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

reserved2

This parameter is ignored.

ciphertext_length
Specifies the length in bytes of the ciphertext parameter. On input, the value is the length the input ciphertext. On output, the value is the length of the data returned in the ciphertext parameter.
For the OCFF1 keyword
The value must be between 2 and 504 inclusive.
For the OCFF2 or OCFF2.1 keyword
The minimum is 2 and the maximum must satisfy this formula depending on the output_alphabet_length value:
(ciphertext_length x lg2(output_alphabet_length))/2 <= (15-1) x 8
For example, when the output_alphabet_length is 10, the maximum ciphertext_length is 31.
104/log2(10) = 31
ciphertext

The enciphered text to be processed.