EFT

Detailed description

Electronic funds transfer operations.

EFT

The APIs of the EFT(Electronic Funds Transfer) module are intended for user authentication and identity verification operations in Visa and Mastercard transactions.

The identity of the card user can usually be verified in two ways:

1. handwritten signature, compared to a signature card held by the card issuer;
2. through a PIN (Personal Identification Number) entered by the user; PIN verification can be done online, with validation by the card issuer, or offline, using a chip card.

The standards adopted are in accordance with Visa's Payment Technology Standards Manual (October 2007).

In general terms, the process of transferring funds by card follows the flow in the figure below. There are several actors involved in the process. The Cardholder (card holder) presents the card to the shopkeeper (Retailer/Merchant), the authenticity of Cardholder can be verified by means of a PIN, which Cardholder enters at the shopkeeper's station (e.g. a POS terminal, Point of Sale). The PIN is then encrypted (a PIN Block is generated) and the transaction data is sent to an electronic payment service provider contracted by the shopkeeper (Acquirer), which then sends the data to the corresponding card scheme, according to the brand of card used by Cardholder, and from there it is sent to the card issuer, which has the identification, credit and other data about Cardholder and maintains a contract with it to use the service. After analyzing the transaction data, in terms of registration, credit and authentication, among others, the issuer can authorize or refuse the transaction, and this response message travels in the opposite direction.

--- title: Generic electronic funds transfer process --- sequenceDiagram autonumber participant Cardholder participant Merchant participant Network participant Flag participant Bank Cardholder ->> Merchant: Card/PIN/CVV activate Merchant Merchant ->> Network: Data
Transaction deactivate Merchant activate Network Network ->> Flag: Data
Transaction deactivate Network activate Flag Flag ->> Bank: Data
Transaction deactivate Flag activate Bank Bank ->> Flag: $ deactivate Bank activate Flag Flag ->> Network: $ deactivate Flag activate Network Network ->> Merchant: $ deactivate Network activate Merchant Merchant ->> Cardholder: Goods/
Services deactivate Merchant Bank -->> Cardholder: Debit Cardholder -->> Bank: $

From the point of view of the encryption keys used in the process, the process is shown in the figure below. Each actor keeps their own keys, and whenever an encrypted message needs to go from one actor to another, the encryption must be translated, i.e. the corresponding key of the actor who is to decrypt the message must be used.

--- title: Cryptographic keys in the transfer of funds --- sequenceDiagram participant Cardholder participant Merchant participant Network participant Flag participant Bank destroy Cardholder Cardholder ->> Merchant: Card/PIN/CVV destroy Merchant Merchant ->> Network: PIN Block Note over Network: HSM:
PIN Translation Note over Network: ZCMK
AWK
... destroy Network Network ->> Flag: PIN Block Note over Flag: HSM:
PIN Translation Note over Flag: ZCMK
AWK
IWK
... destroy Flag Flag ->> Bank: PIN Block activate Bank Note over Bank: HSM:
PIN Block Verification
CVV Verification Note over Bank: ZCMK
IWK
CVK
PVK
... deactivate Banco

Variations or simplifications of the above scheme can be used, for example when the same entity has more than one role, or there is direct communication from the acquirer to the issuer, as can happen in certain debit transactions.

Observation

1. Each cryptographic key must be dedicated to only one application, as determined by the Visa manual.
2. The sizes entered for the parameters refer to the data; the application must ensure that the buffer passed has enough space for the data plus the terminator character.
3. The EFT module works with PIN sizes from 4 (MIN_EFT_PIN_LEN) to 12 (MAX_EFT_PIN_LEN) digits.

About support for 3-D Secure protocol algorithms:

