Parameters

Edit online

The parameters for CSNBFPEE.

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 minimum value is 5. The maximum value is 10.
rule_array
Direction: Input
Type: String array
Keywords that provide control information to the verb. The rule_array keywords are described in Table 1.
Note: At least one character set keyword is required.
Table 1. Keywords for CSNBFPEE control information

Keywords for CSNBFPEE control information
Keyword Description
Processing method (required)
VMDS Specifies that the VDSP method (Visa Data Secure Platform method, formally known as the Visa Merchant Data Secure (VMDS) method) is to be used for processing.
Key management method (one required)
STATIC Specifies the use of double length (2-key) triple-DES symmetric keys. This is a non-DUKPT key.
DUKPT Specifies the use of the transaction unique general purpose Data Encryption Keys generated by the DUKPT process at the point of service for data encryption. This is required if VFPE mode is specified. Otherwise, this is optional.

Both DES DUKPT and AES DUKPT key derivation methods are supported. The content of the derivation_data parameter determines which DUKPT method is used.
Algorithm (required)
TDES Specifies the use of CBC mode triple-DES encryption.
Mode (one required)
CBC Specifies the use of CBC mode. This is the mode for the standard encryption option.
VFPE Specifies the use of Visa format preserving encryption.
PAN input output character set (one required if the clear_PAN_length variable is greater than 0. Otherwise, it is not allowed.)
PAN8BITA Specifies that the PAN data character set is BASE-10 ASCII represented in binary form. Valid ASCII values are in the range 0 - 9 (X'30' - X'39').
PAN4BITX Specifies that the PAN data character set is BASE-10 4-bit hex with two digits per byte. Valid 4-bit hexadecimal values are in the range X'0' - X'9'.
Cardholder name input output character set (required if the clear_cardholder_name_length variable is greater than 0. Otherwise, it is not allowed.)
CN8BITA Specifies that the cardholder name character set is ASCII represented in binary format, one character per byte. See Table 1 for valid characters.
Track_1 input output character set (required if the clear_dtrack1_data_length variable is greater than 0. Otherwise, it is not valid.)
TK18BITA Specifies that the track 1 discretionary data character set is ASCII represented in binary format, one character per byte. See Table 1 for valid characters.
Track_2 input output character set (required if the clear_dtrack2_data_length variable is greater than 0. Otherwise, it is not valid.)
TK28BITA Specifies that the track 2 discretionary data character set is ASCII represented in binary format, one character per byte. Valid ASCII values are in the range 0 - 9 (X'30' - X'39') and A - F (X'41' - X'46').
PIN encryption key output selection (one, optional)
NOPINKEY Do not return a DUKPT PIN encryption key. This is the default.
PINKEY Return a DUKPT PIN encryption key.
PAN check digit compliance (one required if mode VFPE and the pan input output character set keyword is present. Otherwise, it is not allowed.)
CMPCKDGT Last digit of the PAN contains a compliant check digit per ISO/IEC 7812-1.
NONCKDGT Last digit of the PAN does not contain a compliant check digit per ISO/IEC 7812-1.
clear_PAN_length
Direction: Input
Type: Integer
Specifies the number of digits in the clear_PAN parameter. This value must be 0 if clear_PAN is not to be enciphered. The value must be in the range 15 - 19 if PAN data is presented for encryption.
clear_PAN
Direction: Input
Type: String
Contains the account number with which the PIN is associated. The full account number, including check digit, should be included. The data for this parameter is in binary format. It is the binary representation of 4-bit hex (keyword PAN4BITX) or ASCII (keyword PAN8BITA). If the PAN contains an odd number of 4-bit digits, the data must be left justified in the PAN variable and the right-most 4 bits are ignored.

If the clear_PAN_length parameter is zero, this parameter is ignored.

