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
KBEK Input : tamanho da chave : chave : padding section MAC
KBAK Input : KBH : tamanho da chave : chave : 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

Data Structures
class	DinamoClient.PinComponents
	Class that encapsulates the PIN generation components. More...

Enumerations
enum	GenPINOperation : UInt32 { DEFAULT_PIN = DinamoApi.GP_DEFAULT_PIN , USER_DEF_PIN = DinamoApi.GP_USER_DEF_PIN , RANDOM_PIN = DinamoApi.GP_RANDOM_PIN }
	PIN operation options. More...

Functions
string	GenBDKName (byte[] pbKSI)
	Generates the BDK name from a KSI (Key Serial Identification).
string	GenBDKName (byte[] pbKSI, uint dwParam)
	Generates the BDK name from a KSI (Key Serial Identification).
string	GenDUKPT (byte[] pbKSI, byte[] pbDID_CTR, uint dwParam)
	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	GenCVV (string keyId, string pan, string expirationDate, string serviceCode)
	It generates a CVV (Card Verification Value), CVV2 or iCVV using a key within the HSM. This API can also be used to generate card verification codes that support the 3-D Secure protocol. In the case of Visa, the service that implements the protocol is Verified by Visa, and the HSM supports the CAVV standard (Cardholder Authentication Verification Value, which is CVV2 with ATN method). In Mastercard's case, the 3-D Secure protocol is implemented in the SecureCode service, and the HSM supports the CVC2 (Card Verification Code 2) and HMAC SHA1 standards.
bool	VerifyCVV (string keyId, string pan, string expirationDate, string serviceCode, string cvv)
	It verifies a CVV (Card Verification Value), CVV2 or iCVV using a key within the HSM. The API can also be used to verify card verification codes that support the 3-D Secure protocol. See more details in the GenCVV() API.
PinComponents	GenPIN (string pgk, string pan, GenPINOperation operation, int pinLen, string inPin)
	Performs PIN generation operations from the PAN (Personal Account Number) and PGK (Key Name) data entered, with or without the use of offset.
bool	VerifyPINBlock (string ptk, string pgk, string pan, string offset, byte[] pinblock)
	Checks the validity of a PIN in a PIN Block. First the PIN is extracted from the PIN Block with the PTK key, and then it is verified with the PGK key, the same one that was used to generate the PIN, with the GenPIN() function.
byte[]	ExportTR31 (string kbpk, string key, EftExportUsage usage, EftExportMode mode, EftExportExpType exp)
	Exports a key in TR-31 format according to the ASC X9 TR 31-2018 standard.
void	ImportTR31 (string kbpk, string key, bool isExportable, bool isTemporary, byte[] keyBlock)
	Import a key in TR-31 format according to the ASC X9 TR 31-2018 standard.

Enumerations

GenPINOperation

enum GenPINOperation: UInt32

PIN operation options.

Enumerators
DEFAULT_PIN
USER_DEF_PIN
RANDOM_PIN

Examples

eft_gen_pin.cs.

Functions

GenBDKName() [1/2]

string GenBDKName ( byte[]  pbKSI )

inline

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

Parameters

pbKSI

Buffer of size MIN_KSI_LEN containing the KSI.

Return

The name of the BDK key generated from KSI is entered in pbKSI.

Exceptions

DinamoException

Throws exception in case of error.

Examples

dukpt.cs.

GenBDKName() [2/2]

string GenBDKName ( byte[]  pbKSI, uint  dwParam  )

inline

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

Parameters

pbKSI	Buffer of size MIN_KSI_LEN containing the KSI.
dwParam	Reserved for future use.

Return

The name of the BDK key generated from KSI is entered in pbKSI.

Exceptions

DinamoException

Throws exception in case of error.

GenDUKPT()

string GenDUKPT ( byte[]  pbKSI, byte[]  pbDID_CTR, uint  dwParam  )

inline

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

