The FPE translate callable service is used to translate payment data from encryption under one key to encryption under another key with a possibly different format. You should avoid having plain text payment data in your environment. Translations can be performed with data that has been encrypted using the standard encryption option or with data that has been encrypted using the VFPE option. However, the target translation uses double length static TDES keys and the standard encryption option.
This service can be used to translate 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.
The callable service name for AMODE(64) invocation is CSNEFPET.
CALL CSNBFPET(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
input_PAN_length,
input_PAN,
input_CH_name_length,
input_CH_name,
input_dtrack1_data_length,
input_dtrack1_data,
input_dtrack2_data_length,
input_dtrack2_data,
input_key_identifier_length,
input_key_identifier,
output_key_identifier_length,
output_key_identifier,
derivation_data_length,
derivation_data,
output_PAN_length,
output_PAN,
output_CH_name_length,
output_CH_name,
output_dtrack1_data_length,
output_dtrack1_data,
output_dtrack2_data_length,
output_dtrack2_data,
DUKPT_PIN_key_identifier_length,
DUKPT_PIN_key_identifier,
reserved1_length,
reserved1,
reserved2_length,
reserved2)
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.
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.
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.
Direction | Type |
---|---|
Input/Output | String |
The data that is passed to the installation exit.
Direction | Type |
---|---|
Input | Integer |
The number of keywords you supplied in the rule_array parameter. The minimum value is 4. The maximum value is 10.
Direction | Type |
---|---|
Input | String |
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 only for VFPE mode. |
PAN4BITX | Specifies that the PAN data character set is 4-bit hex. Two digits per byte. Valid only for VFPE mode. |
PAN-EBLK | Specifies that the PAN data is in a CBC encrypted block. Valid only for CBC mode. |
Cardholder name input output character set (required if the clear_CH_name_length variable is greater than 0.) | |
CN8BITA | Specifies that the cardholder name character set is ASCII represented in binary format, one character per byte. See Table 3 for valid characters. Valid only for VFPE mode. |
CN-EBLK | Specifies that the cardholder name data is in a CBC-encrypted block. |
Track_1 input 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. |
TK1-EBLK | Specifies that the track 1 discretionary data is in a CBC-encrypted block. Valid only for CBC mode. |
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. Valid only for VFPE mode. |
TK2-EBLK | Specifies that the track 2 discretionary data is in a CBC encrypted block. Valid only for CBC mode. |
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 input 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. |
Direction | Type |
---|---|
Input | Integer |
Specifies the number of bytes of data in the input_PAN parameter if the mode is CBC or the number of PAN digits if the mode is VFPE. The value is 0 if PAN data has not been presented for translation. Otherwise, the value is between 15 and 19 inclusive for VFPE. The value is 16 if CBC mode is selected.
Direction | Type |
---|---|
Input | String |
The enciphered primary account number (PAN) that is to be translated. 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.
Direction | Type |
---|---|
Input | Integer |
Specifies the length in bytes of the input_CH_name parameter. This value must be 0 if cardholder name data is not presented for translation. Otherwise, the value is 2 through 32 for VFPE. For CBC mode, the input value is either 16, 24, 32, or 40.
Direction | Type |
---|---|
Input | String |
The enciphered cardholder full name that is to be translated. Only characters in Table 3 are valid.
Direction | Type |
---|---|
Input | Integer |
Specifies the length in bytes of the input_dtrack1_data parameter. This value must be 0 if track 1 discretionary data is not presented for translation. Otherwise, the value is 1 through 56 for VFPE. For CBC mode, the input value is either 16, 24, 32, 40, 48, 56, or 64.
Direction | Type |
---|---|
Input | String |
The encrypted track 1 data that is to be translated. Only characters in Table 3 are valid.
Direction | Type |
---|---|
Input | Integer |
Specifies the length in bytes of the input_dtrack2_data parameter. This value must be 0 if track 2 discretionary data is not presented for translation. Otherwise, the value is 1 through 19 for VFPE. For CBC mode, the input value is either 8 or 16.
Direction | Type |
---|---|
Input | String |
The encrypted track 2 data that is to be translated.
Direction | Type |
---|---|
Input | Integer |
Specifies the length in bytes of the input_key_identifier parameter. The value must be 64 because only fixed length DES tokens are supported as the key identifier.
Direction | Type |
---|---|
Input/Output | String |
The identifier of the key that is used to either decrypt the input 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.
If the token supplied was encrypted under the old master key, the token is returned encrypted under the current master key.
Direction | Type |
---|---|
Input | Integer |
Specifies the length in bytes of the output_key_identifier parameter. The value must be 64 because only fixed length DES tokens are supported as the key identifier.
Direction | Type |
---|---|
Input/Output | String |
The identifier of the key that is used to decrypt the output card data. The key identifier is an operational token or the key label of an operational token in key storage.
If the token supplied was encrypted under the old master key, the token is returned encrypted under the current master key.
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.
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.
Direction | Type |
---|---|
Input/Output | Integer |
Specifies the number of bytes of data in the output_PAN parameter. This value is 0 or 16 on output.
Direction | Type |
---|---|
Output | String |
The field where the translated primary account number with which the PIN is associated. The full account number, including check digit, is translated. The data for this parameter is returned as TDES-encrypted data in binary format. The 16 byte output is left justified in this field.
Direction | Type |
---|---|
Input/Output | Integer |
Specifies the length in bytes of the output_CH_name parameter. This output value is either 0 or 16, 24, 32, or 40 bytes 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 card.
Direction | Type |
---|---|
Output | String |
The field where the translated cardholder full name is returned. The data for this parameter is returned as TDES-encrypted data in binary format.
Direction | Type |
---|---|
Input/Output | Integer |
Specifies the length in bytes of the output_dtrack1_data parameter. The output value is either 0 or 16, 24, 32, 40, 48, 56, or 64 bytes. 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.
Direction | Type |
---|---|
Output | String |
The field where the translated discretionary track 1 data is returned. This is the discretionary data from track 1 of a magnetic stripe card. The data for this parameter is returned as TDES-encrypted data in binary format.
Direction | Type |
---|---|
Input/Output | Integer |
Specifies the length in bytes of the output_dtrack2_data parameter. The output value is either 0, 8, or 16. 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.
Direction | Type |
---|---|
Output | String |
The field where the translated discretionary track 2 data is returned. This is the discretionary data from track 2 of a magnetic stripe card. The data for this parameter is returned as TDES-encrypted data in binary format.
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.
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.
Direction | Type |
---|---|
Input | Integer |
Length in bytes of the reserved1 parameter. The value must be 0.
Direction | Type |
---|---|
Input | String |
This field is ignored.
Direction | Type |
---|---|
Input | Integer |
Length in bytes of the reserved2 parameter. The value must be 0.
Direction | Type |
---|---|
Input | String |
This field is ignored.
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.
The FPE translate access control point in the domain role controls the function of this service.
This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service.
Server | Required cryptographic hardware | Restrictions |
---|---|---|
IBM eServer zSeries |
This service is not supported. | |
IBM System z9 EC |
This service is not supported. | |
IBM System z10 EC |
This service is not supported. | |
IBM zEnterprise 196 |
This service is not supported. | |
IBM zEnterprise EC12 |
This service is not supported. | |
IBM z13 |
Crypto Express5 CCA Coprocessor |