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 cardholder's identity can typically be verified in two ways:

handwritten signature, compared with a signature card maintained by the card issuer;
via a PIN (Personal Identification Number) provided by the user; PIN verification can be performed online, with validation by the card issuer, or offline, using a chip card.

The adopted standards comply with the Visa Payment Technology Standards Manual (Payment Technology Standards Manual, October 2007).

Generally, the card-based funds transfer process follows the flow shown in the figure below. Several actors are involved in this process. The cardholder (card holder) presents the card to the retailer (Retailer/Merchant), and the cardholder's authenticity can be verified via a PIN, which the cardholder enters at the retailer's station (e.g., a POS terminal, Point of Sale). From there, the PIN is encrypted (a PIN Block is generated), and the transaction data is sent to an electronic payment service provider, contracted by the retailer (Acquirer), who in turn sends the data to the corresponding card scheme, according to the brand of the card used by the cardholder. The data is then sent to the card issuer, who holds the cardholder's identification, credit, and other relevant data, and maintains a contract with the cardholder for the use of the service. After analyzing the transaction data, including registration, credit, and authentication, among others, the issuer can authorize or decline the transaction, and this response message travels back through the flow in reverse.

---
title: Processo genérico de transferência eletrônica de fundos
---

sequenceDiagram
    autonumber
    actor Portador
    participant Loja
    participant Rede
    participant Bandeira
    participant Banco

    Portador ->> Loja: Cartão/PIN/CVV
    activate Loja
    Loja ->> Rede: Dados<br>Transação
    deactivate Loja
    activate Rede
    Rede ->> Bandeira: Dados<br>Transação
    deactivate Rede
    activate Bandeira
    Bandeira ->> Banco: Dados<br>Transação
    deactivate Bandeira
    activate Banco
    Banco ->> Bandeira: $
    deactivate Banco
    activate Bandeira
    Bandeira ->> Rede: $
    deactivate Bandeira
    activate Rede
    Rede ->> Loja: $
    deactivate Rede
    activate Loja
    Loja ->> Portador: Mercadorias/<br>Serviços
    deactivate Loja
    Banco -->> Portador: Débito
    Portador -->> Banco: $

From the perspective of the cryptographic keys used in the process, the process is shown in the figure below. Each actor maintains their own keys, and whenever an encrypted message needs to go from one actor to another, the encryption must be translated; that is, the corresponding key of the actor who will decrypt the message must be used.

---
title: Chaves criptográficas na transferência de fundos
---
%%{init: {'sequence': { 'mirrorActors': false}}}%%

sequenceDiagram
    actor Portador
    participant Loja
    participant Rede
    participant Bandeira
    participant Banco

    destroy Portador
    Portador ->> Loja: Cartão/PIN/CVV
    destroy Loja
    Loja ->> Rede: PIN Block
    Note over Rede: HSM:<br>PIN Translation
    Note over Rede: ZCMK<br>AWK<br>...
    destroy Rede
    Rede ->> Bandeira: PIN Block
    Note over Bandeira: HSM:<br>PIN Translation
    Note over Bandeira: ZCMK<br>AWK<br>IWK<br>...
    destroy Bandeira
    Bandeira ->> Banco: PIN Block
    activate Banco
    Note over Banco: HSM:<br>PIN Block Verification<br>CVV Verification
    Note over Banco: ZCMK<br>IWK<br>CVK<br>PVK<br>...
    deactivate Banco

Variations or simplifications of the above scheme can be used, for example, when the same entity plays more than one role, or when there is direct communication between the provider (acquirer) and the issuer (issuer), as may occur in certain debit account transactions.

Info

Each cryptographic key must be dedicated to a single application, as specified by the Visa manual.
The specified parameter sizes refer to the data; the application must ensure that the passed buffer has sufficient space for the data and the terminator character.
The EFT module works with PIN sizes from 4(MIN_EFT_PIN_LEN) to 12(MAX_EFT_PIN_LEN) digits.

Regarding 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

Elo

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

JCB

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

Miscellaneous

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)

CVV Mechanisms

There are three ways of generating and verifying CVV(Card Verification Value) in HSM: 1. Card Verification Value (CVV), for transactions with magnetic stripe cards; 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 transactions with chip cards; The calculation mechanism is the same in all three forms, and the difference lies in the way the data is entered by the application.

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 scheme for CVV, iCVV, and CVV2 generation and verification.