pbKSI	Buffer of size MIN_KSI_LEN containing the KSI.
pbDID_CTR	Buffer of size MIN_CTR_LEN containing the DID and CTR (last 05 bytes of the KSN).
dwParam	Operation flags according to the table below. NEW_DUKPT_MODE_DUK : Generates a standard DUK (Derived Unique Key) key according to the ISO X9.24-1-2004 manual. NEW_DUKPT_MODE_PEK : Generates a PEK (PIN Encryption Key) key according to the ISO X9.24-1-2004 A manual by applying the XOR of the 0000 0000 0000 FF00 mask to the parts of the key. NEW_DUKPT_MODE_MEK : Generates a MEK key (MAC Encryption Key) according to the ISO X9.24-1-2004 A manual by applying the XOR of the mask 0000 0000 0000 00FF to the parts of the key. NEW_DUKPT_MODE_DE : Diversifies the key generated in Data Encryption format. It applies an XOR of the mask 0000 0000 00FF 0000 0000 00FF 0000 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). Must be used in combination (via OR operation) with one of the flags: NEW_DUKPT_MODE_DUK, NEW_DUKPT_MODE_PEK or NEW_DUKPT_MODE_MEK 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. NEW_DUKPT_MODE_TMP : Generates a temporary DUKPT key. This is an attribute flag and should be used in combination with other flags. NEW_DUKPT_MODE_IPEK : Generates an IPEK key (Initially Loaded PIN Entry Device Key) in accordance with the ISO X9.24-1-2004 A-6 manual.

Return

The name of the BDK key generated from KSI is entered in pbKSI.

Exceptions

DinamoException

Throws exception in case of error.

Examples

dukpt.cs.

GenCVV()

string GenCVV ( string  keyId, string  pan, string  expirationDate, string  serviceCode  )

inline

It generates a CVV (Card Verification Value), CVV2 or iCVV using a key within the HSM. This API can also be used to generate card verification codes that support the 3-D Secure protocol. In the case of Visa, the service that implements the protocol is Verified by Visa, and the HSM supports the CAVV standard (Cardholder Authentication Verification Value, which is CVV2 with ATN method). In Mastercard's case, the 3-D Secure protocol is implemented in the SecureCode service, and the HSM supports the CVC2 (Card Verification Code 2) and HMAC SHA1 standards.

Parameters

keyId	Identifier of the key within the HSM. This identifier must not contain spaces or special characters. Uppercase and lowercase characters are case-sensitive. This key is the CVK (Card Verification Key), a 112-bit 3DES key, and must be the same as the one used for CVV verification. This key can be generated internally in the HSM or imported manually. Normally this key is also used at Visa, sent encrypted by ZCMK (Zone Contro Master Key). As determined in the Visa manual, the 3DES 112 key used as a CVK must be different from the key used for PIN generation and verification and must not be used for other issuer applications, with the exception of CVV2 and iCVV.
pan	PAN (Primary Account Number). Size from 12 to 19 characters. For the calculation of CVV, CVV2 and iCVV, according to the Visa standard in the 2007 Payment Technology Standards Manual, the PAN length is independent. For the calculation of CVC2, according to the Mastercard document SPA Algorithm for the MasterCard Implementation of 3-D Secure - v1.04, the size of the PAN must be exactly 16 digits; when it is smaller, it must be completed on the left with zeros, and when it is larger, only the rightmost 16 digits must be used.
expirationDate	Expiration date. 4-digit length. When generating CVVs and iCVVs, the format must be YYMM. When generating CVV2, the format must be MMYY. When calculating CVC2, this field must be a string ending in zero with the 4 least significant digits of the Transaction Sequence Number, contained in the AVV (Accountholder Authentication Value) converted into the equivalent decimal BCD. Any value smaller than 4 digits must be completed on the left with zeros until it reaches 4 digits. For more details see the Mastercard document SPA Algorithm for the MasterCard Implementation of 3-D Secure - v1.04. When calculating CAVV (CVV2 with the ATN Method), this field must be a zero-ended string with the 4 least significant digits of the ATN (Authentication Tracking Number). For more details see the Visa document 3-D Secure Functional Requirements Access Control Server v. 1.0.2.
serviceCode	Service Code. 3-digit length. For iCVV (Alternate Card Verification Value) generation, the Service Code must be 999. For CVV 2 generation, the Service Code must be 000. For traditional CVV generation, the Service Code is usually 101.

Return

The generated CVV, with a length of 3 digits. The value generated can also be a CVV2 or iCVV, depending on the Service Code values entered.

Exceptions

DinamoException

Throws exception in case of error.

Notes

The API is also compatible with the American Express standard.

Examples

eft_gen_verify_cvv.cs.

VerifyCVV()

bool VerifyCVV ( string  keyId, string  pan, string  expirationDate, string  serviceCode, string  cvv  )

inline

It verifies a CVV (Card Verification Value), CVV2 or iCVV using a key within the HSM. The API can also be used to verify card verification codes that support the 3-D Secure protocol. See more details in the GenCVV() API.

Parameters

