FPE decipher (CSNBFPED and CSNEFPED)

The FPE decipher callable service is used to decrypt payment card data for the Visa Data Secure Platform (Visa DSP) processing. This service supports two options:

The standard encryption option.
The Visa Format Preserving Encryption (VFPE) option.

If the standard encryption option was selected, the plain text data was formatted into blocks and then encrypted with triple-DES encryption with a static TDES key or a DUKPT double length data encryption key. For the decryption operation, the data blocks must be decrypted and unblocked to produce the plaintext. If the data was encrypted with the VFPE option, the data was encrypted in place without changing the data type or length of the field and DUKPT key management is used.

This service can be used to decrypt one or all of the following fields: the primary account number (PAN), the cardholder name, the track 1 discretionary data, or the track 2 discretionary data.

There are three decryption options:

Decrypt standard option with CBC mode TDES and DUKPT keys.
Decrypt VFPE option with DUKPT keys.
Decrypt standard option with CBC mode TDES and double-length TDES keys.

To use this service, you must specify the following:

The processing method, which is limited to Visa Data Secure Platform (Visa DSP).
The key management method, either STATIC or DUKPT.
The algorithm, which is limited to TDES.
The mode, either CBC or Visa Format Preserving Encryption (VFPE).
The plaintext to be decrypted.
The character set of each field to be decrypted using rule-array keywords.
The base derivation key and key serial number if DUKPT key management is used, or a double-length TDES key if STATIC key management is used.
A compliance or non-compliance indicator for the check digit of the PAN to be processed if VFPE is specified.

The service returns the decrypted fields and optionally, the DUKPT PIN key, if the DUKPT key management is selected and the PINKEY rule is specified.

The callable service name for AMODE(64) invocation is CSNEFPED.

Format

CALL CSNBFPED(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             enc_PAN_length,
             enc_PAN,
             enc_CH_name_length,
             enc_CH_name,
             enc_dtrack1_data_length,
             enc_dtrack1_data,
             enc_dtrack2_data_length,
             enc_dtrack2_data,
             key_identifier_length,
             key_identifier,
             derivation_data_length,
             derivation_data,
             clear_PAN_length,
             clear_PAN,
             clear_CH_name_length,
             clear_CH_name,
             clear_dtrack1_data_length,
             clear_dtrack1_data,
             clear_dtrack2_data_length,
             clear_dtrack2_data,
             DUKPT_PIN_key_identifier_length,
             DUKPT_PIN_key_identifier,
             reserved1_length,
             reserved1,
             reserved2_length,
             reserved2)

Parameters

return_code

Direction	Type
Output	Integer

The return code specifies the general result of the callable service. ICSF and cryptographic coprocessor return and reason codes lists the return codes.

reason_code

Direction	Type
Output	Integer

The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. ICSF and cryptographic coprocessor return and reason codes lists the reason codes.

exit_data_length

Direction	Type
Input/Output	Integer

The length of the data that is passed to the installation exit. The data is identified in the exit_data parameter.

exit_data

Direction	Type
Input/Output	String

The data that is passed to the installation exit.

rule_array_count

Direction	Type
Input	Integer

The number of keywords you supplied in the rule_array parameter. The minimum value is 5. The maximum value is 10.

rule_array

Direction	Type
Input	String

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.

Note: At least one character set keyword is required.

