EMV Scripting Service (CSNBESC and CSNEESC)

CALL CSNBESC(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             issuer_integrity_master_key_identifier_length,
             issuer_integrity_master_key_identifier,
             issuer_confidentiality_master_key_identifier_length,
             issuer_confidentiality_master_key_identifier,
             new_PIN_encrypting_key_identifier_length,
             new_PIN_encrypting_key_identifier,
             current_PIN_encrypting_key_identifier_length,
             current_PIN_encrypting_key_identifier,
             new_PIN_block,
             current_PIN_block,
             pan_length,
             pan,
             pan_seq_number,
             atc,
             unpredictable_number,
             input_message_length,
             input_message,
             PIN_offset,
             PIN_format,
             output_message_length,
             output_message,
             mac_length,
             mac,
             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 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 3 and the maximum value is 5.

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 1. Rule array keywords for EMV Scripting Service

Keyword	Meaning
Algorithm (Required)
TDES	Specifies the use of Triple-DES.
Action (One required)
SMINT	Secure messaging with integrity.
SMCON	Secure messaging with confidentiality. Only MC and EMV key modes supported.
SMCONPIN	Secure messaging with confidentiality for commands containing a PIN.
SMCONINT	Secure messaging with both confidentiality and integrity. Only MC and EMV key modes supported.
SMCIPIN	Secure messaging with both confidentiality and integrity for commands containing a PIN.
VISAPIN	Visa PIN change/unblocking as described in VISA Integrated Circuit Card Specification, v1.4.0.
Key mode (One required). Defines the key derivation mechanism.
VISA	Specifies to use the Visa Cryptogram Version 10 key derivation. Not valid with SMCON and SMCONINT.
MC	Specifies to use the MasterCard M/CHIP 2.1 key derivation. The random_number parameter is used. Padding is according to EMV rules.
EMV	Specifies to use the session key derivation as described in EMV Integrated Circuit Card Specification for Payment Systems Version 4.2 (EMV4.2) Book 2, Annex A1.3.
Control flag (Optional)
APPANSEQ	Specifies to append the PAN sequence number when the card specific master key is derived. See the descriptions of pan and pan_seq_number. The default is not to append the PAN sequence number.
Branch Factor (One optional, valid only with key mode EMV). The branching factor is to be used in EMV session key derivation.
TDESEMV2	Specifies a branch factor of 2 for a height of 16. This is the default.
TDESEMV4	Specifies a branch factor of 4 for a height of 8.

issuer_integrity_master_key_identifier_length

Direction	Type
Input	Integer

Specifies the length of the issuer_integrity_master_key_identifier parameter in bytes. The value must be 0 or 64. When the action keywords SMCON or SMCONPIN is specified, the value must be 0 and the issuer_integrity_master_key_identifier parameter is ignored. Otherwise, the value must be 64 and a key token or label must be supplied in the issuer_integrity_master_key_identifier parameter.

issuer_integrity_master_key_identifier

Direction	Type
Input/Output	String

The 64-byte DES key identifier (either an internal token or key label) for the issuer master key to be used for secure messaging with integrity (actions SMINT, SMCONINT, and SMCIPIN) or the issuer master key for authentication (action VISAPIN).

The issuer master key is the DES key from which the card specific keys and session keys for scripting are derived.

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

Table 2. EMV Scripting Service: Key requirements

Key mode keyword	Key derivation used	Key type	Subtype	Key generating bits
VISA	SESS-XOR	DKYGENKY	0	Must be ‘0010’ (keyword DMAC).
MC	MasterCard M/Chip 2.1	DKYGENKY	1	Must be ‘0010’ (keyword DMAC).
EMV	EMV key derivation	DKYGENKY	0	Must be ‘0010’ (keyword DMAC).

Note: For action VISAPIN, this is the issuer master key for authentication. The key is used for preparing the material used to form the PIN block for PIN change/unblock. The card specific key is derived using the same PAN data as for the other issuer master keys. The key must be of type DKYGENKY, subtype 0, and the key generating bits must be '0010' (keyword DMAC).

issuer_confidentiality_master_key_identifier_length

Direction	Type
Input	Integer

This parameter specifies the length of the issuer_confidentiality_master_key_identifier parameter in bytes. The value must be 0 or 64. When action keyword SMINT is specified, the value must be 0 and the issuer_confidentiality_master_key_identifier parameter is ignored. Otherwise, the value must be 64 and a key token or label must be supplied in the issuer_confidentiality_master_key_identifier parameter.

issuer_confidentiality_master_key_identifier

Direction	Type
Input/Output	String

The 64-byte DES key identifier (either an internal token or key label) for the issuer master key to be used for secure messaging with confidentiality (actions SMCON, SMCONPIN, SMCONINT, SMCIPIN, VISAPIN). The issuer master key is the DES key from which card specific keys and session keys for scripting are derived.

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

Table 3. Key type requirements for actions SMCON and SMCONINT

Key mode keyword	Key derivation used	Key type	Subtype	Key generating bits
VISA	SESS-XOR	DKYGENKY	0	Must be ‘0001’ (keyword DDATA).
MC	MasterCard M/Chip 2.1	DKYGENKY	1	Must be ‘0001’ (keyword DDATA).
EMV	EMV key derivation	DKYGENKY	0	Must be ‘0001’ (keyword DDATA).

Table 4. Key type requirements for actions SMCONPIN, SMCIPIN, and VISAPIN

Key mode keyword	Key derivation used	Key type	Subtype	Key generating bits
VISA	SESS-XOR	DKYGENKY	0	Must be ‘1001’ (keyword DMPIN).
MC	MasterCard M/Chip 2.1	DKYGENKY	1	Must be ‘1001’ (keyword DMPIN).
EMV	EMV key derivation	DKYGENKY	0	Must be ‘1001’ (keyword DMPIN).

new_PIN_encrypting_key_identifier_length

Direction	Type
Input	Integer

Specifies the length of the new_PIN_encrypting_key_identifier parameter in bytes. The value must be 0 or 64. When action keyword VISAPIN is specified, the value must be 64. Otherwise, the value must be 0 and the new_PIN_encrypting_key_identifier parameter is ignored.

new_PIN_encrypting_key_identifier

Direction	Type
Input/Output	String

The 64-byte DES key identifier (either an internal token or key label) for the key that encrypts the new PIN block. The key type can be either IPINENC or OPINENC. There are separate Cryptographic Coprocessor access points required based on the rules selected. For additional information, see Cryptographic services used by EMV Scripting Service and Access control points.

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

current_PIN_encrypting_key_identifier_length

Direction	Type
Input	Integer

Specifies the length of the current_PIN_encrypting_key_identifier parameter in bytes. The value must be 0 or 64. When action keyword SMCONPIN, SMCIPIN, or VISAPIN is specified, the value must be 64. Otherwise, the value must be 0 and the current_PIN_encrypting_key_identifier parameter is ignored.

current_PIN_encrypting_key_identifier

Direction	Type
Input/Output	String

The 64-byte DES key identifier (either an internal token or key label) for the key that encrypts the PIN block with the current PIN.

For actions SMCONPIN and SMCIPIN, the key type must be IPINENC. For action VISAPIN, the key type can be either IPINENC or OPINENC.

There are separate Cryptographic Coprocessor access points required depending on the rules selected. For additional information, see Cryptographic services used by EMV Scripting Service and Access control points.

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

new_PIN_block

Direction	Type
Input	String

The 8-byte PIN block encrypted by the new_PIN_encrypting_key_identifier.

For VISAPIN, this is the new PIN. All PIN block formats are supported. This parameter is ignored for all other action keywords.

current_PIN_block

Direction	Type
Input	String

The 8-byte PIN block for the current PIN encrypted by the current_PIN_encrypting_key_identifier.

When VISAPIN is specified, this is the current PIN. All Pin block formats are supported.

When SMCONPIN or SMCIPIN is specified, PIN block formats supported are ISO-0, ISO-1, and ISO-2.

When the action keyword is SMCON, SMCONINT, or SMINT, this parameter is ignored.

pan_length

Direction	Type
Input	Integer

Length in bytes of the pan parameter. The value must be 10.

pan

Direction	Type
Input	String

The 10-byte EMV card’s Primary Account Number. The data must be in compressed numeric format and right justified in a 10-byte field, padded to the left with zeroes. For example, PAN 1234567890 must be provided as x’00000000001234567890’.

This data is used in combination with the PAN sequence number to derive the card’s master key. The exact set of rules is described in EMV Integrated Circuit Card Specification for Payment Systems Version 4.2 (EMV4.2) Book 2, Annex A1.4.

pan_seq_number

Direction	Type
Input	String

The 1-byte sequence number of the EMV card’s Primary Account Number. If the APPANSEQ control flag rule array keyword was specified, this PAN sequence number is used in combination with the PAN to derive the card’s master key. The exact set of rules is described in EMV Integrated Circuit Card Specification for Payment Systems Version 4.2 (EMV4.2) Book 2, Annex A1.4.

atc

Direction	Type
Input	String

The 2-byte application transaction counter that is used for session key derivation. See the key mode rules for more information on session key derivation.

This parameter must be 2 bytes.

Note: The first byte is the high-order byte and the second byte is the low order byte.

unpredicatable_number

Direction	Type
Input	String

The 8-byte random number for secure messaging with MasterCard M/CHIP 2.1 processing. Only used when key mode is MC. Otherwise, this parameter is ignored.

input_message_length

Direction	Type
Input	Integer

The length of the message supplied in the input_message parameter.

This value must be between 8 and 320, inclusive. For key mode rule VISA, the value must be between 8 and 255, inclusive.

input_message

Direction	Type
Input	String

The message to be secured. Padding is as follows:

For action VISAPIN:

To the left one byte that contains the length of the PIN block (which is 8 bytes) and with an ‘80’ byte followed by a number of ‘00’ bytes until the length is 16 bytes. The output PIN block is 16 bytes for this action. Encryption is done in ECB mode.

For scripting with confidentiality:

The message is only padded if it is not a multiple of eight bytes. EMV padding is used.

For scripting with integrity:

The message is only padded if it is not a multiple of eight bytes. EMV padding is used.

The formatting of the message to the EMV card is the responsibility of the application.

PIN_offset

Direction	Type
Input	Integer

The offset in the message to be secured where the PIN block is to be placed. The first position has offset 0.

This parameter is ignored when the VISAPIN, SMINT, and SMCON keywords are specified.

PIN_format

Direction	Type
Input	String

The 17 bytes consists of two 8 byte fields for input and output PIN block format respectively and a 1 byte for the PAD digit, in case a PAD digit is needed for one of the PIN formats.

The following PIN formats are supported:

For actions SMCONPIN and SMCIPIN:

ISO-0, ISO-1, and ISO-2. Both 8 byte blocks must be fully specified.

For action VISAPIN:

All PIN formats are supported. See ICSF Application Programmer's Guide. Only the first 8 bytes (and maybe the PAD digit) are used for this action.

The pad digit must be specified only when specifying “3624“ for the PIN format.

This parameter is ignored when the SMINT and SMCON keywords are specified.

output_message_length

Direction	Type
Input	Integer

On input, the length of the buffer to receive the processed message. The value must be at least as long as the input message plus any padding.

On output, the actual length of the message returned in the output_message_length parameter.

This parameter is ignored when keyword SMINT is specified.

output_message

Direction	Type
Input	String

The encrypted message when the action keyword is SMCON, SMCONPIN, SMCONINT, SMCIPIN, or VISAPIN.

The formatting of the message to the EMV card is the responsibility of the application.

mac_length

Direction	Type
Input	Integer

The number of bytes of the MAC that are to be returned in the mac parameter. The MAC is returned for secure messaging with integrity. Values 4, 6, and 8 are supported.

This parameter is ignored when keyword SMCOM, SMCONPIN, or VISAPIN is specified.

mac

Direction	Type
Input	String

The MAC value that is calculated for the actions SMINT, SMCONINT, and SMCIPIN.

Note that for actions SMCONINT and SMCIPIN, the result of the integrity protection, the MAC, is output in this parameter and the result of the encryption is in the output message parameter.

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.

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 caller does not require authorization to each of these services, only to the EMV Scripting Service. Additionally, the caller must have the required access control points enabled.

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