HSM Dinamo implements the cryptographic algorithms that support the 3-D Secure protocol, developed by Visa. Visa's Verified by Visa and Mastercard's Secure Code services are offered by the brands based on this protocol. The HSM implements the cryptographic card verification algorithms that support the protocol and the services, allowing the HSM user to generate and verify the codes, CVC2 (Card Verification Code 2) and HMAC SHA1 in the case of Mastercard (Secure Payment Application Algorithm) and CAVV (Cardholder Authentication Verification Value, CVV2 with ATN method) in the case of Visa.

HSM supports CAP (Visa) and DPA (Mastercard) authentication mechanisms.

The HSM provides support for ATM Remote Key Loading/Transport through cryptographic functionalities based on RSA and X.509 functions.

The HSM implementation complies with the standards defined in the documentation listed below:

EMVCo

• Integrated Circuit Card Specifications for Payment Systems, Book 2, Security and Key Management v. 4.2, June 2008
• EMV Card Personalization Specification, v. 1.1, July 2007

Visa

• Payment Technology Standards Manual, October 2007
• Visa Certification Authority Public Keys for Visa Smart Debit/Credit (VSDC), February 2007
• Visa Smart Debit/Credit Certification Authority Technical Requirements v. 2.1, April 2006
• 3-D Secure Functional Requirements Access Control Server v. 1.0.2, May 2006
• Visa Integrated Circuit Card v. 1.4.0, October 2001

Mastercard

• M/Chip Lite 2.1 Card Application Specifications for Debit and Credit, April 2003
• M/Chip 4 Version 1.1 Issuer Guide to Debit and Credit Parameter Management, January 2007
• M/Chip 4 Version 1.1 Security & Key Management, June 2006
• Public Key Infrastructure (PKI) - Certification Authority Interface Specification, January 2005
• Public Key Infrastructure (PKI) - Certification Authority Member Procedures, January 2006
• SPA Algorithm for the MasterCard Implementation of 3-D Secure v1.04, May 2004

Link

• ELO Chip Card, CCD Cryptographic Algorithms, no version, no date.
• Elo Certificate Authority Manual - Issuer's Guide, version 1.2, September 2011

JCB

• JCB IC Card Specification, v. 2.0, October 2012
• JCB CA Interface Guide, unversioned, January 2014
• JCB Key Guide, unversioned, January 2014

Others

• ANSI X9.24 part 1, Retail Financial Services Symmetric Key Management Part 1: Using Symmetric Techniques
• ASC X9 TR 31-2018, Interoperable Secure Key Exchange Key Block Specification, April 15, 2018
• ASC X9 TR 34-2019, Interoperable Method for Distribution of Symmetric Keys using Asymmetric Techniques: Part 1 - Using Factoring-Based Public Key Cryptography Unilateral Key Transport, September 22, 2019
• IBM z/OS V1R9.0 Cryptographic Services ICSF Application Programmer's Guide (3624 PIN Formats and Algorithms)
• ISO/IEC 9797-1 Method 2, Information technology - Security techniques - Message Authentication Codes (MACs) - Part 1, 1999
• IDTECH USER MANUAL SecureMag Encrypted MagStripe Reader (80096504-001 RevL 06/19/14)

Mechanisms of CVV

There are three ways of generating and verifying CVV(Card Verification Value) in HSM:

1. Card Verification Value (CVV), for magnetic stripe card transactions;
2. Card Verification Value 2 (CVV 2); for transactions without the physical presence of the card (via telephone, post or Internet, for example);
3. Alternate Card Verification Value (iCVV), for chip card transactions; The calculation mechanism is the same in all three forms, and the difference lies in the way the application enters the data.

The key used for CVV generation and verification calculations is called CVK(Card Verification Key). This key is internal to the HSM; the application only needs to enter its key name (id). Physically, it is a 112-bit 3DES key, which corresponds to two 56-bit DES keys.

The figure below illustrates the diagrams for generating and verifying CVV, iCVV and CVV2.