clear_cardholder_name_length
Direction: Input
Type: Integer
Specifies the length of the clear_cardholder_name parameter in bytes. This value must be 0 if the cardholder name is not to be enciphered. The value must be in the range 2 - 32 if the cardholder name data is presented for encryption.
clear_cardholder_name
Direction: Input
Type: String
Contains the card holder's full name. The data for this parameter is in binary format. It is the binary representation of ASCII characters as defined in Table 3. Only characters from this table are valid.
clear_dtrack1_data_length
Direction: Input
Type: Integer
Specifies the length of the clear_dtrack1_data parameter in bytes. This value must be 0 if the track 1 discretionary data is not to be enciphered. The value must be in the range 1 - 56 if the track 1 discretionary data is presented for encryption.
clear_dtrack1_data
Direction: Input
Type: String
Contains the discretionary data that is stored on track 1 of a magnetic stripe card. This data does not include the PAN, cardholder name, expiration date, or service code. The data for this parameter is in binary format. It is the binary representation of ASCII characters as defined in Table 3. Only characters defined in this table are valid.
clear_dtrack2_data_length
Direction: Input
Type: Integer
Specifies the length of the clear_dtrack2_data parameter in bytes. This value must be 0 if the track 2 discretionary data is not to be enciphered. The value must be in the range 1 - 19 if the track 2 discretionary data is presented for encryption.
clear_dtrack2_data
Direction: Input
Type: String
Contains the discretionary data that is stored on track 2 of a magnetic stripe card. This data does not include the PAN, expiration date, or service code. The data for this parameter is in binary format. It is the binary representation of ASCII characters. The data for this parameter is in BASE-16 binary format. It is the binary representation of ASCII in the range X'30' - X'39' and X'41' - X'46' (ASCII: 0 - 9 and A - F).
key_identifier_length
Direction: Input
Type: Integer
Specifies the length of the key_identifier parameter in bytes.

When DES DUKPT method is specified, set the value to 64 for a CCA token, or up to 9992 for a TR-31 token. When AES DUKPT method is used the maximum value is 3500 for a CCA token, and 9992 for a TR-31 token.

key_identifier
Direction: Input/Output
Type: String
The identifier of the key that is used to either encrypt the card data (key management STATIC) or derive the DUKPT_PIN_key_identifer (key management DUKPT). The key identifier is an operational token or the key label of an operational token in key storage.

For the DES-DUKPT key derivation method, the base derivation key is the one from which the operational keys are derived using the DUKPT algorithm defined in ANS X9.24-1 2017 (Part 1). If the key is a CCA token, then the key type must be KEYGENKY. In addition, it must have a control vector with bit 18 equal to B'1' (UKPT).

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

  • TR-31 key usage: B0
  • Algorithm: T
  • TR-31 mode of key use: X

For the AES-DUKPT key derivation method, the BDK is the one from which the operational keys are derived using the DUKPT algorithm defined in ANSI x9.24-3 2017. If the key is a CCA token, then it is an AES DKYGENKY with the A-DUKPT bit set to 1 in the low-order byte of key usage field 1, indicating this key is allowed to be used as base derivation key (BDK).

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

  • TR-31 key usage: B0
  • Algorithm: A
  • TR-31 mode of key use: X

For key management STATIC, (Zone Encryption Key in the VDSP specification), the key type must be either a CCA DES CIPHER or ENCIPHER key, or a TR-31 key with the following attributes:

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

For production purposes, it is recommended that the key have left and right halves that are not equal.

Note: Data keys are not supported.

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