Table 1. Rule array keywords for FPE Decipher
Keyword	Meaning
*Processing method (required)*
VMDS	Specifies that the Visa DSP method (formally known as the Visa Merchant Data Secure 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.
*Algorithm (required)*
TDES	Specifies the use of CBC mode triple-DES encryption.
*Mode (one required)*
CBC	Specifies the user 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 ASCII represented in binary form. Valid ASCII values are '0' through '9' (X'30' through X'39').
PAN4BITX	Specifies that the PAN data character set is 4-bit hex. Two digits per byte. Valid 4-bit hexadecimal values are X'0' through X'9'.
*Cardholder name input output character set (required if the clear_CH_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 3 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 3 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 '0' - '9' (X'30' - X'39') and 'A' - 'F' (X'41' - X'46'.
*PIN encryption key output selection (one, optional, if DUKPT is specified. Otherwise, it is not valid.)*
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 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.

enc_PAN_length

Direction	Type
Input	Integer

Specifies the number of bytes of data in the enc_PAN parameter if the mode is CBC or the number of PAN digits if the mode is VFPE. The value is 0 or 15 through 19 for VFPE. The value must be 0 or 16 if the standard option with CBC mode is selected. The value is zero when the PAN has not been presented for decryption.

enc_PAN

Direction	Type
Input	String

The enciphered primary account number (PAN) that is to be decrypted. 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 are ignored.

enc_CH_name_length

Direction	Type
Input	Integer

Specifies the length in bytes of the enc_CH_name parameter. The input value is 0 or between 1 and 32, inclusive for VFPE. For the standard method, the input value is 0 or 2 through 32 for VFPE. For CBC mode, the input value is 0, 16, 24, 32, or 40. The value is zero when the cardholder name has not been presented for decryption.

enc_CH_name

Direction	Type
Input	String

The enciphered cardholder full name that is to be decrypted. Only characters in Table 3 are valid.

enc_dtrack1_data_length

Direction	Type
Input	Integer

Specifies the length in bytes of the enc_dtrack1_data parameter. The input value is 0 or between 1 and 56 inclusive for VFPE. For the standard method, the input value is 0 or 1 through 56 for VFPE. For CBC mode, the input value is 0 or 16, 24, 32, 40, 48, 56, or 64. The value is zero when the track 1 discretionary data has not been presented for decryption.

enc_dtrack1_data

Direction	Type
Input	String

The encrypted track 1 data that is to be decrypted. Only characters in Table 3 are valid.

enc_dtrack2_data_length

Direction	Type
Input	Integer

Specifies the length in bytes of the enc_dtrack2_data parameter. The input value is 0 or 1 through 19 for VFPE. For mode CBC, the input value is 0, 8, or 16. The value is zero when the track 2 discretionary data is not been presented for decryption.

enc_dtrack2_data

Direction	Type
Input	String

The encrypted track 2 data that is to be decrypted.

key_identifier_length

Direction	Type
Input	Integer

Specifies the length in bytes of the key_identifier parameter. The value must be 64 because only fixed length DES tokens are supported as the key identifier.

key_identifier

Direction	Type
Input/Output	String

The identifier of the key that is used to either decrypt 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 key management DUKPT, the key type must be KEYGENKY. In addition, it must have a control vector with bit 18 equal to B'1' (UKPT). The base derivation key is the one from which the operational keys are derived using the DUKPT algorithm defined in ANS X9.24 Part 1. For key management STATIC, (Zone Encryption Key in the Visa DSP specification), the key type must be either CIPHER or ENCIPHER. 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	Type
Input	Integer

Specifies the length in bytes of the derivation_data parameter. The value must be 10 if a DUKPT key is specified in the key_identifier parameter. If a data encryption key is specified in the key_identifier parameter, this value must be set to zero.

derivation_data

Direction	Type
Input	String

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 value 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.

clear_PAN_length

Direction	Type
Input/Output	Integer

Specifies the number of PAN digits in the clear_PAN parameter. This value must be 0 or between 15 and 19, inclusive on output.

clear_PAN

Direction	Type
Output	String

The field where the deciphered primary account number is returned. The full account number, including check digit, is recovered. The data for this parameter is returned in binary format. It is the binary representation of 4-bit hex (keyword PAN4BITX) or ASCII (keyword PAN8BITA) as indicated by the supplied rule array keyword. The clear PAN is left justified in this field.

clear_CH_name_length

Direction	Type
Input/Output	Integer

Specifies the length in bytes of the clear_CH_name parameter. This output value is 0 or 2 through 32 on output. The variable can be larger on input. However, on output, this field is updated to indicate the actual number of bytes returned by the service.

clear_CH_name

Direction	Type
Output	String

The field where the deciphered cardholder full name is returned. The output data for this parameter is in binary format. It is the binary representation of ASCII as indicated by the supplied rule array keyword.

clear_dtrack1_data_length

Direction	Type
Input/Output	Integer

Specifies the length in bytes of the clear_dtrack1_data parameter. The output value is 0 or 1 through 56. The value can be larger on input. However, on output, this field is updated to indicate the actual number of bytes returned by the service.

clear_dtrack1_data

Direction	Type
Output	String

The field where the deciphered discretionary track 1 data is returned.

clear_dtrack2_data_length

Direction	Type
Input/Output	Integer

Specifies the length in bytes of the clear_dtrack2_data parameter. The output value is 0 or 1 through 19. The value can be larger on input. However, on output, this field is updated to indicate the actual number of bytes returned by the service.

clear_dtrack2_data

Direction	Type
Output	String

The field where the deciphered discretionary track 2 data is returned.

DUKPT_PIN_key_identifier_length

Direction	Type
Input/Output	Integer

Specifies the length in bytes of the DUKPT_PIN_key_identifier parameter. If the PINKEY rule-array keyword is specified, set this value to 64. 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	Type
Input/Output	String

On input, must contain a DES OPINENC or IPINENC skeleton token. On output, DUKPT_PIN_key_identifier contains the DES token with the derived DES OPINENC or IPINENC key.

reserved1_length

Direction	Type
Input	Integer

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

reserved1

Direction	Type
Input	String

This field is ignored.

reserved2_length

Direction	Type
Input	Integer

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

reserved2

Direction	Type
Input	String

This field is ignored.

Usage notes

SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS.

Access control points

The FPE decipher access control point in the domain role controls the function of this service.

Required hardware

This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service.

Table 2. FPE Decipher required hardware
Server	Required cryptographic hardware	Restrictions
IBM eServer zSeries 990 IBM eServer zSeries 890		This service is not supported.
IBM System z9 EC IBM System z9 BC		This service is not supported.
IBM System z10 EC IBM System z10 BC		This service is not supported.
IBM zEnterprise 196 IBM zEnterprise 114		This service is not supported.
IBM zEnterprise EC12 IBM zEnterprise BC12		This service is not supported.
IBM z13	Crypto Express5 CCA Coprocessor