Encrypted PIN Translate Enhanced (CSNBPTRE and CSNEPTRE)

CALL CSNBPTRE(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             input_PIN_key_identifier_length,
             input_PIN_key_identifier,
             output_PIN_key_identifier_length,
             output_PIN_key_identifier,
             PAN_key_identifier_length,
             PAN_key_identifier,
             input_PIN_profile_length,
             input_PIN_profile,
             PAN_data_length,
             PAN_data,
             input_PIN_block_length,
             input_PIN_block,
             output_PIN_profile_length,
             output_PIN_profile,
             sequence_number,
             output_PIN_block_length,
             output_PIN_block,
             reserved1_length,
             reserved1,
             reserved2_length,
             reserved2 ) 

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 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 value must be between 6 and 9 inclusive.

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.

Table 2. Rule array keywords for Encrypted PIN Translate Enhanced

Keyword	Meaning
Mode (required)
REFORMAT	Specifies that either or both the PIN-block format and the PIN-block encryption are to be changed. If the PIN-extraction method is not chosen by default, another element in the rule array must specify one of the keywords that indicates a PIN-extraction method.
Processing method (required)
VMDS	Specifies the Visa Merchant Data Secure method be used for processing.
Input PAN data key management method (one required) These keywords are used to define the PAN-encrypting key used to decrypt the PAN_data parameter.
IN-DUKPT	Specifies that the key to be used to decrypt the PAN data is to be derived using the key specified in the input_PIN_key_identifier. See the description of the input_PIN_key_identifier for the requirements of the key. The DUKPT-BH or DUKPT-IP keyword is required.
OUTDUKPT	Specifies that the key to be used to encrypt the PAN data is to be derived using the key specified in the output_PIN_key_identifier. See the description of the output_PIN_key_identifier for the requirements of the key. The DUKPT-BH or DUKPT-OP keyword is required.
STATIC	Specifies that key is supplied in the PAN_key_identifier parameter is to be used to decrypt the PAN data.
Input data algorithm (one required)
TDES	Specifies Triple-DES encryption was used for the PAN data.
Input data mode (one required)
CBC	Specifies CBC mode encryption was used for the PAN data. This is the mode for the Standard Encryption option.
VFPE	Specifies Visa format preserving mode encryption was used for the PAN data.
PAN input character set (one required)
PAN4BITX	Specifies the PAN data character set is 4-bit hexadecimal. Two digits per byte. Not valid with the CBC rule.
PAN8BITA	Specifies the PAN data character set is normal ASCII represented in binary format. Not valid with CBC rule.
PAN-EBLK	Specifies the PAN data is in a CBC encrypted block. Valid only with CBC rule.
PAN check digit compliance (one required if mode VFPE and PAN input character set keyword present; otherwise, not allowed)
CMPCKDGT	Last digit of the PAN data contains a compliant check digit per ISO/IEC 7812-1.
NONCKDGT	Last digit of the PAN data contains does not contain a compliant check digit per ISO/IEC 7812-1.
Unique key per transaction (one optional) These keywords are for the PIN-encrypting keys.
DUKPT-BH	Specifies that the input and output PIN-encrypting keys are to be derived using the key-generating key specified in the respective parameters. See the descriptions of the input_PIN_key_identifier and output_PIN_key_identifier parameters for the requirements of the keys.
DUKPT-IP	Specifies that the input PIN-encrypting key is to be derived using the key-generating key specified in the input_PIN_key_identifier parameter. See the description of the input_PIN_key_identifier for the requirements of the key.
DUKPT-OP	Specifies that the output PIN-encrypting key is to be derived using the key-generating key specified in the output_PIN_key_identifier parameter. See the description of the output_PIN_key_identifier for the requirements of the key.
PIN-extraction method (one, optional)	See PIN block format and PIN extraction method keywords for additional information and a list of PIN block formats and PIN extraction method keywords. Note: If a PIN extraction method is not specified, the first one method listed in Table 1 for the PIN block format will be the default method.

input_PIN_key_identifier_length

Direction	Type
Input	Integer

Specifies the length of the input_PIN_key_identifier parameter in bytes. The value must be 64.

input_PIN_key_identifier

Direction	Type
Input/Output	String

The identifier of the key to decrypt the input PIN block or the key-generating key to be used to derive the key to decrypt the input PIN block. The key-generating key can optionally be used to derive the key to decrypt the PAN data. The key identifier is an operational token or the key label of an operational token in key storage.

If you do not use the UKPT process or you specify the DUKPT-OP rule array keyword, the key token must contain the PIN-encrypting key to be used to decipher the input PIN block. The key algorithm must be DES, the key type must be IPINENC, and the key usage REFORMAT bit must be enabled.

If you use the UKPT process for the input PIN block by specifying the DUKPT-IP or DUKPT-BH rule array keyword, the key token must contain the key-generating key to derive the PIN-encrypting key. If you have also specified the IN-DUKPT keyword, the key will be used to derive the key to decrypt the PAN data. The key algorithm must be DES, the key type must be KEYGENKY, and the key usage UKPT bit must be enabled.

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

output_PIN_key_identifier_length

Direction	Type
Input/Output	Integer

Specifies the length of the output_PIN_key_identifier parameter in bytes. The value must be 64.