keyId	Identifier of the key within the HSM. This identifier must not contain spaces or special characters. Uppercase and lowercase characters are case-sensitive. This key is the CVK (Card Verification Key), a 112-bit 3DES key, and must be the same as the one used to generate the CVV.
pan	PAN (Primary Account Number). Length from 12 to 19 characters. See more details about this field in the GenCVV() API.
expirationDate	Expiration date. 4-digit length. For CVV and iCVV verification, the format must be YYMM. For CVV 2 verification the format must be MMYY. For information on support for 3-D Secure protocol algorithms, see more details on this field in the GenCVV() API.
serviceCode	Service Code. 3-digit length. For iCVV (Alternate Card Verification Value) verification, the Service Code must be 999. For CVV 2 verification, the Service Code must be 000
cvv	CVV to be validated. 3-digit length. The value entered can also be a CVV2 or iCVV, depending on the Service Code values entered.

Return

true if the CVV has been successfully validated and false if it is invalid.

Exceptions

DinamoException

Throws exception in case of error.

Examples

eft_gen_verify_cvv.cs.

GenPIN()

PinComponents GenPIN ( string  pgk, string  pan, GenPINOperation  operation, int  pinLen, string  inPin  )

inline

Performs PIN generation operations from the PAN (Personal Account Number) and PGK (Key Name) data entered, with or without the use of offset.

Parameters

pgk	PGK (PIN Generation Key) key identifier, within the HSM.
pan	PAN (Primary Account Number).
operation	Type of PIN generation. According to the table below. Value Meaning GenPINOperation.DEFAULT_PIN Generates the default PIN based on PAN and PGK. The inPin parameter must be null. GenPINOperation.USER_DEF_PIN Generates an offset for the PIN set by the caller. The inPin parameter must contain the PIN. GenPINOperation.RANDOM_PIN Randomly generates a PIN and offset based on PAN and PGK. inPin must be null.

Parameters

pinLen	PIN size to be used/generated in the operation. It must be between DinamoApi.MIN_EFT_PIN_LEN and DinamoApi.MAX_EFT_PIN_LEN.
inPin	Input PIN. It must have a size between DinamoApi.MIN_EFT_PIN_LEN and DinamoApi.MAX_EFT_PIN_LEN.

Return

PIN and offset.

Exceptions

DinamoException

Throws exception in case of error.

Examples

eft_gen_pin.cs.

VerifyPINBlock()

bool VerifyPINBlock ( string  ptk, string  pgk, string  pan, string  offset, byte[]  pinblock  )

inline

Checks the validity of a PIN in a PIN Block. First the PIN is extracted from the PIN Block with the PTK key, and then it is verified with the PGK key, the same one that was used to generate the PIN, with the GenPIN() function.

Parameters

ptk	Identifier of the "PIN Block" decryption key within the HSM. PIN Transport Key (PTK).
pgk	Identifier of the key to be used for PIN verification within the HSM. PIN Generation Key (PGK).
pan	PAN (Primary Account Number).
offset	PIN offset. It must be between DinamoApi.MIN_EFT_PIN_LEN and DinamoApi.MAX_EFT_PIN_LEN.
pinblock	Buffer containing the input Pin Block to be verified. The expected PIN Block format is ISO PIN Block Format 0 (equivalent to ANSI PIN Block Format 0 and VISA PIN Block Format 1). The buffer must have the size of a PIN Block, DinamoApi.DES_BLOCK (8 bytes).

Return

true if the PIN has been successfully validated and false if it is invalid.

Exceptions

DinamoException

Throws exception in case of error.

Examples

eft_verify_pinblock.cs.

ExportTR31()

byte[] ExportTR31 ( string  kbpk, string  key, EftExportUsage  use, EftExportMode  mode, EftExportExpType  exp  )

inline

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.
mode	Key usage mode identifier, as described in ASC X9 TR 31-2018 Section A.5.3 table 8.
exp	Key exportability identifier, as described in ASC X9 TR 31-2018 Section A.5.5 table 10.

Return

Key block

Exceptions

DinamoException

Throws exception in case of error.

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

Examples

export_import_tr31.cs.

ImportTR31()

void ImportTR31 ( string  kbpk, string  key, bool  isExportable, bool  isTemporary, byte[]  keyBlock  )

inline

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.
isExportable	Defines whether the imported key is exportable.
isTemporary	Defines whether the imported key is temporary.
keyBlock	Key block in TR-31 format.

Exceptions

DinamoException

Throws exception in case of error.

Notes

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

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

Examples

export_import_tr31.cs.