Encrypted PIN Translate2 (CSNBPTR2 and CSNEPTR2)

CALL CSNBPTR2(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             input_PIN_encrypting_key_identifier_length,
             input_PIN_encrypting_key_identifier,
             output_PIN_encrypting_key_identifier_length,
             output_PIN_encrypting_key_identifier,
             authentication_key_identifier_length,
             authentication_key_identifier,
             input_PIN_profile_length,
             input_PIN_profile,
             input_PAN_data_length,
             input_PAN_data,
             input_PIN_block_length,
             input_PIN_block,
             output_PIN_profile_length,
             output_PIN_profile,
             output_PAN_data_length,
             output_PAN_data,
             authentication_data_length,
             authentication_data,
             output_PIN_block_length,
             output_PIN_block,
             reserved1_length,
             reserved1,
             reserved2_length,
             reserved2,
             reserved3_length,
             reserved3 ) 

return_code

Direction	Type
Output	Integer

The return code specifies the general result of the callable service. ICSF and cryptographic coprocessor return/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/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 that you supplied in the rule_array parameter. Values are 1 through 5.

rule_array

Direction	Type
Input	Character String

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. Keywords for Encrypted PIN Translate2

Keyword	Meaning
Mode (one, required)
REFORMAT	Specifies that either the PIN-block format or the PIN-block encryption, or both, 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.
TRANSLAT	Specifies that only PIN-block encryption is changed. The first 24 bytes of PIN profiles are ignored for all formats except ISO-4. The input PIN profile must be supplied for ISO-4 PIN blocks.
PAN change option (One, optional) Only valid with REFORMAT and for ISO-4 PIN block processing.
PAN-CHG	Specifies that a PAN change has been requested.
PAN format option (one, optional) Only valid with REFORMAT and for ISO-4 PIN block processing.
PANAUTAS	Specifies to format the PAN data using the original ASCII format when verifying the CMAC of the authentication data.
PANAUTI4	Specifies to format the PAN data according to ISO 9564-1 Plain text primary account number field format when verifying the CMAC of the authentication data.
DES DUKPT (one, optional). Valid for DES keys only. See Table 4 for valid DUKPT keyword combinations.
UKPTIPIN	Specifies the use of DUKPT input-key derivation and PIN-block decryption, Single-DES method. This keyword cannot be specified with ADUKPTBH or ADUKPTIP.
UKPTOPIN	Specifies the use of DUKPT output-key derivation and PIN-block encryption, Single-DES method. This keyword cannot be specified with ADUKPTBH or ADUKPTOP.
UKPTBOTH	Specifies the use of DUKPT key-derivation and PIN-block ciphering for both input and output processing, Single-DES method. This keyword cannot be specified with any of the keywords in the AES DUKPT group.
DUKPT-IP	Specifies the use of DUKPT input-key derivation and PIN-block decryption, Triple-DES method. This keyword cannot be specified with ADUKPTBH or ADUKPTIP.
DUKPT-OP	Specifies the use of DUKPT output-key derivation and PIN-block encryption, Triple-DES method. This keyword cannot be specified with ADUKPTBH or ADUKPTOP.
DUKPT-BH	Specifies the use of DUKPT key-derivation and PIN-block ciphering for both input and output processing, Triple-DES method. This keyword cannot be specified with any of the keywords in the AES DUKPT group.
AES DUKPT (one, optional). Valid for AES keys only. See Table 4 for valid DUKPT keyword combinations.
ADUKPTBH	Specifies the use of DUKPT key-derivation and PIN-block ciphering for both input and output processing. AES DUKPT method. This keyword cannot be specified with any of the keywords in the DES DUKPT group.
ADUKPTIP	Specifies the use of DUKPT key-derivation and PIN-block ciphering for input processing. AES DUKPT method. This keyword cannot be specified with UKPTIPIN, UKPTBOTH, DUKPT-IP, or DUKPT-BH
ADUKPTOP	Specifies the use of DUKPT key-derivation and PIN-block ciphering for output processing. AES DUKPT method. This keyword cannot be specified with UKPTOPIN, UKPTBOTH, DUKPT-OP, or DUKPT-BH.
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 listed in Table 1 for the PIN block format will be the default.