--- title: Geração de CVV / iCVV / CVV2 --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TB PAN[PAN] Service[Código de serviço / 99/ 000] Data[Data de expiração] CVKid[CVK id] H[\"HSM: CVK (3DES 112)"/] cvv((CVV)) icvv((iCVV)) cvv2((CVV 2)) PAN --> H Service --> H Data --> H CVKid --> H H --> cvv H --> icvv H --> cvv2

PIN mechanisms

HSM works by generating PINs (Personal Identification Numbers) using a derivation mechanism, based on an internal key called PGK(PIN Generation Key). This form of generation has several advantages, especially compared to the method of generating PINs with random values, as it does not require the use of a database for validation (with the probable exposure of sensitive data) and also keeps both the generation and validation processes more secure, as they are carried out internally to the HSM.

The standard used to generate the PIN by the HSM is IBM 3624, using offsets to allow the PIN to be changed by the user or the card issuer. To mitigate decimalization and verification attacks, the HSM uses an internal conversion table, which is not exposed to the application. As an additional security factor, a 168-bit 3DES key is used instead of a 112-bit 3DES; there is no interference in the operation of the algorithm, since the DES and 3DES keys use input and output blocks of the same size.

--- title: Geração de PIN por derivação --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TB PAN[PAN] InPIN[InPIN] Offset[offset] PGKid[PGK id] H[\"HSM: CVK (3DES 112)"/] r((PIN)) PAN --> H InPIN --> H Offset --> H PGKid --> H H --> r

Three PIN generation modes are defined per derivation:

1. from the PAN(Personal Account Number), the entry PIN (inPIN) and the PGK;
2. from an input PIN and the PGK, using an offset allows the user to change the PIN;
3. from the PAN, the PGK and an input PIN, with the use of an offset allows automatic PIN change;

There is no business rule handling for PINs generated within the HSM; this function must be performed by the calling application.

The algorithms for generation using the IBM 3624 standard are shown in the diagrams below.

--- title: Algoritmo de Geração de PIN IBM 3624 --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TD Dado{{Dado de Validação}} PGK{{PGK}} Op3DES[\Operação 3DES/] Troca[Troca de dígito] Ajuste[Ajuste de tamanho] Pin((PIN)) Dado --> Op3DES PGK --> Op3DES Op3DES -- Tabela de decimalização interna --> Troca Troca -- PIN Intermediário --> Ajuste Ajuste --> Pin

To allow the user(cardholder) to select their own PIN, a PIN offset is used in the IBM 3624 method, so that two new entries are required, the PIN set by the user and a check of 4 bits. The offset operation is performed after the steps of the IBM 3624 algorithm shown above. This enables the HSM's internal process to validate the PIN, even if the user defines a different PIN to the one initially generated by the HSM.

