DK PAN Modify in Transaction (CSNBDPMT and CSNEDPMT)

Use the DK PAN Modify in Transaction callable service to generate a new PIN reference value (PRW) for an existing PIN when a merger has occurred and the account information has changed. The inputs include the current PIN, the account information (PAN and card data) for the current, and the new account.

The DK PRW CMAC Generate service is called prior to this service to generate the MAC of the changed account information. If the MAC associated with the account information does not verify, the service fails.

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

Format

CALL CSNBPDPMT(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             current_PAN_data_length,
             current_PAN_data,
             new_PAN_data_length,
             new_PAN_data,
             current_card_p_data_length,
             current_card_p_data,
             current_card_t_data_length,
             current_card_t_data,
             new_card_p_data_length,
             new_card_p_data,
             new_card_t_data_length,
             new_card_t_data,
             CMAC_FUS_length,
             CMAC_FUS,
             ISO_encrypted_PIN_block_length,
             ISO_encrypted_PIN_block,
             current_PIN_reference_value_length,
             current_PIN_reference_value,
             current_PRW_random_number_length,
             current_PRW_random_number,
             CMAC_FUS_key_identifier_length,
             CMAC_FUS_key_identifier,
             IPIN_encryption_key_identifier_length,
             IPIN_encryption_key_identifier,
             PRW_key_identifier_length,
             PRW_key_identifier,
             new_PRW_key_identifier_length,
             new_PRW_key_identifier,
             new_PIN_reference_value_length,
             new_PIN_reference_value,
             new_PRW_random_number_length,
             new_PRW_random_number)

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 value must be 0.

rule_array

Direction	Type
Input	Character

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. There are no keywords for this service.

current_PAN_data_length

Direction	Type
Input	Integer

Specifies the length in bytes of the current_PAN_data parameter. The value must be between 10 and 19, inclusive.

current_PAN_data

Direction	Type
Input	Character

The current PAN data associated with the PIN. The full account number, including check digit, should be included. This parameter is character data.

new_PAN_data_length

Direction	Type
Input	Integer

Specifies the length in bytes of the new_PAN_data parameter. The value must be between 10 and 19, inclusive.

new_PAN_data

Direction	Type
Input	Character

The new PAN data to be associated with the PIN. The full account number, including check digit, should be included. This parameter is character data.

current_card_p_data_length

Direction	Type
Input	Integer

Specifies the length in bytes of the current_card_p_data parameter. The value must be between 2 and 256, inclusive.

current_card_p_data

Direction	Type
Input	String

The time-invariant card data (CDp) of the current account, determined by the card issuer.

current_card_t_data_length

Direction	Type
Input	Integer

Specifies the length in bytes of the current_card_t_data parameter. The value must be between 2 and 256, inclusive.

current_card_t_data

Direction	Type
Input	String

The time-invariant card data (CDp) of the current account, determined by the card issuer.

new_card_p_data_length

Direction	Type
Input	Integer

Specifies the length in bytes of the new_card_p_data parameter. The value must be between 2 and 256, inclusive.

new_card_p_data

Direction	Type
Input	String

The time-invariant card data (CDp) of the current account, determined by the card issuer.

new_card_t_data_length

Direction	Type
Input	Integer

Specifies the length in bytes of the new_card_t_data parameter. The value must be between 2 and 256, inclusive.

new_card_t_data

Direction	Type
Input	String

The time-invariant card data (CDp) of the current account, determined by the card issuer.

CMAC_FUS_length

Direction	Type
Input	Integer

Specifies the length in bytes of the CMAC_FUS parameter. The value must be between 8 and 16, inclusive.

CMAC_FUS

Direction	Type
Input	String

The 8-byte to 16-byte MAC that was of the current and new PANs and card data strings and PIN reference values. The MAC is generated using the DK PRW CMAC Generate service.

ISO_encrypted_PIN_block_length

Direction	Type
Input	Integer

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

ISO_encrypted_PIN_block

Direction	Type
Input	String