input_PIN_encrypting_key_identifier_length

Direction	Type
Input	Integer

Specifies the length in bytes of the input_PIN_encrypting_key_identifier parameter.

If the input_PIN_encrypting_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_PIN_encrypting_key_identifier

Direction	Type
Input/Output	String

The identifier of the PIN-encrypting 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 identifier is a variable-length operational key token or key block or the key label of an operational token or block in key storage.

For CCA key tokens:

For DES keys

If you do not use the DUKPT process or specified the UKPTOPIN or DUKPT-OP rule array keyword, the key is a DES 64-byte PIN block encrypting key of type IPINENC and has one or both of the TRANSLAT and REFORMAT key usage bits enabled as appropriate for the requested mode.

If you use the DUKPT process for the input PIN block by specifying the UKPTIPIN, UKPTBOTH, DUKPT-IP, or DUKPT-BH rule array keyword, the key is the DES 64-byte base derivation key of KEYGENKY key type with key usage UKPT enabled.

For AES keys (ISO-4 PIN blocks)

If you do not use the DUKPT process or specified the ADUKPTOP rule array keyword, this key is an AES variable-length PIN block encrypting key of type PINPROT with one or both of the PINXLATE and REFORMAT key usage field bits enabled as appropriate for the requested mode. The key usage fields must have the decryption operation set so that the key can be used for decryption (DECRYPT), but not encryption, and the encryption mode of Cipher Block Chaining (CBC) must be specified.

If you use the DUKPT process for the input PIN block by specifying the ADUKPTIP or ADUKPTBH rule array keywords and the input_PIN_profile contains AES-DUKPT derivation data, this key is an AES variable-length DKYGENKY key with the A-DUKPT bit set to 1 in the low-order byte of key usage field 1.

For X9.143 key blocks:

For DES keys

If you do not use the DUKPT process or specified the UKPTOPIN or DUKPT-OP rule array keyword, the key is TDES PIN-encrypting key (key usage P0, algorithm T, and mode of use D).

If you use the DUKPT process for the input PIN block by specifying the UKPTIPIN, UKPTBOTH, DUKPT-IP, or DUKPT-BH rule array keyword, the key is the TDES base derivation key (key usage B0, algorithm T, and mode of use X).

For AES keys (ISO-4 PIN blocks)

If you do not use the DUKPT process or specified the ADUKPTOP rule array keyword, this key is an AES PIN-encrypting key (key usage P0, algorithm A, and mode of use D).

If you use the DUKPT process for the input PIN block by specifying the ADUKPTIP or ADUKPTBH rule array keywords and the input_PIN_profile contains AES-DUKPT derivation data, this key is an AES base derivation key (key usage B0, algorithm A, and mode of use X).

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

output_PIN_encrypting_key_identifier_length

Direction	Type
Input	Integer

Specifies the length in bytes of the output_PIN_encrypting_key_identifier parameter.

If the output_PIN_encrypting_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_PIN_encrypting_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 identifier is an operational token or the key label of an operational token in key storage.

For CCA key tokens:

For DES keys

If you do not use the DUKPT process or specified the UKPTIPIN or DUKPT-IP rule array keyword, the key is a DES 64-byte PIN block encrypting key of type OPINENC and has one or both of the TRANSLAT and REFORMAT key usage bits enabled as appropriate for the requested mode.

If you use the DUKPT process for the output PIN-block by specifying the UKPTOPIN, UKPTBOTH, DUKPT-OP, or DUKPT-BH rule array keyword, the key is the DES 64-byte base derivation key of KEYGENKY key type with key usage UKPT enabled.

For AES keys (ISO-4 PIN block)

If you do not use the DUKPT process or you specify the ADUKPTIP rule array keyword, this key is an AES variable-length PIN block encrypting key of type PINPROT with one or both of the PINXLATE and REFORMAT key usage field bits enabled as appropriate for the requested mode. The key usage fields must have the encryption operation set so that the key can be used for encryption (ENCRYPT), but not decryption, and the encryption mode of Cipher Block Chaining (CBC) must be specified.