--- title: Algoritmo de Geração de PIN IBM 3624 com offset --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TD Dado{{Dado de Validação}} PGK{{PGK}} Op3DES[\Operação 3DES/] Troca[Troca de dígito] Ajuste[Ajuste de tamanho] Sub[\"Subtração em módulo 10
(InPin -PIN)"/] OpOff[\Operação de offset no PIN/] Pin((PIN)) InPin{{"InPin
(PIN gerado pelo usuário)"}} Of{{"dado de offset
(4-bit)"}} Dado --> Op3DES PGK --> Op3DES Op3DES -- Tabela de decimalização interna --> Troca Troca -- PIN Intermediário --> Ajuste Ajuste --> Sub Sub --> OpOff OpOff --> Pin InPin --> Sub Of --> OpOff

PIN BlockTranslate operations work with two keys, one source and one destination; there is an intermediate phase to make the input format compatible with the output format, if possible. There are certain block formats that are not interoperable, either because there is no data for conversion or because the standard is restricted.

HSM's default translation mode involves translating the input block into ISO PIN Block Format 0. In automatic translation mode, the conversion is performed opaquely, converting from the block with the source key to the block with the target key, without analyzing the format or content of the block.

--- title: Operação de PIN Translate --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TD blockin{{Bloco de entrada}} keyin{{Chave de entrada}} OpDES1[\DES/] Prep[Preparação] OpDES2[\DES/] keyout{{Chave de destino}} blockout{{Bloco da saída}} blockin --> OpDES1 keyin --> OpDES1 OpDES1 --> Prep Prep --> OpDES2 keyout --> OpDES2 OpDES2 --> blockout

When verifying a PIN Block, two key operations take place: first the PIN Block is decrypted using the PTK(PIN Transport Key), the PIN is extracted from the decrypted PIN Block, and then the PIN is verified using the PGK(PIN Generation Key, the same key used to generate the original PIN). This verification can be done with or without the use of an offset; this PIN offset is not part of the PIN Block and is not encrypted by the PTK. The expected PIN Block format is ISO PIN Block Format 0 (equivalent to ANSI PIN Block Format 0 and VISA PIN Block Format 1).

--- title: Operação de Verificação de PIN Block --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TD pinblock{{PIN Block}} ptk{{PTK}} OpDES1[\DES/] Prep[PIN, PAN, ...] pin[PIN] pgk{{PGK}} off{{offset}} OpDES2[\3DES/] r((Result)) ptk --> OpDES1 pinblock --> OpDES1 OpDES1 --> Prep Prep --> pin pin --> OpDES2 pgk --> OpDES2 off --> OpDES2 OpDES2 --> r

Mechanisms of DUKPT

DUKPT(Derived Unique Key Per Transaction) is a way of using unique keys per transaction, derived from a fixed key. This process is defined in ANSI X9.24 part 1.

The KSN(Key Serial Number) is the identifier of a transaction key and is divided into parts such as: KSI(Key Set ID), TRSM(Tamper Resistant Security Module), POS (Point of Sale) identifier also known as DID (Device ID) and the CTR(Transaction Counter).

--- title: DUKPT key generation --- sequenceDiagram participant hsm as HSM participant pos as PoS/ATM
Device Note over hsm: BDK activate hsm hsm ->> hsm: IPEK (Device Id) deactivate hsm hsm ->> pos: IPEK Note over pos: IPEK

HSM uses the parts of KSN separated into KSI and DID + CTR each containing 5 bytes.

The steps in the process of using DUKPT are, at each end of the communication:

At the POS:

1. Previously initialized with an IPEK derived from a BDK.
2. Generates (or retrieves from a table of future keys) the future key using the DID and CTR.
3. Encrypts the required block (e.g. PIN Block).
4. Sends KSN + encrypted block. KSN is made up of TRMS (or DID), KSI and CTR.
5. Increases internal CTR.

At HSM:

1. Receives KSN + Encrypted Block.
2. Selects the appropriate BDK based on the KSN received. KSN is made up of TRMS (or DID), KSI and CTR.
3. Generates the IPEK based on the selected BDK and KSN.
4. It uses the IPEK, DID and CTR contained in the KSN to generate the session key.
5. Decrypts the Block and does the necessary processing.
6. The POS has an IPEK(Initial Pin Encryption Key) derived from a BDK(Base Derivation Key). This BDK is stored within the HSM and is used in the regeneration of the IPEK of the respective POS and then this IPEK is used in the derivation of the unique transaction keys of this POS.

--- title: DUKPT communication between POS/ATM and HSM --- sequenceDiagram participant pos as PoS/ATM
Device participant hsm as HSM Note over pos: IPEK activate pos pos ->> pos: KSI,CTR pos ->> pos: Session key pos ->> pos: Plain text > cipher block deactivate pos pos ->> hsm: cipher block
TRSM (Device Id)
KSI
CTR activate hsm Note over hsm: BDK hsm ->> hsm: IPEK (Device Id) hsm ->> hsm: KSI,CTR hsm ->> hsm: Session key hsm ->> hsm: cipher block > clear text deactivate hsm

Key-wrapping TR-31

It is a wrapping/_unwrapping_ process with confidentiality and integrity protection for keys and associated data, defined in the ASC X9 TR 31-2018 document.

KBPK(Key Block Protection Key) is the derivation key used to derive the encryption and authentication keys. This key is only used for derivation. Also known as KWK (Key Wrapping Key). Stored in the HSM.

KBEK(Key Block Encryption Key) is the key derived from KBPK and used only for key klock encryption. It is generated with each wrap/unwrap operation and is not stored persistently in the HSM.

KBAK(Key Block Authentication Key) is the key derived from KBPK and used only for calculating the MAC of the key klock. It is generated with each wrap/unwrap operation and is not stored persistently in the HSM.

KDID(Key Derivation Input Data) is the data used to derive the KBEK and KBAK keys. It contains data such as: counter, key usage indicator, algorithm indicator and size. It varies according to the derivation method used, the key to be derived and other parameters.

The derivation of the KBEK and KBAK keys uses CMAC with the Key Derivation Input Data (specific to each derived key) and the KBPK key as input.

--- title: Processo de derivação KBEK e KBAK --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TD kbekin("Key derivation
input data
KBEK") kbakin("Key derivation
input data
KBAK") cmac1([CMAC]) kbpk(KBPK) cmac2([CMAC]) kbek("Key Block
Encryption Key") kbak("Key Block
Authentication Key") kbekin --> cmac1 kbakin --> cmac2 cmac1 --> kbek cmac2 --> kbpk cmac2 --> kbak cmac1 --> kbpk

Key block contains the data of the exported key. This block is divided into 3 parts:

1. KBH(Key Block Header) contains information about the key and the key block.

1. The confidential data that will be sent/saved. It is encrypted with the KBEK key. The input data for encryption is: the key size, the key and the padding.

1. The MAC that connects the KBH and the encrypted key block. It is generated using the KBAK key. The input data for the MAC operation is: the KBH, and the input data for encryption.

%%{init: { 'theme': 'dark' } }%% timeline title Processo de Geração do Key Block section KBH section Bloco Cifrado Inputs#58; : tamanho da chave : chave KBEK : padding section MAC Inputs#58; : KBH : tamanho da chave : chave KBAK : padding

Definitions

• KSN: Key Serial Number
• KSI: Key Set ID
• TRSM: Tamper Resistant Security Module
• POS: Point of Sale
• CTR: Transaction Counter
• DID: Device ID
• BDK: Base Derivation Key
• IPEK: Initial Pin Encryption Key
• ATM: Automatic Teller Machine
• KBPK: Key Block Protection Key
• KBEK: Key Block Encryption Key
• KBAK: Key Block Authentication Key
• AESKW: AES Key Wrap
• TDKW: Tripple DES Key Wrap
• KWK: Key Wrapping Key
• KBH: Key Block Header

Functions
String	generateDUKPT (byte[] baKSI, byte[] baDID_CTR, int dwParam) throws TacException
	It generates a DUKPT key within the HSM using a KSI (Key Serial Identification), a DID (Device ID) and a CTR (Transaction Counter) from the same KSN (Key Serial Number).
String	generateDUKPTName (byte[] baKSI, byte[] baDID_CTR) throws TacException
	Generates the name of the DUKPT from an entered KSI and CTR.
String	generateBDKName (byte[] baKSI) throws TacException
	Generates the BDK name from a KSI (Key Serial Identification).
byte[]	translatePINBlock (String srcPEK, String dstPEK, int transBlockType, String PAN, byte[] inPINBlock) throws TacException
	It translates a PIN block, decrypting it with one key and encrypting it with another.
byte[]	exportTR31 (String kbpk, String key, int usage, byte mode, byte export) throws TacException
	Exports a key in TR-31 format according to the ASC X9 TR 31-2018 standard.
void	importTR31 (String kbpk, String key, int keyAttributes, byte[] keyBlock) throws TacException
	Import a key in TR-31 format according to the ASC X9 TR 31-2018 standard.

Functions

generateDUKPT()

String generateDUKPT	(	byte[]	baKSI,
		byte[]	baDID_CTR,
		int	dwParam ) throws TacException

It generates a DUKPT key within the HSM using a KSI (Key Serial Identification), a DID (Device ID) and a CTR (Transaction Counter) from the same KSN (Key Serial Number).

Parameters

baKSI	Buffer of size TacNDJavaLib.MIN_KSI_LEN containing the KSI (first 05 bytes of the KSN).
baDID_CTR	Buffer of size TacNDJavaLib.MIN_CTR_LEN containing the DID and CTR (last 05 bytes of the KSN).
dwParam	Operating flags according to the table below. Value Meaning TacNDJavaLib.NEW_DUKPT_MODE_DUK Generates a standard DUK (Derived Unique Key) according to the ISO X9.24-1-2004 manual. TacNDJavaLib.NEW_DUKPT_MODE_PEK Generates a PEK key (PIN Encryption Key) according to the ISO X9.24-1-2004 A-1,A-6 manual by applying the XOR of the 0000 0000 0000 FF00 mask to the parts of the key. TacNDJavaLib.NEW_DUKPT_MODE_MEK Generates a MEK key (MAC Encryption Key) according to the ISO X9.24-1-2004 A-1,A-6 manual by applying the XOR of the 0000 0000 0000 00FF mask to the parts of the key. TacNDJavaLib.NEW_DUKPT_MODE_DE Diversifies the generated key in Data Encryption format. It applies an XOR of the 0000 0000 00FF 0000 0000 00FF 0000 mask to the generated DUKPT key, encrypts the left key of the DUKPT using the generated DUKPT and repeats the encryption with the right key. After this operation, it joins the encrypted left and right parts to form the Data Encryption Key. As described in IDTECH USER MANUAL SecureMag Encrypted MagStripe Reader (80096504-001 RevL 06/19/14). It must be used in combination (via OR operation) with one of the flags: TacNDJavaLib.NEW_DUKPT_MODE_DUK, TacNDJavaLib.NEW_DUKPT_MODE_PEK or TacNDJavaLib.NEW_DUKPT_MODE_MEK. TacNDJavaLib.NEW_DUKPT_MODE_EXP Generates an exportable DUKPT key. This is an attribute flag and should be used in combination with other flags. Only use if specifically required. TacNDJavaLib.NEW_DUKPT_MODE_TMP Generates a temporary DUKPT key. This is an attribute flag and should be used in combination with other flags.

Return

Returns the name of the generated DUKPT key.

Exceptions

TacException

generateDUKPTName()

String generateDUKPTName	(	byte[]	baKSI,
		byte[]	baDID_CTR ) throws TacException

Generates the name of the DUKPT from an entered KSI and CTR.

Parameters

baKSI	Buffer of size TacNDJavaLib.MIN_KSI_LEN containing the KSI (first 05 bytes of the KSN).
baDID_CTR	Buffer of size TacNDJavaLib.MIN_CTR_LEN containing the DID and CTR (last 05 bytes of the KSN).

Return

Returns the name of the DUKPT key.

Exceptions

TacException

generateBDKName()

String generateBDKName

(

byte[]

baKSI

)

throws TacException

Generates the BDK name from a KSI (Key Serial Identification).

Parameters

baKSI

Buffer of size TacNDJavaLib.MIN_KSI_LEN containing the KSI (first 05 bytes of the KSN).

Return

Returns the name of the BDK key.

Exceptions

TacException

translatePINBlock()

byte[] translatePINBlock	(	String	srcPEK,
		String	dstPEK,
		int	transBlockType,
		String	PAN,
		byte[]	inPINBlock ) throws TacException

It translates a PIN block, decrypting it with one key and encrypting it with another.

The incoming block format is identified automatically, and the outgoing block format can be defined by the caller, as long as the format change is not from a PAN Unbound to a PAN Bound. PAN Bound formats are those that use PAN information in their composition. It is therefore possible to perform both key translation and format translation. The caller can perform a forced validation of the format by indicating for the outgoing format, the same one they are using in the incoming PIN Block.

Parameters

srcPEK	Identifier of the decryption key within the HSM.
dstPEK	Identifier of the encryption key within the HSM.
transBlockType	Output block format identifier. According to the table below. Value Meaning TacNDJavaLib.TP_TRANSLATE_TYPE_AUTO It performs an opaque conversion, translating from the block with the source key to the block with the target key, without analyzing the format or content of the block. PAN Bound: does not apply. TacNDJavaLib.TP_TRANSLATE_TYPE_ISO_0 Uses ISO PIN Block Format 0 (equivalent to ANSI PIN Block Format 0 and VISA PIN Block Format 1). PAN Bound: yes. TacNDJavaLib.TP_TRANSLATE_TYPE_ISO_1 Uses ISO PIN Block Format 1. PAN Bound: no. TacNDJavaLib.TP_TRANSLATE_TYPE_ISO_3 Uses ISO PIN Block Format 3. PAN Bound: yes. TacNDJavaLib.TP_TRANSLATE_TYPE_IBM_3624 IBM 3624 block type used. Not implemented.
PAN	PAN (Primary Account Number).
inPINBlock	PIN Block input. The buffer must have the size of a PIN Block, TacNDJavaLib.DES_BLOCK (8 bytes)

Return

PIN block output.

Exceptions

TacException

Notes

In the case of a non-opaque conversion, i.e. a format translation, if the input PIN Block format cannot be recognized, a D_ERR_OPERATION_FAILED error will be returned.
The ISO PIN Block Format 2 method is not implemented in the HSM, as this format is intended to be used to protect the PIN when it is submitted from the chip card reader.

exportTR31()

byte[] exportTR31	(	String	kbpk,
		String	key,
		int	usage,
		byte	mode,
		byte	export ) throws TacException

Exports a key in TR-31 format according to the ASC X9 TR 31-2018 standard.

Parameters

kbpk	Name of the KBPK key (Key Block Protection Key) used to derive the encryption and authentication keys.
key	Name of the key to be exported from the HSM.
usage	Key usage identifier, as described in ASC X9 TR 31-2018 Section A.5.1 table 6. The following options are accepted. Value Meaning TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_AUTO Sets the identifier automatically. The following values are used: TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D0 for symmetric key and TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D1 for asymmetric key. TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_B0 BDK Base Derivation Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_B1 Initial DUKPT Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_B2 Base Key Variant Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_C0 CVK Card Verification Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D0 Symmetric Key for Data Encryption TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D1 Asymmetric Key for Data Encryption TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D2 Data Encryption Key for Decimalization Table TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E0 EMV/chip Issuer Master Key: Application cryptograms TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E1 EMV/chip Issuer Master Key: Secure Messaging for Confidentiality TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E2 EMV/chip Issuer Master Key: Secure Messaging for Integrity TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E3 EMV/chip Issuer Master Key: Data Authentication Code TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E4 EMV/chip Issuer Master Key: Dynamic Numbers TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E5 EMV/chip Issuer Master Key: Card Personalization TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E6 EMV/chip Issuer Master Key: Other TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_I0 Initialization Vector (IV) TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_K0 Key Encryption or wrapping TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_K1 TR-31 Key Block Protection Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_K2 TR-34 Asymmetric key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_K3 Asymmetric key for key agreement/key wrapping TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M0 ISO 16609 MAC algorithm 1 (using TDEA) TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M1 ISO 9797-1 MAC Algorithm 1 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M2 ISO 9797-1 MAC Algorithm 2 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M3 ISO 9797-1 MAC Algorithm 3 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M4 ISO 9797-1 MAC Algorithm 4 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M5 ISO 9797-1:1999 MAC Algorithm 5 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M6 ISO 9797-1:2011 MAC Algorithm 5/CMAC TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M7 HMAC TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M8 ISO 9797-1:2011 MAC Algorithm 6 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_P0 PIN Encryption TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_S0 Asymmetric key pair for digital signature TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_S1 Asymmetric key pair, CA key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_S2 Asymmetric key pair, non-X9.24 key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V0 PIN verification, KPV, other algorithm TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V1 PIN verification, IBM 3624 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V2 PIN Verification, VISA PVV TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V3 PIN Verification, X9.132 algorithm 1 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V4 PIN Verification, X9.132 algorithm 2
mode	Key usage mode identifier, as described in ASC X9 TR 31-2018 Section A.5.3 table 8. The following options are accepted. Value Meaning TacNDJavaLib.EFT_ME_TR31_EXP_MODE_AUTO Sets the usage mode identifier automatically. The following value is used TacNDJavaLib.EFT_ME_TR31_EXP_MODE_N. TacNDJavaLib.EFT_ME_TR31_EXP_MODE_B Both Encryption & Decryption / Wrap & Unwrap TacNDJavaLib.EFT_ME_TR31_EXP_MODE_C Both Generation & Verification TacNDJavaLib.EFT_ME_TR31_EXP_MODE_D Decryption / Unwrap Only TacNDJavaLib.EFT_ME_TR31_EXP_MODE_E Encryption / Wrap Only TacNDJavaLib.EFT_ME_TR31_EXP_MODE_G Generation Only TacNDJavaLib.EFT_ME_TR31_EXP_MODE_N No special restrictions (except those defined by the key usage identifier) TacNDJavaLib.EFT_ME_TR31_EXP_MODE_S Signature Only TacNDJavaLib.EFT_ME_TR31_EXP_MODE_T Both Signature & Decryption TacNDJavaLib.EFT_ME_TR31_EXP_MODE_V Verification only TacNDJavaLib.EFT_ME_TR31_EXP_MODE_X Key used to derive other key(s) TacNDJavaLib.EFT_ME_TR31_EXP_MODE_Y Key used to create key variants
export	Key exportability identifier, as described in ASC X9 TR 31-2018 Section A.5.5 table 10. The following options are accepted. Value Meaning TacNDJavaLib.EFT_ME_TR31_EXP_AUTO Defines the exportability identifier automatically. The following value is used TacNDJavaLib.EFT_ME_TR31_EXP_X9_24. TacNDJavaLib.EFT_ME_TR31_EXP_X9_24 Exportable under a KEK (Key Encryption Key) in a format meeting that defined in the requirements of X9.24 Parts 1 or 2. TacNDJavaLib.EFT_ME_TR31_EXP_NON_EXPORTABLE Not exportable by the recipient of the Key Block, or storage location. Does not prevent the export of keys derived from a non-exportable key. TacNDJavaLib.EFT_ME_TR31_EXP_KEK_EXPORTABLE Sensitive, Exportable under a KEK (Key Encryption Key) in a format not necessarily in accordance with the requirements of X9.24 Parts 1 or 2.

Return

key block

Exceptions

TacException

Notes

This API exports a key using the methods for generating key_block below.

KBPK algorithm	Export method
3DES	5.3.2.1 Key Derivation Binding Method - TDEA
AES	5.3.2.3 Key Block Binding Method - AES

importTR31()

void importTR31	(	String	kbpk,
		String	key,
		int	keyAttributes,
		byte[]	keyBlock ) throws TacException

Import a key in TR-31 format according to the ASC X9 TR 31-2018 standard.

Parameters

kbpk	Name of the KBPK key (Key Block Protection Key) used to derive the encryption and authentication keys.
key	Name of the key to be imported into the HSM.
keyAttributes	Additional key parameters. See the options in the createKey() method.
keyBlock	key block

Exceptions

TacException

Notes

This API imports keys protected by the generation methods of the key_block.

KBPK algorithm	Method
3DES	5.3.2.1 Key Derivation Binding Method - TDEA
AES	5.3.2.3 Key Block Binding Method - AES