The 8-byte encrypted PIN block with the PIN in ISO-1 format.

current_PIN_reference_value_length

Direction	Type
Input	Integer

Specifies the length in bytes of the current_PIN_reference_value parameter. The value must be 16.

current_PIN_reference_value

Direction	Type
Input	String

The 16-byte PIN reference value for comparison to the calculated value.

current_PRW_random_number_length

Direction	Type
Input	Integer

Specifies the length in bytes of the current_PRW_random_number parameter. The value must be 4.

current_PRW_random_number

Direction	Type
Input	String

The 4-byte random number associated with the PIN reference value.

CMAC_FUS_key_identifier_length

Direction	Type
Input	Integer

Specifies the length in bytes of the CMAC_FUS_key_identifier parameter. If the CMAC_FUS_key_identifier contains a label, the length must be 64. Otherwise, the value must be between the actual length of the token and 725.

CMAC_FUS_key_identifier

Direction	Type
Input/Output	String

The identifier of the key to verify the CMAC_FUS value. The key identifier is an operational token or the key label of an operational token in key storage. The key algorithm of this key must be AES, the key type must be MAC, and the key usage fields must indicate VERIFY, CMAC, and DKPINAD2.

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

IPIN_encryption_key_identifier_length

Direction	Type
Input	Integer

Specifies the length in bytes of the IPIN_encryption_key_identifier parameter. If the IPIN_encryption_key_identifier contains a label, the length must be 64. Otherwise, the value must be between the actual length of the token and 725.

IPIN_encryption_key_identifier

Direction	Type
Input/Output	String

The identifier of the key to decrypt the encrypted_PIN_block. The key identifier is an operational token or the key label of an operational token in key storage. The key algorithm of this key must be DES and the key type must be IPINENC.

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

PRW_key_identifier_length

Direction	Type
Input	Integer

Specifies the length in bytes of the PRW_key_identifier parameter. If the PRW_key_identifier contains a label, the length must be 64. Otherwise, the value must be between the actual length of the token and 725.

PRW_key_identifier

Direction	Type
Input/Output	String

The identifier of the key to verify the input PRW. The key identifier is an operational token or the key label of an operational token in key storage. The key algorithm of this key must be AES, the key type must be PINPRW, and the key usage fields must indicate VERIFY, CMAC, and DKPINOP.

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

new_PRW_key_identifier_length

Direction	Type
Input	Integer

Specifies the length in bytes of the new_PRW_key_identifier parameter. If the new_PRW_key_identifier contains a label, the length must be 64. Otherwise, the value must be between the actual length of the token and 725.

new_PRW_key_identifier

Direction	Type
Input/Output	String

The identifier of the key to generate the new PRW. The key identifier is an operational token or the key label of an operational token in key storage. The key algorithm of this key must be AES, the key type must be PINPRW, and the key usage fields must indicate GENONLY, CMAC, and DKPINOP.

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

new_PIN_reference_value_length

Direction	Type
Input/Output	Integer

Specifies the length in bytes of the new_PIN_reference_value parameter. The value must be at least 16. On output, it will be set to 16.

new_PIN_reference_value

Direction	Type
Output	String

The 16-byte new PIN reference value.

new_PRW_random_number_length

Direction	Type
Input/Output	Integer

Specifies the length in bytes of the new_PRW_random_number parameter. The value must be at least 4. On output, it will be set to 4.

new_PRW_random_number

Direction	Type
Output	String

The 4-byte random number associated with the new PIN reference value.

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 DK PAN Modify in Transaction 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 1. DK PAN Modify in Transaction 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	Crypto Express3 Coprocessor	DK AES PIN key support requires the November 2013 or later licensed internal code (LIC).
IBM zEnterprise EC12 IBM zEnterprise BC12	Crypto Express3 Coprocessor Crypto Express4 CCA Coprocessor	DK AES PIN key support requires the September 2013 or later licensed internal code (LIC).
IBM z13	Crypto Express5 CCA Coprocessor