If you use the DUKPT process for the output PIN block by specifying the ADUKPTOP or ADUKPTBH rule array keywords and the output_PIN_profile contains AES-DUKPT derivation data, this key is an AES variable-length DKYGENKY key with the A-DUKPT bit set to 1 in the low-order byte of key usage field 1.

For X9.143 key blocks:

For DES keys

If you do not use the DUKPT process or specified the UKPTIPIN or DUKPT-IP rule array keyword, the key is TDES PIN-encrypting key (key usage P0, algorithm T, and mode of use E).

If you use the DUKPT process for the input PIN block by specifying the UKPTOPIN, UKPTBOTH, DUKPT-OP, or DUKPT-BH rule array keyword, the key is the TDES base derivation key (key usage B0, algorithm T, and mode of use X).

For AES keys (ISO-4 PIN blocks)

If you do not use the DUKPT process or specified the ADUKPTIP rule array keyword, this key is an AES PIN-encrypting key (key usage P0, algorithm A, and mode of use E).

If you use the DUKPT process for the input PIN block by specifying the ADUKPTOP or ADUKPTBH rule array keywords and the output_PIN_profile contains AES-DUKPT derivation data, this key is an AES base derivation key (key usage B0, algorithm A, and mode of use X).

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

authentication_key_identifier_length

Direction	Type
Input	Integer

Specifies the length in bytes of the authentication_key_identifier parameter.

When the PAN change option keyword PAN-CHG is not specified, the value must be zero.

When the PAN change option keyword PAN-CHG is specified, and the authentication_key_identifier contains a label, the length must be 64.

Otherwise, the value must be between the actual length of the token and 9992.

authentication_key_identifier

Direction	Type
Input/Output	String

The identifier of the key to verify the CMAC in the authentication_data parameter. The key identifier is an operational token or the key label of an operational token in key storage. When authentication_key_identifier_length is zero, this parameter is ignored.

For CCA keys, the key algorithm of this key must be AES, the key type must be MAC, and the key usage fields must indicate CMAC, VERIFY. When Encrypted PIN Translate2 - Permit ISO-4 to ISO-4 PTR2AUTH is enabled, the AES MAC key must have key usage VERIFY, CMAC, and PTR2AUTH enabled.

For X9.143 keys, the identifier is a variable-length key block of an AES MAC key: key usage M6, algorithm A, and mode of use V.

If the token or block supplied was encrypted under the old master key, the token or block is 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.

Table 2. Supported Encrypted PIN Translate2 PIN profile lengths

Pin profile	Length
PIN-block format only.	24
PIN-block format and CKSN extension used for DES-DUKPT.	48
PIN-block format and single block of derivation data extension used for AES-DUKPT.	44

input_PIN_profile

Direction	Type
Input	String

The 24, 44, or 48 byte input PIN profile. The profile consists of three 8-byte character strings with information defining the input PIN-block format and optionally followed by either an additional 24 bytes containing the input CKSN extension or an additional 20 bytes containing the input derivation data extension. See The PIN profile for additional information.

If the rule array keyword UKPTBOTH or UKPTIPIN is specified, CKSN extension must be included in the input_PIN_profile. Single-DES DUKPT algorithm will be used to derive the DUKPT key used to decrypt the input PIN block.

If the rule array keyword DUKPT-BH or DUKPT-IP is specified, CKSN extension must be included in the input_PIN_profile. The Triple-DES DUKPT algorithm will be used to derive the DUKPT key used to decrypt the input PIN block.

If the rule array keyword ADUKPTBH or ADUKPTIP is specified, the AES-DUKPT algorithm will be used to derive the DUKPT key used to decrypt the input PIN block when the derivation data extension is included in the input_PIN_profile. See Table 1 for the layout of the AES-DUKPT derivation data extension. The algorithm indicator must be set to X'0000' (2-key TDES), X'0001' (3-key TDES), X'0002' (AES-128), X'0003' (AES-192), or X'0004' (AES-256). The key usage indicator must be set to X'1000' (PIN Encryption).