derivation_data_length
Direction: Input
Type: Integer
Specifies the length of the derivation_data parameter in bytes. To specify the DES DUKPT method, set the value to 10 if the key management method DUKPT is specified in the rule array. To specify the AES DUKPT method, set the value to 20 if the key management method DUKPT is specified in the rule array. Otherwise, this value must be 0.
derivation_data
Direction: Input
Type: String
When specifying the DES-DUKPT method, the derivation_data parameter contains the 80 bit (10 byte) derivation data that is used as input to the DUKPT derivation process. The derivation data contains the current key serial number (CKSN), which is composed of the 59 bit initial key serial number concatenated with the 21 bit value of the current encryption counter, which the device increments for each new transaction. This field is in binary format.
When specifying the AES DUKPT method, parameter derivation_data contains the 20 byte AES DUKPT derivation data. See Table 1 for the layout of the AES DUKPT derivation data. The algorithm indicator must be set to X'0000' (2- key TDES). The key usage indicator must be set to X'1000' (PIN Encryption).
enc_PAN_length
Direction: Input
Type: Integer
Specifies the number of PAN digits in the enc_PAN parameter. This value must either be 0 or in the range 15 - 19, inclusive on output.
enc_PAN
Direction: Output
Type: String
This parameter returns the enciphered primary account number. For VFPE mode, if the PAN contains an odd number of 4-bit digits, the data is left-justified in the PAN variable and the right-most 4 bits can be ignored.
enc_cardholder_name_length
Direction: Input/Output
Type: Integer
Specifies the length of the enc_cardholder_name parameter in bytes. This output value is either 0 or in the range 2 - 32 for VFPE. For CBC mode, the output value is in the range 16 - 40 and a multiple of 8 if the service is successful and cardholder name data is enciphered. The parameter can be larger on input. However, on output, this length is updated to indicate the actual number of bytes returned by the service.
enc_cardholder_name
Direction: Output
Type: String
The field where the enciphered cardholder full name is returned.
enc_dtrack1_data_length
Direction: Input/Output
Type: Integer
Specifies the length of the enc_dtrack1_data parameter in bytes. The output value is either 0 or in the range 1 - 56 for mode VFPE. For mode CBC, the output value is in the range16 - 64 and a multiple of 8 if the service is successful and the track 1 discretionary data is enciphered. The parameter can be larger on input. However, on output, this length is updated to indicate the actual number of bytes returned by the service.
enc_dtrack1_data
Direction: Output
Type: String
This parameter returns the enciphered discretionary track 1 data.
enc_dtrack2_data_length
Direction: Input/Output
Type: Integer
Specifies the length of the enc_dtrack2_data parameter in bytes. The output value is either 0 or in the range 1 - 19 for mode VFPE. For mode CBC, the output value is 8 or 16 if the service is successful and the data is enciphered. The parameter can be larger on input. However, on output, this length is updated to indicate the actual number of bytes returned by the service.
enc_dtrack2_data
Direction: Output
Type: String
This parameter returns the enciphered discretionary track 2 data.
DUKPT_PIN_key_identifier_length
Direction: Input/Output
Type: Integer
Specifies the length of the DUKPT_PIN_key_identifier parameter in bytes. If the PINKEY rule-array keyword is specified, set this value to 64 for a CCA token, and up to 9992 for a TR-31 token. Otherwise, set this value to 0. On output, the variable is updated with the length of the data returned in the DUKPT_PIN_key_identifier variable.
DUKPT_PIN_key_identifier
Direction: Input/Output
Type: String
On input, this parameter must contain either a CCA or TR-31 skeleton token. For a CCA token, it must be a DES OPINENC or IPINENC skeleton token. On output, it contains the DES token with the derived DES OPINENC or IPINENC key.

For a TR-31 token, it must be a DES skeleton token with the following attributes:

  • TR-31 key usage: P0
  • Algorithm: T
  • TR-31 mode of key use: B, D, or E

On output, it contains the TR-31 DES token with the newly derived key.

reserved1_length
Direction: Input
Type: Integer
Specifies the length of the reserved1 parameter in bytes. The value must be 0.
reserved1
Direction: Input
Type: String
This parameter is ignored.
reserved2_length
Direction: Input
Type: Integer
Length of the reserved2 parameter in bytes. The value must be 0.
reserved2
Direction: Input
Type: String
This parameter is ignored.