---
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((CVV2))

    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 key; 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 modes for PIN generation by derivation are defined: 1. from the PAN (Personal Account Number), the input PIN (inPIN), and the PGK; 2. from an input PIN and the PGK, using an offset to allow the user to change the PIN; 3. from the PAN, the PGK, and an input PIN, using an offset to allow 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<br>(InPin -PIN)"/]
    OpOff[\Operação de offset no PIN/]
    Pin((PIN))

    InPin{{"InPin<br>(PIN gerado pelo usuário)"}}
    Of{{"dado de offset<br>(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 Block Translate operations (PIN Block Translate) involve two keys: a source key and a destination key. An intermediate phase is included to reconcile the input format with the output format, where feasible. Certain block formats are not interoperable, either due to insufficient data for conversion or restrictions imposed by the standard.

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

PIN Block verification involves two key operations: first, the PIN Block is deciphered using the PTK (PIN Transport Key); then, the PIN is extracted from the deciphered PIN block, and subsequently, PIN verification is performed using the PGK (PIN Generation Key), which is the same key used for the original PIN generation. This verification can be conducted with or without 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

DUKPT Mechanisms

DUKPT (Derived Unique Key Per Transaction) is a method for employing unique keys per transaction, derived from a fixed key, with this process being defined in ANSI X9.24 Part 1.

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

---
title: Geração chaves DUKPT
---

sequenceDiagram
    participant hsm as HSM
    participant pos as PoS/ATM<br>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 for using DUKPT are, at each end of the communication:

At the POS:

Previously initialized with an IPEK derived from a BDK.
Generates (or retrieves from a future key table) the future key using the DID and CTR.
Encrypts the required block (e.g., PIN Block).
Sends KSN + encrypted Block. KSN is composed of TRSM (or DID), KSI, and CTR.
Increments the internal CTR.

At HSM:

Receives KSN + Encrypted Block.
Selects the appropriate BDK based on the received KSN. KSN consists of TRMS (or DID), KSI, and CTR.
Generates the IPEK based on the selected BDK and KSN.
Uses the IPEK, DID, and CTR contained in the KSN to generate the session key.
Decrypts the Block and performs the necessary processing.
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: Comunicação DUKPT entre o POS/ATM e o HSM
---

sequenceDiagram
    participant pos as PoS/ATM<br>Device
    participant hsm as HSM

    Note over pos: IPEK
    activate pos
    pos ->> pos: KSI,CTR
    pos ->> pos: Chave de sessão
    pos ->> pos: Texto claro > bloco cifrado
    deactivate pos
    pos ->> hsm: bloco cifrado<br>TRSM (Device Id)<br>KSI<br>CTR
    activate hsm
    Note over hsm: BDK
    hsm ->> hsm: IPEK (Device Id)
    hsm ->> hsm: KSI,CTR
    hsm ->> hsm: Chave de sessão
    hsm ->> hsm: bloco cifrado > texto claro

    deactivate hsm

TR-31 Key-Wrapping

It is a wrapping/unwrapping process with confidentiality and integrity protection for keys and associated data, as 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) comprises the data utilized for deriving the KBEK and KBAK keys. It includes elements such as the counter, key usage indicator, algorithm indicator, and size. Its specific content varies based on the derivation method used, the key being derived, and other relevant parameters.

The derivation of KBEK and KBAK keys utilizes CMAC, taking the Key Derivation Input Data (which is 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("KDID")
    kbakin("KDID")
    cmac1[\CMAC/]
    kbpk(KBPK)
    cmac2[\CMAC/]
    kbek("KBEK")
    kbak("KBAK")

    kbpk --> cmac2
    kbpk --> cmac1
    kbekin --> cmac1
    kbakin --> cmac2
    cmac1 --> kbek
    cmac2 --> kbak

The Key block contains the exported key data. This block is divided into three parts:

The KBH (Key Block Header) contains information about the key and the key block.
This refers to the confidential data that will be sent or stored. It is encrypted using the KBEK key. The input data for this encryption consists of the key size, the key itself, and the padding.
The MAC that binds the KBH and the encrypted key block. It is generated using the KBAK key. The input data for the MAC operation includes: the KBH, and the input data used for encryption.

%%{init: { 'theme': 'dark' } }%%
timeline
    title Processo de Geração do Key Block

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

Trade Name

See the Modules topic for the current commercial name of the module; it will be used in presentations, marketing and promotional material, commercial proposals, and contracts.

License

See the Licenses and Modules topics for information on whether a specific license is required to use the module's APIs and what the name of this license is.

API EFT

Specific API documentation for the EFT module, with functions, classes and examples.

C/C++

API C/C++
Java

Java API
.NET

NET API