input_PAN_data_length

Direction	Type
Input	Integer

Specifies the length of the input_PAN_data parameter in bytes.

When the TRANSLAT mode rule is specified, the value must be 0 except when the PIN block format is ISO-4. When the format is ISO-4, the value must be 10 - 19.

When the REFORMAT keyword is specified:

• If the input PIN block format is ISO-0, ISO-3, or VISA-4, the value must be 12.
• If the input PIN block format is ISO-4, the value must be 10 - 19.
• Otherwise, the value must be 0.

input_PAN_data

Direction	Type
Input	String

The primary account number (PAN) data used to format the input PIN block. This service uses this data to recover the PIN from the PIN block when the format uses the PAN data.

When the TRANSLAT mode rule is specified, this parameter is ignored except when the PIN block format is ISO-4. When the format is ISO-4, this parameter is required.

When the REFORMAT keyword is specified and the input PIN profile specifies ISO-0, ISO-3, ISO-4, or VISA-4 for the PIN block format, this parameter is required.

When the profile specifies the ISO-0, ISO-3, or VISA-4 block format, the 12 rightmost digits of the PAN, excluding the check digit, are used to format the output PIN block.

When the PIN block format is ISO-4, the PAN is used to format the output PIN block. The PAN check digit is included in the formation. The PAN check digit is excluded in the test used to determine if the PAN of an ISO-4 PIN block is equivalent to a PAN that is in a non-ISO format 4 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 for DES PIN-encrypting key and 16 for AES PIN-encrypting key.

input_PIN_block

Direction	Type
Input	String

The 8-byte or 16-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. See Table 2 for the supported PIN profile lengths.

output_PIN_profile

Direction	Type
Input	String

The 24, 44, or 48 byte output PIN profile. The profile contains three 8-byte character strings with information defining the PIN-block format and optionally followed by either an additional 24 bytes containing the input CKSN extension or an additional 20 bytes containing the input derivation data extension. See The PIN profile for additional information.

If the rule array keyword UKPTBOTH or UKPTOPIN is specified, CKSN extension must be included in the output_PIN_profile. Single-DES DUKPT algorithm will be used to derive the DUKPT key used to encrypt the output PIN block.

If the rule array keyword DUKPT-BH or DUKPT-OP is specified, CKSN extension must be included in the output_PIN_profile. The Triple-DES DUKPT algorithm will be used to derive the DUKPT key used to encrypt the output PIN block.

If the rule array keyword ADUKPTBH or ADUKPTOP is specified, the AES-DUKPT algorithm will be used to derive the DUKPT key used to encrypt the output PIN block when the derivation data extension is included in the output_PIN_profile. See Table 1 for the layout of the AES-DUKPT derivation data extension. The algorithm indicator must be set to X'0000' (2-key TDES), X'0001' (3-key TDES), X'0002' (AES-128), X'0003' (AES-192), or X'0004' (AES-256). The key usage indicator must be set to X'1000' (PIN Encryption).

When the mode rule is TRANSLAT, the first 24 bytes of this parameter are ignored.

When the mode rule is REFORMAT in the rule array, the input PIN profile and output PIN profile can have different PIN block formats.

When UKPTOPIN or UKPTBOTH is specified, the parameter is extended to a 48-byte field and must contain the output current key serial number.

When DUKPT-OP or DUKPT-BH is specified, the parameter is extended to a 48-byte field and must contain the output current key serial number.

output_PAN_data_length

Direction	Type
Input	Integer

Specifies the length of the output_PAN_data parameter in bytes.

When the mode rule is TRANSLAT, this parameter is ignored.

When the mode rule is REFORMAT:

• If the output PIN block format is ISO-0, ISO-3, or VISA-4, the value must be 12.
• If the format is ISO-4, the value must be 10 - 19.
• Otherwise, the value must be zero.

output_PAN_data

Direction	Type
Input	String

The primary account number (PAN) data used to format the output PIN block. When the output_PAN_data_length is zero, this parameter is ignored. When the mode rule is TRANSLAT, the parameter is ignored.