output_PIN_key_identifier

Direction	Type
Input/Output	String

The identifier of the key to encrypt the output PIN block or the key-generating key to be used to derive the key to encrypt the output PIN block. The key-generating key can optionally be used to derive the key to decrypt the PAN data. The key identifier is an operational token or the key label of an operational token in key storage.

If you do not use the UKPT process or you specify the DUKPT-IP rule array keyword, the key token must contain the PIN-encrypting key to be used to encipher the output PIN block. The key algorithm must be DES, the key type must be OPINENC, and the key usage REFORMAT bit must be enabled.

If you use the UKPT process for the output PIN block by specifying the DUKPT-OP or DUKPT-BH rule array keyword, the key token must contain the key-generating key to derive the PIN-encrypting key. If you have also specified the OUTDUKPT keyword, the key will be used to derive the key to decrypt the PAN data. The key algorithm must be DES, the key type must be KEYGENKY, and the key usage UKPT bit must be enabled.

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

PAN_key_identifier_length

Direction	Type
Input	Integer

Specifies the length of the PAN_key_identifier parameter in bytes. The value must be 64 if the PAN key management method keyword is STATIC; otherwise, the value is 0.

PAN_key_identifier

Direction	Type
Input/Output	String

The identifier of the key to decrypt the PAN data. The key identifier is an operational token or the key label of an operational token in key storage. The key algorithm must be DES, the key type must be CIPHER or DECIPHER, and the key must be a double-length key.

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

input_PIN_profile_length

Direction	Type
Input	Integer

Specifies the length of the input_PIN_profile parameter in bytes. The value is 24 if the profile does not contain a CKSN extension. The value is 48 when the CKSN extension is part of the profile.

input_PIN_profile

Direction	Type
Input	String

The 24 or 48 bytes input PIN profile. The profile consists of three 8-byte character strings with information defining the input PIN-block format and optionally, an additional 24 bytes containing the input CKSN extension.

PAN_data_length

Direction	Type
Input	Integer

When the input data mode keyword is CBC, this parameter specifies the length in bytes of the PAN_data parameter. The value must be 16.

When the input data mode keyword is VFPE, this parameter specifies the number of PAN digits. The value will be between 15 and 19 inclusive.

PAN_data

Direction	Type
Input	String

The enciphered primary account number (PAN) to be used to reformat the PIN block format. 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 rightmost 4 bits are ignored.

This service uses this data to recover the PIN from the PIN block if you specify the REFORMAT keyword and the input PIN profile specifies the ISO-0, VISA-4, or ISO-3 keyword for the PIN block format. If the output PIN profile specifies the ISO-0, VISA-4, or ISO-3 keyword for the PIN block format, the 12 rightmost digits of the PAN, excluding the check digit, are used to format the output PIN block.

input_PIN_block_length

Direction	Type
Input	Integer

Specifies the length of the input_PIN_block parameter in bytes. The value must be 8.

input_PIN_block

Direction	Type
Input	String

The 8-byte enciphered PIN block that contains the PIN to be processed.

output_PIN_profile_length

Direction	Type
Input	Integer

Specifies the length of the output_PIN_profile parameter in bytes. The value is 24 or 48.

output_PIN_profile

Direction	Type
Input	String

The 24 or 48 byte PIN profile for the output PIN block. The profile contains three 8-byte character strings with information defining the PIN-block format and optionally, an additional 24 bytes containing the output CKSN extension.

sequence_number

Direction	Type
Input	Integer

The 4 byte sequence number if the output PIN block format is 3621. Specify the integer value 99999. Otherwise, this parameter is ignored.

output_PIN_block_length

Direction	Type
Input/Output	Integer

Specifies the length of the output_PIN_block parameter in bytes. The value must be at least 8 bytes. On output, the value is updated with the actual number of bytes returned.

output_PIN_block

Direction	Type
Output	String

The 8 byte reformatted PIN block.

reserved1_length

Direction	Type
Input	Integer

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

reserved1

Direction	Type
Input	String

This field is ignored.

reserved2_length

Direction	Type
Input	Integer

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

reserved2

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 Encrypted PIN Translate Enhanced access control in the domain role controls the function of this service. In addition, the Encrypted PIN Translate – Reformat access control must be enabled when the mode rule array keyword is REFORMAT.

If any of the rule array keywords that control UKPT key derivation (IN-DUKPT, OUTDUKPT, DUKPT-OP, DUKPT-IP, and DUKPT-BH) are specified, the UKPT - PIN Verify, PIN Translate access control must be enabled.

An enhanced PIN security mode is available for formatting an encrypted PIN block into IBM 3621 format or IBM 3624 format. To do this, you must enable the Enhanced PIN Security access control point in the domain role. When activated, this mode limits checking of the PIN to decimal digits. No other PIN block consistency checking will occur.

When the Disallow translation from DES wrapping to weaker DES wrapping access control point is enabled, this service will fail if the input PIN key identifier is a PIN-encrypting key and is stronger than the output PIN key identifier when it is a PIN-encrypting key.

When the Disallow PIN block format ISO-1 access control is enabled in the domain role, the PIN block format in the input_PIN_profile and output_PIN_profile parameters is not allowed to be ISO-1.

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