This service uses this data to format the output PIN block if you specify the REFORMAT keyword and the output PIN profile specifies the ISO-0, ISO-3, ISO-4, or VISA-4 keyword for the PIN block format.

For the ISO-4 format, the PAN-CHG rule must be specified in the rule array and the authentication data must be supplied.

When using the ISO-0, ISO-3, or VISA-4 PIN-block format, use the 12 rightmost digits of PAN, excluding the check digit. When using the ISO-4 PIN-block format, the PAN check digit is included in the formation of the PIN blocks.

authentication_data_length

Direction	Type
Input	Integer

Specifies the length of the authentication_data parameter in bytes. When the PAN change option keyword PAN-CHG is specified, the value must be 12 – 276. Otherwise, the value must be zero.

authentication_data

Direction	Type
Input	String

The MAC that must be verified to authorize a PAN change operation. When the authentication_data_length is zero, this parameter is ignored.

The parameter contains a length-value structure with the following format:

Offset	Length	Description
0	2	Length of the CMAC, n. The CMAC can be 8 – 16 bytes long,
2	n	CMAC
2 + n	2	Length of the optional additional authentication data.
4 + n	0 - 256	Optional additional authentication data.

The additional authentication data length can be 0. If a PAN change is requested, the CMAC length can be 8 to 16 bytes. The service creates a CMAC over the old PAN data, new PAN data, and additional authentication data.

Note: The PAN data must be ASCII character data when calculating the authentication value.

This MAC is compared to the CMAC in this parameter for length specified. If the values match, the PAN change request is honored.

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 for DES PIN blocks and 16 for AES PIN blocks. On output, the value is updated with the actual number of bytes returned.

output_PIN_block

Direction	Type
Output	String

The 8 or 16 byte reformatted PIN block.

reserved1_length

Direction	Type
Input/Output	Integer

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

reserved1

Direction	Type
Input	String

This parameter 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 parameter is ignored.

reserved3_length

Direction	Type
Input	Integer

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

reserved3

Direction	Type
Input	String

This parameter 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 following table shows the access control points in the domain role that control the function of this service. When the input or output PIN format in the PIN profile is ISO-4, the Encrypted PIN Translate2 – REFORMAT/TRANSLATE access controls are used. When neither the input nor output PIN format in the PIN profile is ISO-4, the Encrypted PIN Translate – REFORMAT/TRANSLATE access controls are used.

If any of the Unique Key per Transaction rule array keywords are specified, the DUKPT - PIN Verify, PIN Translate access control point must be enabled.

An enhanced PIN security mode is available for extracting PINs from a 3621 or 3624 encrypted PIN-block and formatting an encrypted PIN block into IBM 3621 or 3624 format using the PADDIGIT PIN-extraction method. This mode limits checking of the PIN to decimal digits, and a minimum PIN length of 4 is enforced; no other PIN-block consistency checking will occur. To activate this mode, enable the Enhanced PIN Security access control.

When the Encrypted PIN Translate - Translate PIN Check access control is enabled, checking of the PIN block is performed. The checking is the same as the checking done when the REFORMAT keyword is specified.

When the General ISO PIN Error Security access control is enabled, the return code will be a general PIN block error (return code 8 reason code 2514) instead of some of the PIN block errors return code. The use of a general return code can prevent the abuse of PIN processing error messages due to information leakage derived from the return code reason codes returned under various conditions. For more details, see PIN block error processing mode.

When the Disallow translation from AES wrapping to DES wrapping access control point is enabled in the domain role, this service fails if the input_PIN_encrypting_key_identifier is an AES key and the output_PIN_encrypting_key_identifier is a DES key.

When the Disallow translation from AES wrapping to weaker AES wrapping access control point is enabled in the domain role, this service fails if the input_PIN_encrypting_key_identifier is stronger than the output_PIN_encrypting_key_identifier.

When the Disallow translation from DES wrapping to weaker DES wrapping access control point is enabled in the domain role, this service fails if the input_PIN_encrypting_key_identifier is stronger than the output_PIN_encrypting_key_identifier.

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. The CCA releases used in the table are described in CCA release levels.