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

Electronic funds transfer operations. More...

Settings and Macros
#define	DN_CALC_ARPC_EMV_4_2_M1_ICC (1)
#define	DN_CALC_ARPC_EMV_4_2_M1_SK (2)
#define	DN_CALC_ARPC_EMV_4_2_M2 (3)
#define	DN_EFT_AES_KCV_TYPE_CMAC (1)
#define	DN_EFT_GET_KCV_TYPE_X9_24 (1)
#define	DN_EFT_GET_KCV_TYPE_CMAC (2)
#define	DN_EXP_ZPK_FLAG_FULL_CKS (1)
#define	DN_EFT_GET_KCV_MAX_LEN (3)
#define	DN_EFT_GEN_OFFLINE_KCV_TYPE_X9_24 (1)
#define	DN_EFT_GEN_OFFLINE_KCV_TYPE_CMAC (2)
#define	DN_EFT_KCV_TYPE_X9_24_LEN (3)
#define	DN_EFT_KCV_TYPE_CMAC_LEN (3)

Functions
int AAP_API	DPINBlockTranslate(HSESSIONCTX hSession, char *szSrcPEK, char *szDstPEK, BYTE bTransBlockType, char *szPAN, BYTE *pbInPinBlock, BYTE *pbOutPinBlock, DWORD dwParam)
int AAP_API	DGenerateCVV(HSESSIONCTX hSession, char *szKeyId, char *szPAN, char *szExpirationDate, char *szServiceCode, char *szCVV, DWORD dwParam)
int AAP_API	DVerifyCVV(HSESSIONCTX hSession, char *szKeyId, char *szPAN, char *szExpirationDate, char *szServiceCode, char *szCVV, DWORD dwParam)
int AAP_API	DGeneratePIN(HSESSIONCTX hSession, char *szPGK, char *szPAN, DWORD dwOperation, int nPinLen, char *szInPin, char *szOffset, char *szOutPin, DWORD dwParam)
int AAP_API	DVerifyPINBlock(HSESSIONCTX hSession, char *szPTK, char *szPGK, char *szPAN, char *szOffset, BYTE *pbInPinBlock, DWORD dwParam)
int AAP_API	DEFTCheckKeyParts (int nKeyAlgId, EFT_VISA_KEY_PARTS *pstKeyParts, DWORD dwParam)
int AAP_API	DGenerateDUKPT(HSESSIONCTX hSession, BYTE *pbKSI, BYTE *pbDID_CTR, char *szDUKPT, DWORD dwParam)
void AAP_API	DGenerateBDKName(BYTE *pbKSI, char *szBDKName, DWORD dwParam)
void AAP_API	DGenerateDUKPTName(BYTE *pbKSI, BYTE *pbDID_CTR, char *szDUKPTName, DWORD dwParam)
int AAP_API	DGeneratePVV(HSESSIONCTX hSession, char *szPGK, BYTE bPVKI, char *szPAN, char *szPIN, char *szPVV, DWORD dwParam)
int AAP_API	DGenerateDAC(HSESSIONCTX hSession, char *szIMKDAC, char *szPAN, BYTE *pbSEQ, BYTE *pbDAC, DWORD dwParam)
int AAP_API	DVerifyDAC(HSESSIONCTX hSession, char *szIMKDAC, char *szPAN, BYTE *pbSEQ, BYTE *pbDAC, DWORD dwParam)
int AAP_API	DSignSDA(HSESSIONCTX hSession, char *szIK, BYTE *pbDAC, DWORD dwSDA_DATALen, BYTE *pbSDA_DATA, DWORD *pdwSigLen, BYTE *pbSig, DWORD dwParam)
int AAP_API	DGenerateDDA_ICCCert(HSESSIONCTX hSession, BYTE bOP, char *szIK, char *szPAN, DWORD dwDDA_DATALen, BYTE *pbDDA_DATA, DWORD *pdwSigLen, BYTE *pbSig, DWORD dwParam)
int AAP_API	DGenerateICCMK(HSESSIONCTX hSession, BYTE bOP, char *szIK, char *szKeK, char *szPAN, BYTE *pbSEQ, DWORD *pdwEnvelopeLen, BYTE *pbEnvelope, DWORD dwParam)
int AAP_API	DGenerateEMV_HMAC(HSESSIONCTX hSession, BYTE bOP, char *szIK, char *szPAN, BYTE *pbSEQ, BYTE *pbNONCE, DWORD dwDataLen, BYTE *pbData, BYTE *pbMAC, DWORD dwParam)
int AAP_API	DGenerateEMV_MAC(HSESSIONCTX hSession, BYTE bOP, char *szIK, char *szPAN, BYTE *pbSEQ, BYTE *pbNONCE, DWORD dwDataLen, BYTE *pbData, BYTE *pbMAC, DWORD dwParam)
int AAP_API	DCheckIDN(HSESSIONCTX hSession, char *szIK, char *szPAN, BYTE *pbSEQ, BYTE *pbATC, BYTE *pbUN, BYTE *pbIDN, DWORD dwParam)
int AAP_API	DEncryptEMV(HSESSIONCTX hSession, BYTE bEncOP, char *szEncIK, BYTE *pbEncNONCE, BYTE bMacOP, char *szMacIK, BYTE *pbMacNONCE, char *szPAN, BYTE *pbSEQ, DWORD dwDataLen, BYTE *pbData, DWORD *pdwEncDataLen, BYTE *pbEncData, BYTE *pbMAC, DWORD dwParam)
int AAP_API	DGenerateEMV_CSR(HSESSIONCTX hSession, BYTE bOP, char *szIK, BYTE *pbTrackNum, BYTE *pbServiceID, BYTE *pbIssuerID, BYTE *pbExpDate, DWORD *pdwCSRLen, BYTE *pbCSR, DWORD dwParam)
int AAP_API	DGenerateEMV_CSREx(HSESSIONCTX hSession, BYTE bOP, char *szIK, BYTE *pbTrackNum, BYTE *pbServiceID, BYTE *pbIssuerID, BYTE *pbExpDate, DBLOB *pdbCSR, BYTE *pbHash, DWORD dwParam)
int AAP_API	DGenerateEMV_PinBlock(HSESSIONCTX hSession, BYTE bOP, BYTE *pbNONCE, char *szTransportKey, char *szISSUER_MK, char *szISSUER_SMC_MK, char *szPAN, BYTE *pbSEQ, BYTE *pbOLD_PB, BYTE *pbNEW_PB, BYTE *pbOutBlock, DWORD *pdwOutBlockLen, DWORD dwParam)
int AAP_API	DDeriveEMV_Key(HSESSIONCTX hSession, char *szSrcKey, WORD wBufferLen, BYTE *pbBuffer, BYTE bOP, DWORD dwAttrib, char *szDstKey, HKEYCTX *phKey, DWORD dwParam)
int AAP_API	DCalculateARPC(HSESSIONCTX hSession, char *szIssuerMK, char *szPAN, BYTE *pbSEQ, BYTE *pbARQC, BYTE *pbARC, BYTE *pbARPC, DWORD dwParam)
int AAP_API	DCalculateARPC_Ex(HSESSIONCTX hSession, DWORD dwOp, void *pvInData, BYTE *pbARPC, DWORD dwParam)
int AAP_API	DMAC_ISO9797_1_Met2(DWORD dwType, BYTE *pbKey, DWORD dwAlg, const BYTE *pbMsg, DWORD dwMsgLen, BYTE *pbMAC)
int AAP_API	DEFTImportKey(HSESSIONCTX hSession, char *szKeyId, int nKeyAlgId, void *pstKeyParts, DWORD dwParam)
int AAP_API	DEFTExportAESKeyParts(HSESSIONCTX hSession, BYTE bKcvType, const char *szKeyId, void *pvKeyParts, DWORD dwReserved)
int AAP_API	DEFTExportKey(HSESSIONCTX hSession, BYTE bExportMode, char *szKEKId, char *szKeyId, BYTE *pbEncryptedBlock, DWORD *pdwEncryptedBlockLen, BYTE *pbKeyCheckValue, DWORD dwParam)
int AAP_API	DEFTKeKImport(HSESSIONCTX hSession, BYTE bOP, DWORD dwAlgId, char *szKeKName, char *szKeyName, DWORD dwAttr, BYTE *pbKCV1, BYTE *pbKCV2, BYTE *pbKCV3, BYTE *pbKCVFinal, BYTE *pbBlob, DWORD dwFlags)
int AAP_API	DEFTExportZPK(HSESSIONCTX hSession, char *szKeyId, int *pnKeyAlg, int *pnKeySize, EFT_VISA_KEY_PARTS *pstKeyParts, DWORD dwParam)
int AAP_API	DEFTGetKcv(HSESSIONCTX hSession, BYTE bType, const char *szKeyId, BYTE *pbKcv, DWORD *pdwKcvLen, DWORD dwReserved)
int AAP_API	DEFTGenKCVOffline(DWORD dwType, int nAlgId, const BYTE *pbKey, DWORD dwKeyLen, BYTE *pbKCV, DWORD *pdwKCVLen, DWORD reserved)
int AAP_API	DEFTExportTR31(HSESSIONCTX hSession, const char *szKBPK, const char *szKey, void *pvReserved, WORD wUsage, BYTE bMode, BYTE bExport, BYTE *pbOutBlock, DWORD *pdwOutBlockLen, DWORD dwParam)
int AAP_API	DEFTImportTR31(HSESSIONCTX hSession, const char *szKBPK, const char *szKey, DWORD dwKeyAttributes, BYTE *pbKeyBlock, DWORD dwKeyBlockLen, DWORD dwParam)

Definitions and macros

DN_CALC_ARPC_EMV_4_2_M1_ICC

#define DN_CALC_ARPC_EMV_4_2_M1_ICC (1)

#include <dinamo.h>

DN_CALC_ARPC_EMV_4_2_M1_SK

#define DN_CALC_ARPC_EMV_4_2_M1_SK (2)

#include <dinamo.h>

DN_CALC_ARPC_EMV_4_2_M2

#define DN_CALC_ARPC_EMV_4_2_M2 (3)

#include <dinamo.h>

DN_EFT_AES_KCV_TYPE_CMAC

#define DN_EFT_AES_KCV_TYPE_CMAC (1)

#include <dinamo.h>

CMAC-type KCV. In accordance with the PCI "PIN Security Requirements".

DN_EFT_GET_KCV_TYPE_X9_24

#define DN_EFT_GET_KCV_TYPE_X9_24 (1)

#include <dinamo.h>

Exports an AES key by parts in ANSI X9.24 format.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bKcvType	Type of KCV to be used for export. Value Meaning DN_EFT_GET_KCV_TYPE_X9_24 Generates the key's KCV (Key Check Value) as defined in ANSI X.9.24 with a size of 3 bytes. DN_EFT_GET_KCV_TYPE_CMAC Generates the KCV (Key Check Value) of the key as defined in the PCI PIN Security Requirements with a size of 3 bytes.
[in]	szKeyId	Name of the key to be exported.
[out]	pvKeyParts	Pointer to an EFT_AES_KEY_PARTS structure that will contain the data for reconstructing the key.
[in]	dwReserved	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values. Generates the key's KCV (Key Check Value) as defined in ANSI X.9.24 with a size of 3 bytes.

DN_EFT_GET_KCV_TYPE_CMAC

#define DN_EFT_GET_KCV_TYPE_CMAC (2)

#include <dinamo.h>

Generates the KCV (Key Check Value) of the key as defined in the PCI PIN Security Requirements with a size of 3 bytes.

DN_EXP_ZPK_FLAG_FULL_CKS

#define DN_EXP_ZPK_FLAG_FULL_CKS (1)

#include <dinamo.h>

DN_EFT_GET_KCV_MAX_LEN

#define DN_EFT_GET_KCV_MAX_LEN (3)

#include <dinamo.h>

Maximum size of the generated KCV (Key Check Value).

DN_EFT_GEN_OFFLINE_KCV_TYPE_X9_24

#define DN_EFT_GEN_OFFLINE_KCV_TYPE_X9_24 (1)

#include <dinamo.h>

Generates the key's KCV (Key Check Value) as defined in ANSI X.9.24 with a size of 3 bytes.

DN_EFT_GEN_OFFLINE_KCV_TYPE_CMAC

#define DN_EFT_GEN_OFFLINE_KCV_TYPE_CMAC (2)

#include <dinamo.h>

Generates the KCV (Key Check Value) of the key as defined in the PCI PIN Security Requirements with a size of 3 bytes.

DN_EFT_KCV_TYPE_X9_24_LEN

#define DN_EFT_KCV_TYPE_X9_24_LEN (3)

#include <dinamo.h>

Size of the KCV (Key Check Value) generated.

DN_EFT_KCV_TYPE_CMAC_LEN

#define DN_EFT_KCV_TYPE_CMAC_LEN (3)

#include <dinamo.h>

Size of the KCV (Key Check Value) generated.

Functions

DPINBlockTranslate()

int AAP_API DPINBlockTranslate	(	HSESSIONCTX	hSession,
		char *	szSrcPEK,
		char *	szDstPEK,
		BYTE	bTransBlockType,
		char *	szPAN,
		BYTE *	pbInPinBlock,
		BYTE *	pbOutPinBlock,
		DWORD	dwParam )

#include <dinamo.h>

It translates a PIN Block, decrypting the block 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

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szSrcPEK	Identifier of the decryption key within the HSM.
[in]	szDstPEK	Identifier of the encryption key within the HSM.
[in]	bTransBlockType	Output block format identifier. According to the table below. Value Meaning 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. 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. TP_TRANSLATE_TYPE_ISO_1 Uses ISO PIN Block Format 1. PAN Bound: no. TP_TRANSLATE_TYPE_ISO_3 Uses ISO PIN Block Format 3. PAN Bound: yes. TP_TRANSLATE_TYPE_IBM_3624 IBM 3624 block type used. Not implemented.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbInPinBlock	Buffer containing the input PIN Block. The buffer must have the size of a PIN Block, DES_BLOCK (8 bytes) .
[out]	pbOutPinBlock	Buffer that will contain the outgoing PIN Block. The buffer must have the size of a PIN Block, DES_BLOCK (8 bytes).
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

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.

Examples

pin_block_translate.c.

DGenerateCVV()

int AAP_API DGenerateCVV	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		char *	szPAN,
		char *	szExpirationDate,
		char *	szServiceCode,
		char *	szCVV,
		DWORD	dwParam )

#include <dinamo.h>

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

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	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.
[in]	szPAN	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.
[in]	szExpirationDate	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.
[in]	szServiceCode	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.
[out]	szCVV	Output buffer containing the generated CVV string. 3-digit length. The generated value can also be a CVV2 or iCVV, depending on the Service Code values entered.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

The API is also compatible with the American Express standard.

Examples

eft_validate_cvv.c.

DVerifyCVV()

int AAP_API DVerifyCVV	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		char *	szPAN,
		char *	szExpirationDate,
		char *	szServiceCode,
		char *	szCVV,
		DWORD	dwParam )

#include <dinamo.h>

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 DGenerateCVV() API.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	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.
[in]	szPAN	PAN (Primary Account Number). Length from 12 to 19 characters. See more details about this field in the DGenerateCVV() API.
[in]	szExpirationDate	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 DGenerateCVV() API.
[in]	szServiceCode	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
[in]	szCVV	CVV to be validated. 3-digit length. The value entered can also be a CVV2 or iCVV, depending on the Service Code values entered.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples

eft_validate_cvv.c.

DGeneratePIN()

int AAP_API DGeneratePIN	(	HSESSIONCTX	hSession,
		char *	szPGK,
		char *	szPAN,
		DWORD	dwOperation,
		int	nPinLen,
		char *	szInPin,
		char *	szOffset,
		char *	szOutPin,
		DWORD	dwParam )

#include <dinamo.h>

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

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szPGK	Key identifier within the HSM.
[in]	szPAN	PAN (Primary Account Number).
[in]	dwOperation	Type of PIN generation. According to the table below. Value Meaning GP_DEFAULT_PIN Generates the default PIN based on PAN and PGK. The szInPin parameter must be NULL. GP_USER_DEF_PIN Generates an offset for the PIN set by the caller. The szInPin parameter must contain a string containing the PIN. GP_RANDOM_PIN Randomly generates a PIN and offset based on PAN and PGK. szInPin must be NULL.
[in]	nPinLen	PIN size to be used/generated in the operation. It must be between MIN_EFT_PIN_LEN and MAX_EFT_PIN_LEN.
[in]	szInPin	Input PIN. The buffer must be between MIN_EFT_PIN_LEN + 1 and MAX_EFT_PIN_LEN + 1.
[out]	szOffset	Buffer containing the offset string. The buffer must have a size between MIN_EFT_PIN_LEN + 1 and MAX_EFT_PIN_LEN + 1.
[out]	szOutPin	Buffer containing the outgoing PIN string. The buffer must be between MIN_EFT_PIN_LEN + 1 and MAX_EFT_PIN_LEN + 1.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DVerifyPINBlock()

int AAP_API DVerifyPINBlock	(	HSESSIONCTX	hSession,
		char *	szPTK,
		char *	szPGK,
		char *	szPAN,
		char *	szOffset,
		BYTE *	pbInPinBlock,
		DWORD	dwParam )

#include <dinamo.h>

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 DGeneratePIN() function.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szPTK	Identifier of the "PIN Block" decryption key within the HSM. It is the PIN Transport Key.
[in]	szPGK	Identifier of the key to be used for PIN verification within the HSM. It is the PIN Generation Key.
[in]	szPAN	PAN (Primary Account Number).
[in]	szOffset	PIN offset. The buffer must be between MIN_EFT_PIN_LEN + 1 and MAX_EFT_PIN_LEN + 1.
[in]	pbInPinBlock	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 be the size of a PIN Block, DES_BLOCK (8 bytes).
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples

verify_pin_block.c.

DEFTCheckKeyParts()

int AAP_API DEFTCheckKeyParts	(	int	nKeyAlgId,
		EFT_VISA_KEY_PARTS *	pstKeyParts,
		DWORD	dwParam )

#include <dinamo.h>

Checks the validity of the parts of a VISA key with their respective check values, in the format described in the VISA Payment Technology Standards Manual, October 2007.

Parameters

[in]	nKeyAlgId	Algorithm of the key to be verified.
[in]	pstKeyParts	Pointer to an EFT_VISA_KEY_PARTS structure containing the parts of the key to be checked and their part check values.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

Only the parts are checked with their respective check values, the complete and assembled switch is not checked in this test.

DGenerateDUKPT()

int AAP_API DGenerateDUKPT	(	HSESSIONCTX	hSession,
		BYTE *	pbKSI,
		BYTE *	pbDID_CTR,
		char *	szDUKPT,
		DWORD	dwParam )

#include <dinamo.h>

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

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	pbKSI	Buffer of size MIN_KSI_LEN containing the KSI (first 05 bytes of the KSN).
[in]	pbDID_CTR	Buffer of size MIN_CTR_LEN containing the DID and CTR (last 05 bytes of the KSN).
[out]	szDUKPT	Buffer of size MAX_OBJ_ID that will contain the DKUPT key name generated from the parameters entered.
[in]	dwParam	Operating flags according to the table below. Value Meaning NEW_DUKPT_MODE_DUK Generates a standard DUK (Derived Unique Key) according to the ISO X9.24-1-2004 manual. NEW_DUKPT_MODE_PEK Generates a PEK key (PIN Encryption Key) in accordance with 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 0000 0000 0000 00FF mask to the parts of the key. NEW_DUKPT_MODE_DE Diversifies the generated key 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

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples

gen_dukpt.c.

DGenerateBDKName()

void AAP_API DGenerateBDKName	(	BYTE *	pbKSI,
		char *	szBDKName,
		DWORD	dwParam )

#include <dinamo.h>

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

Parameters

[in]	pbKSI	Buffer of size MIN_KSI_LEN containing the KSI.
[out]	szBDKName	Buffer of size MAX_OBJ_ID that will contain the BDK key name generated from the KSI entered in pbKSI.
[in]	dwParam	Reserved for future use (must be 0).

Return

It does not return a value.

Examples

gen_dukpt.c.

DGenerateDUKPTName()

void AAP_API DGenerateDUKPTName	(	BYTE *	pbKSI,
		BYTE *	pbDID_CTR,
		char *	szDUKPTName,
		DWORD	dwParam )

#include <dinamo.h>

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

Parameters

[in]	pbKSI	Buffer of size MIN_KSI_LEN containing the KSI (Key Serial Identification).
[in]	pbDID_CTR	Buffer of size MIN_CTR_LEN containing the CTR (Device ID and Transaction Counter).
[out]	szDUKPTName	Buffer of size MAX_OBJ_ID that will contain the DKUPT key name generated from the KSI and CTR entered in pbKSI and pbCTR.
[in]	dwParam	Reserved for future use (must be 0).

Return

It does not return a value.

DGeneratePVV()

int AAP_API DGeneratePVV	(	HSESSIONCTX	hSession,
		char *	szPGK,
		BYTE	bPVKI,
		char *	szPAN,
		char *	szPIN,
		char *	szPVV,
		DWORD	dwParam )

#include <dinamo.h>

It generates a PVV (Pin Verification Value) from a PAN (Primary Account Number), a PIN (Personal Identification Number) and a PGK.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szPGK	Key identifier within the HSM.
[in]	bPVKI	Key identifier ranging from EFT_MIN_PVKI to EFT_MAX_PVKI.
[in]	szPAN	PAN (Primary Account Number).
[in]	szPIN	PIN (Personal Identification Number).
[out]	szPVV	Buffer containing the generated PVV string. It must have a minimum size of EFT_PVV_LEN + 1 (zero terminator).
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DGenerateDAC()

int AAP_API DGenerateDAC	(	HSESSIONCTX	hSession,
		char *	szIMKDAC,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbDAC,
		DWORD	dwParam )

#include <dinamo.h>

It generates a DAC (Data Authentication Code) receiving as parameters the PAN (Primary Account Number), the SEQ (PAN Sequence Number) and the IMKDAC (Issuer Master Key) used in the DAC.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szIMKDAC	Key identifier within the HSM.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer of size EFT_EMV_SDA_SEQ_LEN containing the SEQ (PAN Sequence Number).
[out]	pbDAC	Buffer of size EFT_EMV_SDA_DAC_LEN containing the DAC (Data Authentication Code) to be verified.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DVerifyDAC()

int AAP_API DVerifyDAC	(	HSESSIONCTX	hSession,
		char *	szIMKDAC,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbDAC,
		DWORD	dwParam )

#include <dinamo.h>

Checks a DAC (Data Authentication Code) receiving as parameters the PAN (Primary Account Number), the SEQ (PAN Sequence Number) and the IMKDAC key (Issuer Master Key) used in the DAC.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szIMKDAC	Key identifier within the HSM.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer of size EFT_EMV_SDA_SEQ_LEN containing the SEQ (PAN Sequence Number).
[in]	pbDAC	Buffer of size EFT_EMV_SDA_DAC_LEN containing the DAC (Data Authentication Code) to be verified.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DSignSDA()

int AAP_API DSignSDA	(	HSESSIONCTX	hSession,
		char *	szIK,
		BYTE *	pbDAC,
		DWORD	dwSDA_DATALen,
		BYTE *	pbSDA_DATA,
		DWORD *	pdwSigLen,
		BYTE *	pbSig,
		DWORD	dwParam )

#include <dinamo.h>

Signs a SAD (Static Application Data) to SDA (Static Data Authentication) cards, generating an SSDA (Signed Static Application Data).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szIK	Name of the private key within the HSM that will be used to sign the SAD.
[in]	pbDAC	Buffer of size EFT_EMV_SDA_DAC_LEN containing the DAC (Data Authentication Code) to be verified.
[in]	dwSDA_DATALen	Buffer size pointed to by pbSDA_DATA .
[in]	pbSDA_DATA	Buffer containing the SDA (Static Application Data) to be signed of a size specified in dwSDA_DATALen.
[in,out]	pdwSigLen	Pointer to a DWORD containing the size of the buffer pointed to by pbSig.
[out]	pbSig	Buffer size pointed to by pdwSigLen that will receive the SSDA (Signed Static Application Data). NULL can be passed to retrieve the required size from pbSig, which will be returned in pdwSigLen.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DGenerateDDA_ICCCert()

int AAP_API DGenerateDDA_ICCCert	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		char *	szIK,
		char *	szPAN,
		DWORD	dwDDA_DATALen,
		BYTE *	pbDDA_DATA,
		DWORD *	pdwSigLen,
		BYTE *	pbSig,
		DWORD	dwParam )

#include <dinamo.h>

Generates the ICC (Integrated Circuit Card) Certificate used in DDA (Dynamic Data Authentication) authentication.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bOP	Type of operation to be applied according to the table below. Value Meaning EFT_EMV_DDA_OP_RSA_SIGN1 RSA + SHA1
[in]	szIK	Name of the private key within the HSM that will be used to sign the Certificate.
[in]	szPAN	PAN (Primary Account Number).
[in]	dwDDA_DATALen	Buffer size pointed to by pbDDA_DATA.
[in]	pbDDA_DATA	Buffer containing the data of the certificate to be signed. Pass on the structure described in EMV Book 2 Tables 10 to 14, without including the Recovered Data Header and Trailer fields.
[in,out]	pdwSigLen	Pointer to a DWORD containing the buffer size pbSig.
[out]	pbSig	Buffer that will receive the signed certificate. NULL can be passed to retrieve the required size of pbSig, which will be returned in pdwSigLen.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DGenerateICCMK()

int AAP_API DGenerateICCMK	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		char *	szIK,
		char *	szKeK,
		char *	szPAN,
		BYTE *	pbSEQ,
		DWORD *	pdwEnvelopeLen,
		BYTE *	pbEnvelope,
		DWORD	dwParam )

#include <dinamo.h>

Generates ICC (Integrated Circuit Card) Master Keys.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bOP	Type of operation to be applied according to the table below. Value Meaning EFT_EMV_GEN_ICC_MK_OP_CBC_EXP Operation in CBC mode EFT_EMV_GEN_ICC_MK_OP_ECB_EXP Operation in ECB mode
[in]	szIK	Name of the key within the HSM that will be used to generate the Master Key.
[in]	szKeK	Name of the transport key used to encrypt the generated key.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer of size EFT_EMV_SDA_SEQ_LEN containing the SEQ (PAN Sequence Number).
[in,out]	pdwEnvelopeLen	Pointer to a DWORD containing the size of the buffer pointed to by pbEnvelope.
[out]	pbEnvelope	Buffer that will receive the envelope with the generated key. NULL can be passed to retrieve the required size of pbSig, which will be returned in pdwEnvelopeLen.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DGenerateEMV_HMAC()

int AAP_API DGenerateEMV_HMAC	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		char *	szIK,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbNONCE,
		DWORD	dwDataLen,
		BYTE *	pbData,
		BYTE *	pbMAC,
		DWORD	dwParam )

#include <dinamo.h>

Obsolete

The DGenerateEMV_MAC() API is functionally and syntactically equivalent to the DGenerateEMV_HMAC API. The reference to DGenerateEMV_HMAC remains active in the library (internally it is redirected to DGenerateEMV_MAC() ). Applications that call DGenerateEMV_HMAC do not need to be changed.

DGenerateEMV_MAC()

int AAP_API DGenerateEMV_MAC	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		char *	szIK,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbNONCE,
		DWORD	dwDataLen,
		BYTE *	pbData,
		BYTE *	pbMAC,
		DWORD	dwParam )

#include <dinamo.h>

It generates a standard EMV or MAC (Message Authentication Code) cryptogram, used in EMV commands.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bOP	Type of operation (padding, key derivation, etc.) to be applied in the construction of the cryptogram (MAC) according to the table below. Value Meaning EMV_OP_ISO_9797_1_M2_COMMON ISO 9797-1 Padding Method 2 COMMON. EMV_OP_ISO_9797_1_M2_MCHIP ISO 9797-1 Padding Method 2 MCHIP standard. EMV_OP_ISO_9797_1_M2_VISA ISO 9797-1 Padding Method 2 VISA standard. EMV_OP_ISO_9797_1_M2_VISA_CRYPTOGRAM ISO 9797-1 Padding Method 2 VISA_CRYPTOGRAM. EMV_OP_ISO_9797_1_M2_RAW ISO 9797-1 Padding Method 2 Algorithm 3.NULL must be passed in the szPAN, pbSEQ and pbNONCE parameters. EMV_OP_ISO_9797_1_M1_VISA_CRYPTOGRAM_PADD_V10 ISO 9797-1 Padding Method 1 VISA standard. EMV_OP_ISO_9797_1_M2_ELO ISO 9797-1 Padding Method 2 COMMON. EMV_OP_ISO_9797_1_M2_JCB ISO 9797-1 Padding Method 2. As described in JCB IC Card Specification, Version 2.0 - October, 2012. EMV_OP_ISO_9797_1_M1_JCB ISO 9797-1 Padding Method 1. As described in JCB IC Card Specification, Version 2.0 - October, 2012. EMV_OP_ISO_9797_1_M1_JCB_CRYPTOGRAM ISO 9797-1 Padding Method 1. As described in JCB IC Card Specification, Version 2.0 - October, 2012.
[in]	szIK	Name of the key within the HSM that will be used to generate the MAC.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer of size EFT_EMV_SDA_SEQ_LEN containing the SEQ (PAN Sequence Number). It must be in ASCII format.
[in]	pbNONCE	Buffer containing the diversifying material used to generate the MAC, must have size DES_BLOCK. Type of operation according to bOP parameter NONCE EMV_OP_ISO_9797_1_M2_COMMON ATC (2 bytes)||00|00|00|00|00|00||00 EMV_OP_ISO_9797_1_M2_MCHIP CVN10 and CVN11: ATC (2 bytes)||00||UC(Unpredictable Number) CVN14 and CVN15: ATC (2 bytes)||00||00||00||00|||00 EMV_OP_ISO_9797_1_M2_VISA 00||00||00||00|||ATC (2 bytes) EMV_OP_ISO_9797_1_M2_VISA_CRYPTOGRAM 00||00||00||00||00||00||00||00 or NULL EMV_OP_ISO_9797_1_M2_RAW NULL EMV_OP_ISO_9797_1_M1_VISA_CRYPTOGRAM_PADD_V10 00||00||00||00||00||00||00||00 or NULL EMV_OP_ISO_9797_1_M2_ELO ATC (2 bytes)||00|00|00|00|00|00||00 EMV_OP_ISO_9797_1_M2_JCB 00||00||00||00|||ATC (2 bytes) EMV_OP_ISO_9797_1_M1_JCB 00||00||00||00|||ATC (2 bytes) EMV_OP_ISO_9797_1_M1_JCB_CRYPTOGRAM 00||00||00||00|||ATC (2 bytes)

The CVN (Cryptogram Version Number) determines the version of the cryptogram used and depends on business definitions. The application must use the NONCE following the CVN version, where applicable.
For more information on which CVN to use, consult your card scheme provider.

Parameters

[in]	dwDataLen	Buffer size pointed to by pbData.
[in]	pbData	Buffer size specified by dwDataLen containing the data that will be used to generate the MAC. Note that the padding will be done by the HSM, according to the parameter bOPso the calling application should not pad the data in pbData.
[out]	pbMAC	DES_BLOCK-sized buffer containing the generated MAC.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DCheckIDN()

int AAP_API DCheckIDN	(	HSESSIONCTX	hSession,
		char *	szIK,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbATC,
		BYTE *	pbUN,
		BYTE *	pbIDN,
		DWORD	dwParam )

#include <dinamo.h>

Check the IDN (ICC Dynamic Number).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szIK	Name of the key within the HSM that will be used to verify the IDN.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer of size EFT_EMV_SDA_SEQ_LEN containing the SEQ (PAN Sequence Number).
[in]	pbATC	Buffer of size EFT_EMV_IDN_ATC_LEN containing the ATC (Application Transaction Counter).
[in]	pbUN	Buffer of size EFT_EMV_IDN_UN_LEN containing the UN (Unpredictable Number).
[in]	pbIDN	Buffer of size EFT_EMV_IDN_LEN containing the IDN (ICC Dynamic Number).
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DEncryptEMV()

int AAP_API DEncryptEMV	(	HSESSIONCTX	hSession,
		BYTE	bEncOP,
		char *	szEncIK,
		BYTE *	pbEncNONCE,
		BYTE	bMacOP,
		char *	szMacIK,
		BYTE *	pbMacNONCE,
		char *	szPAN,
		BYTE *	pbSEQ,
		DWORD	dwDataLen,
		BYTE *	pbData,
		DWORD *	pdwEncDataLen,
		BYTE *	pbEncData,
		BYTE *	pbMAC,
		DWORD	dwParam )

#include <dinamo.h>

Encrypts data in SMC (Secure Message with Confidentiality) and generates MACs (Message Authenticatino Code) in SMC/SMI (Secure Messaging for Confidentiality/Integrity).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bEncOP	Type of operation to be applied according to the table below. Value Meaning EMV_OP_ISO_9797_1_M2_COMMON ISO 9797-1 Method 2 COMMON standard. EMV_OP_ISO_9797_1_M2_MCHIP ISO 9797-1 Method 2 MCHIP standard. EMV_OP_ISO_9797_1_M2_VISA ISO 9797-1 Method 2 VISA standard. EMV_OP_ISO_9797_1_M2_ELO ISO 9797-1 Padding Method 2 COMMON. EMV_OP_ISO_9797_1_M2_JCB ISO 9797-1 Padding Method 2. As described in JCB IC Card Specification, Version 2.0 - October, 2012.
[in]	szEncIK	Name of the key within the HSM that will be used to encrypt the data.
[in]	pbEncNONCE	Buffer containing the diversifier material used to encrypt the data, must have DES_BLOCK size.
[in]	bMacOP	Type of operation to be applied according to the table below. Value Meaning EMV_OP_ISO_9797_1_M2_COMMON ISO 9797-1 Method 2 COMMON standard. EMV_OP_ISO_9797_1_M2_MCHIP ISO 9797-1 Method 2 MCHIP standard. EMV_OP_ISO_9797_1_M2_VISA ISO 9797-1 Method 2 VISA standard. EMV_OP_ISO_9797_1_M2_ELO ISO 9797-1 Padding Method 2 COMMON. EMV_OP_ISO_9797_1_M2_JCB ISO 9797-1 Padding Method 2. As described in JCB IC Card Specification, Version 2.0 - October, 2012. EMV_OP_ISO_9797_1_M1_JCB ISO 9797-1 Padding Method 1. As described in JCB IC Card Specification, Version 2.0 - October, 2012. EMV_OP_ISO_9797_1_M1_JCB_CRYPTOGRAM ISO 9797-1 Padding Method 1. As described in JCB IC Card Specification, Version 2.0 - October, 2012.
[in]	szMacIK	Name of the key within the HSM that will be used to generate the MAC.
[in]	pbMacNONCE	Buffer containing the diversifying material used to generate the MAC, must have DES_BLOCK size.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer of size EFT_EMV_SDA_SEQ_LEN containing the SEQ (PAN Sequence Number).
[in]	dwDataLen	Buffer size pointed to by pbData.
[in]	pbData	Buffer of size specified by dwDataLen containing the data that will be used in the encryption/generation of the MAC.
[in,out]	pdwEncDataLen	Pointer to a DWORD containing the size of the buffer pointed to by pbEncData.
[out]	pbEncData	Buffer that will contain the encrypted data. NULL can be passed to retrieve the required size of pdwEncDataLen, which will be returned in pdwEncDataLen.
[out]	pbMAC	Buffer size DES_BLOCK which will contain the generated MAC. Can be NULL if szMacIK e pbMacNONCE are NULL.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DGenerateEMV_CSR()

int AAP_API DGenerateEMV_CSR	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		char *	szIK,
		BYTE *	pbTrackNum,
		BYTE *	pbServiceID,
		BYTE *	pbIssuerID,
		BYTE *	pbExpDate,
		DWORD *	pdwCSRLen,
		BYTE *	pbCSR,
		DWORD	dwParam )

#include <dinamo.h>

Generates the issuer's CSR (Certificate Signing Request).

Obsolete

Use the DGenerateEMV_CSREx() API.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bOP	Type of operation to be applied according to the table below. Value Meaning EFT_EMV_OP_CSR_VISA VISA process standard. The pbCSR buffer will contain CSR + HASH. HASH of size EFT_EMV_CSR_VISA_HASH_SIZE. EFT_EMV_OP_CSR_MASTER MASTERCARD process standard. The pbCSR buffer will contain CSR + HASH. HASH of size EFT_EMV_CSR_MASTER_HASH_SIZE. EFT_EMV_OP_CSR_ELO ELO process standard. The pbCSR buffer will contain the CSR.
[in]	szIK	Name of the key within the HSM that will be used to generate the CSR (Issuer Key).
[in]	pbTrackNum	Buffer of size EFT_EMV_CSR_VISA_TRACK_NUM_LEN containing the Track Number.
[in]	pbServiceID	Buffer of size EFT_EMV_CSR_VISA_SERVICE_ID_LEN containing the Service ID.
[in]	pbIssuerID	Buffer of size EFT_EMV_CSR_VISA_ISSUER_ID_LEN containing the Issuer ID.
[in]	pbExpDate	Buffer of size EFT_EXP_DATE_LEN containing the expiry date in MMYY format. It must be in ASCII format.
[in,out]	pdwCSRLen	Pointer to a DWORD containing the size of the buffer pointed to by pbCSR.
[out]	pbCSR	Buffer that will contain the CSR. NULL can be passed to retrieve the required size of pbCSR, which will be returned in pdwCSRLen.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DGenerateEMV_CSREx()

int AAP_API DGenerateEMV_CSREx	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		char *	szIK,
		BYTE *	pbTrackNum,
		BYTE *	pbServiceID,
		BYTE *	pbIssuerID,
		BYTE *	pbExpDate,
		DBLOB *	pdbCSR,
		BYTE *	pbHash,
		DWORD	dwParam )

#include <dinamo.h>

Generates the issuer's CSR (Certificate Signing Request);

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bOP	Type of operation to be applied according to the table below. Value Meaning EFT_EMV_OP_CSR_VISA VISA process standard. The buffer pdbCSR will contain the CSR and pbHash the HASH. pbHash must be previously allocated with size EFT_EMV_CSR_VISA_HASH_SIZE. EFT_EMV_OP_CSR_MASTER MASTERCARD process standard. The buffer pdbCSR will contain the CSR and pbHash the HASH. pbHash must be allocated in advance with EFT_EMV_CSR_MASTER_HASH_SIZE. EFT_EMV_OP_CSR_ELO ELO process standard. The buffer pdbCSR will contain the CSR. pbHash must be NULL and no HASH will be returned. EFT_EMV_OP_CSR_JCB JCB process standard. The buffer pdbCSR will contain the CSR. pbHash must be NULL and no HASH will be returned. It follows the standard JCB CA Interface Guide, 04/01/2014 in the file layout described in section 5.1.2.2.
[in]	szIK	Name of the key within the HSM that will be used to generate the CSR (Issuer Key).
[in]	pbTrackNum	Buffer of size EFT_EMV_CSR_VISA_TRACK_NUM_LEN containing the Track Number. If EFT_EMV_OP_CSR_JCB is defined in bOP this field must contain the Serial Number of size EFT_EMV_CSR_VISA_TRACK_NUM_LEN.
[in]	pbServiceID	Buffer of size EFT_EMV_CSR_VISA_SERVICE_ID_LEN containing the Service ID.
[in]	pbIssuerID	Buffer of size EFT_EMV_CSR_VISA_ISSUER_ID_LEN containing the Issuer ID.
[in]	pbExpDate	Buffer of size EFT_EXP_DATE_LEN containing the expiry date in MMYY format. It must be in ASCII format.
[out]	pdbCSR	Pointer to one DBLOB which will contain the CSR and its size. The member pvData should be released with DFree() after use.
[out]	pbHash	Buffer that will contain the HASH. See the table in bOP for the expected values for this parameter.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DGenerateEMV_PinBlock()

int AAP_API DGenerateEMV_PinBlock	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		BYTE *	pbNONCE,
		char *	szTransportKey,
		char *	szISSUER_MK,
		char *	szISSUER_SMC_MK,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbOLD_PB,
		BYTE *	pbNEW_PB,
		BYTE *	pbOutBlock,
		DWORD *	pdwOutBlockLen,
		DWORD	dwParam )

#include <dinamo.h>

Generates a data segment for a PIN (Personal Identification Number) change command from PIN Blocks. This command is typically an APDU (Application Protocol Data Unit) for an ISO-7816 card.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bOP	Identifier of the type of derivation of the operation keys for generating the output block. According to the table below. Value Meaning PBC_EMV_PIN_BLOCK_OP_MCHIP Operational keys and the output block will be generated in accordance with the "M/Chip 4 Version 1.1 Issuer Guide, chapter 6", "M/Chip Lite 2.1 Card Application Specifications for Debit and Credit, section: 2.7 Secure Messaging" and "M/Chip 4 Version 1.1, Section 7.2.8". PBC_EMV_PIN_BLOCK_OP_VISA Operational keys and the output block will be generated in accordance with "EMV book 2 v4.2, A1.4.1 option A and A1.4.2 option B", "VISA ICC specification 1.4.0 appendix B.4/EMV Book 2 v4.2 A1.3" - for the card and session keys respectively. "VISA ICC spec 1.4.0, B.3.3 Data Encipherment Calculation, C.11.1 PIN Data Generated Using the Current PIN and C.11.2 PIN Data Generated Without Using the Current PIN", for the block. PBC_EMV_PIN_BLOCK_OP_VISA_CRYPTOGRAM Operational keys and the output block will be generated according to "EMV book 2 v4.2, A1.4.1 option A and A1.4.2 option B" - for the card and session keys (the session key is the same as the ICC key). "VISA ICC spec 1.4.0, B.3.3 Data Encipherment Calculation, C.11.1 PIN Data Generated Using the Current PIN and C.11.2 PIN Data Generated Without Using the Current PIN", for the block. PBC_EMV_PIN_BLOCK_OP_ELO Operational keys and output blocks will be generated in accordance with the ELO Chip Card Manual, CCD Cryptographic Algorithms, A5, section TDES Keys Usage Algorithm (Script Processing Command Data Encryption in Change PIN script cmd), Algorithm no. 4. PBC_EMV_PIN_BLOCK_OP_JCB Operational keys and output blocks will be generated in accordance with the JCB IC Card Specification Manual, Version 2.0 - October, 2012.
[in]	pbNONCE	Buffer containing the diversifying material, must have size DES_BLOCK. Identifier used in the bOP parameter NONCE PBC_EMV_PIN_BLOCK_OP_MCHIP Encode as specified in the MCHIP manual: ATC (2 bytes) ||00|00|00|00|00|00|00. PBC_EMV_PIN_BLOCK_OP_VISA 00||00||00||00|||ATC (2 bytes). PBC_EMV_PIN_BLOCK_OP_VISA_CRYPTOGRAM 00||00||00||00||00||00||00||00. PBC_EMV_PIN_BLOCK_OP_ELO ATC (2 bytes)||00|00|00|00|00|00||00 PBC_EMV_PIN_BLOCK_OP_JCB 00||00||00||00||00|||ATC (2 bytes). JCB IC Card Specification, Version 2.0 - October, 2012.
[in]	szTransportKey	Identifier of the transport key within the HSM. This key must be of the DES or 3DES type.
[in]	szISSUER_MK	Identifier of the "Issuer MK" key within the HSSM. This key must be of type 3DES 112 bits. This key can be the same as the "Issuer SMC MK" key in certain cases.
[in]	szISSUER_SMC_MK	Identifier of the "Issuer SMC MK" key within the HSM. This key must be of type 3DES 112 bits.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer of size EFT_EMV_SDA_SEQ_LEN containing the SEQ (PAN Sequence Number). It must be in ASCII format.
[in]	pbOLD_PB	Buffer containing the PIN Block with the current PIN. The buffer must have the size DES_BLOCK (8 bytes). NULL must be passed if the PIN Block with the current password is not required. Blocks in ISO 0/1/2/3 format are supported.
[in]	pbNEW_PB	Buffer containing the PIN Block with the new PIN. The buffer must be the size of a DES_BLOCK (8 bytes). Blocks in ISO 0/1/2/3 format are supported.
[out]	pbOutBlock	Buffer that will contain the output data segment. A maximum buffer size of PBC_EMV_PIN_BLOCK_MAX_OUTPUT can be used, which will be sufficient for all cases.
[in,out]	pdwOutBlockLen	Pointer to a DWORD containing the size of the buffer made available in pbOutPinblock. It will contain the size of the data written in pbOutPinblock in case of success. In case of failure, it will contain the required size of pbOutPinblock.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

If the error D_ERR_OPERATION_FAILED is returned, it may indicate that:

1. The transport key is wrong;
2. The input PIN blocks are unknown or invalid;
3. There has been a failure in the derivation of the ICC or session keys;
4. The type of operation is not valid.

DDeriveEMV_Key()

int AAP_API DDeriveEMV_Key	(	HSESSIONCTX	hSession,
		char *	szSrcKey,
		WORD	wBufferLen,
		BYTE *	pbBuffer,
		BYTE	bOP,
		DWORD	dwAttrib,
		char *	szDstKey,
		HKEYCTX *	phKey,
		DWORD	dwParam )

#include <dinamo.h>

DCalculateARPC()

int AAP_API DCalculateARPC	(	HSESSIONCTX	hSession,
		char *	szIssuerMK,
		char *	szPAN,
		BYTE *	pbSEQ,
		BYTE *	pbARQC,
		BYTE *	pbARC,
		BYTE *	pbARPC,
		DWORD	dwParam )

#include <dinamo.h>

Calculates an ARPC (Authorization Response Cryptogram) following the EMV Book 2 standard (v4.2, 2008), Section 8.2.1, ARPC Method 1.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szIssuerMK	Name of the sender key within the HSM that will be used to generate the MAC.
[in]	szPAN	PAN (Primary Account Number).
[in]	pbSEQ	Buffer of size EFT_EMV_SDA_SEQ_LEN containing the SEQ (PAN Sequence Number).
[in]	pbARQC	DES_BLOCK-sized buffer containing the ARQC (Authorization Request Cryptogram).
[in]	pbARC	Buffer of size 2 (two bytes) containing the ARC (Authorization Response Code).
[out]	pbARPC	Buffer of size DES_BLOCK that will contain the generated ARPC.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

The calculation of Method 2 of ARPC EMV Book 2 (v4.2, 2008), Section 8.2.1, ARPC Method 2 can be done using the DGenerateEMV_MAC() function.

DCalculateARPC_Ex()

int AAP_API DCalculateARPC_Ex	(	HSESSIONCTX	hSession,
		DWORD	dwOp,
		void *	pvInData,
		BYTE *	pbARPC,
		DWORD	dwParam )

#include <dinamo.h>

Calculates an ARPC (Authorization Response Cryptogram).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	dwOp	Type of ARPC operation to be executed. Value Meaning DN_CALC_ARPC_EMV_4_2_M1_ICC Calculates an ARPC in the EMV Book 2 standard (v4.2, 2008), Section 8.2.1, ARPC Method 1 using the issuer key within the HSM. Use the DN_CALC_ARPC_EMV_METHOD_1 structure as a parameter of pvInData. DN_CALC_ARPC_EMV_4_2_M1_SK Calculates an ARPC in the EMV Book 2 standard (v4.2, 2008), Section 8.2.1, ARPC Method 1 using the session key derived from the emisor key within the HSM. Use the DN_CALC_ARPC_EMV_METHOD_1 structure as a parameter of pvInData. DN_CALC_ARPC_EMV_4_2_M2 Calculates an ARPC in the EMV Book 2 standard (v4.2, 2008), Section 8.2.1, ARPC Method 2 using the session key derived from the emisor key within the HSM. Use the DN_CALC_ARPC_EMV_METHOD_2 structure as a parameter of pvInData.
[in]	pvInData	Input data for calculating the ARPC, as described in the parameter dwOP.
[out]	pbARPC	Buffer of size DES_BLOCK that will contain the generated ARPC.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

The calculation of Method 2 of ARPC EMV Book 2 (v4.2, 2008), Section 8.2.1, ARPC Method 2 can also be done using the DGenerateEMV_MAC() function.

DMAC_ISO9797_1_Met2()

int AAP_API DMAC_ISO9797_1_Met2	(	DWORD	dwType,
		BYTE *	pbKey,
		DWORD	dwAlg,
		const BYTE *	pbMsg,
		DWORD	dwMsgLen,
		BYTE *	pbMAC )

#include <dinamo.h>

It generates a MAC (Message Authentication Code) in the ISO/IEC 9797-1 Method 2 standard. This operation is done offline in the library, outside the HSM.

Parameters

[in]	dwType	Type of operation to be carried out, according to the table below.
[in]	pbKey	The buffer containing the key used to generate the MAC must be the same size as the type of key entered in dwAlg.
[in]	dwAlg	Type of key used to generate the MAC.
[in]	pbMsg	Buffer that will go through the MAC process.
[in]	dwMsgLen	Buffer size pbMsg.
[out]	pbMAC	The buffer containing the generated MAC must be DES_BLOCK in size.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DEFTImportKey()

int AAP_API DEFTImportKey	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		int	nKeyAlgId,
		void *	pstKeyParts,
		DWORD	dwParam )

#include <dinamo.h>

Import a key by parts in EFT formats.

Used to import keys by parts:

• DES and 3DES: ZMK (Zone Master Key), also known as ZCMK (Zone Control Master Key) in VISA format;
• AES: in ANSI X9.24 format.

  Parameters

  [in]	hSession	Context acquired through the DOpenSession() function.
  [in]	szKeyId	Name of the key to be imported into the HSM.
  [in]	nKeyAlgId	Supports the following algorithms. Value Meaning ALG_DES, ALG_3DES_112 or ALG_3DES_168 Import a DES key in the format described in VISA Payment Technology Standards Manual, October 2007 Chapter 7 and Appendix C. Use the structure EFT_VISA_KEY_PARTS as a parameter pstKeyParts. ALG_AES_128, ALG_AES_192 or ALG_AES_256 Import an AES key in the format ANSI X9.24 (2004), XOR method (KCV described in Annex C). Use the structure EFT_AES_KEY_PARTS_DATA as a parameter pstKeyParts.
  [in]	pstKeyParts	Pointer to a structure containing the data for reconstructing the key as described in nKeyAlgId.
  [in]	dwParam	Pass 0. Or any of the values below. Value Meaning DN_EFT_AES_KCV_TYPE_CMAC Used to import AES keys in ANSI X9.24 format, with CMAC-type KCV. In accordance with the PCI "PIN Security Requirements".

  Return

  0 (ZERO) if the function is successful.
  See the Return Codes section for other values.

DEFTExportAESKeyParts()

int AAP_API DEFTExportAESKeyParts	(	HSESSIONCTX	hSession,
		BYTE	bKcvType,
		const char *	szKeyId,
		void *	pvKeyParts,
		DWORD	dwReserved )

#include <dinamo.h>

DEFTExportKey()

int AAP_API DEFTExportKey	(	HSESSIONCTX	hSession,
		BYTE	bExportMode,
		char *	szKEKId,
		char *	szKeyId,
		BYTE *	pbEncryptedBlock,
		DWORD *	pdwEncryptedBlockLen,
		BYTE *	pbKeyCheckValue,
		DWORD	dwParam )

#include <dinamo.h>

DEFTKeKImport()

int AAP_API DEFTKeKImport	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		DWORD	dwAlgId,
		char *	szKeKName,
		char *	szKeyName,
		DWORD	dwAttr,
		BYTE *	pbKCV1,
		BYTE *	pbKCV2,
		BYTE *	pbKCV3,
		BYTE *	pbKCVFinal,
		BYTE *	pbBlob,
		DWORD	dwFlags )

#include <dinamo.h>

DEFTExportZPK()

int AAP_API DEFTExportZPK	(	HSESSIONCTX	hSession,
		char *	szKeyId,
		int *	pnKeyAlg,
		int *	pnKeySize,
		EFT_VISA_KEY_PARTS *	pstKeyParts,
		DWORD	dwParam )

#include <dinamo.h>

Exports a ZPK (Zone PIN Key) or ZMK (Zone Master Key) key. The export is done in parts, with their respective check values as described in the VISA Payment Technology Standards Manual, October 2007.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the key to be imported into the HSM.
[out]	pnKeyAlg	Algorithm of the exported a-key.
[out]	pnKeySize	Size of the exported key.
[out]	pstKeyParts	Pointer to an EFT_VISA_KEY_PARTS structure that will contain the parts of the exported key and their KCVs (Key Check Value).
[in]	dwParam	The following options are accepted. Value Meaning 0 Generates the key's KCV (Key Check Value) as defined in ANSI X.9.24 with a size of 3 bytes. DN_EXP_ZPK_FLAG_FULL_CKS Generates the key's KCV (Key Check Value) as defined in ANSI X.9.24 with a size of 8 bytes.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

It can be used to export keys that follow the export by parts standard described in the VISA Payment Technology Standards Manual, October 2007 Chapter 7 and Appendix C. It can be used for ZPK (Zone PIN Key), ZMK (Zone Master Key)/ZCMK (Zone Control Master Key) keys, for example.

DEFTGetKcv()

int AAP_API DEFTGetKcv	(	HSESSIONCTX	hSession,
		BYTE	bType,
		const char *	szKeyId,
		BYTE *	pbKcv,
		DWORD *	pdwKcvLen,
		DWORD	dwReserved )

#include <dinamo.h>

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bType	Type of key to be used to generate the KCV. Value Meaning DN_EFT_GET_KCV_TYPE_X9_24 Generates the key's KCV (Key Check Value) as defined in ANSI X.9.24 with a size of 3 bytes. DN_EFT_GET_KCV_TYPE_CMAC Generates the KCV (Key Check Value) of the key as defined in the PCI PIN Security Requirements with a size of 3 bytes.
[in]	szKeyId	Name of the key that will be used to generate the KCV.
[out]	pbKcv	Pointer to a buffer that will contain the generated KCV. Can be NULL to get the size of the KCV in pdwKcvLen.
[in,out]	pdwKcvLen	Buffer size pbKcv. At the end of the call it will contain the size of the generated KCV.
[in]	dwReserved	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DEFTGenKCVOffline()

int AAP_API DEFTGenKCVOffline	(	DWORD	dwType,
		int	nAlgId,
		const BYTE *	pbKey,
		DWORD	dwKeyLen,
		BYTE *	pbKCV,
		DWORD *	pdwKCVLen,
		DWORD	reserved )

#include <dinamo.h>

Generates a KCV (Key Check Value) of an offline key.

Parameters

[in]	dwType	KCV type. Value Meaning DN_EFT_GEN_OFFLINE_KCV_TYPE_X9_24 Generates the key's KCV (Key Check Value) as defined in ANSI X.9.24 with a size of DN_EFT_KCV_TYPE_X9_24_LEN. DN_EFT_GEN_OFFLINE_KCV_TYPE_CMAC Generates the KCV (Key Check Value) of the key as defined in the PCI PIN Security Requirements with a size of DN_EFT_KCV_TYPE_CMAC_LEN.
[in]	nAlgId	Key algorithm. Currently only DES, 3DES and AES are accepted.
[in]	pbKey	Pointer to the buffer containing the key.
[in]	dwKeyLen	Key size.
[out]	pbKCV	Pointer to the buffer that will contain the generated KCV.
[in,out]	pdwKCVLen	Buffer size pbKCV. At the end of the call it will contain the size of the generated KCV.
[in]	reserved	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

DEFTExportTR31()

int AAP_API DEFTExportTR31	(	HSESSIONCTX	hSession,
		const char *	szKBPK,
		const char *	szKey,
		void *	pvReserved,
		WORD	wUsage,
		BYTE	bMode,
		BYTE	bExport,
		BYTE *	pbOutBlock,
		DWORD *	pdwOutBlockLen,
		DWORD	dwParam )

#include <dinamo.h>

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

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKBPK	Name of the KBPK key (Key Block Protection Key) used to derive the encryption and authentication keys.
[in]	szKey	Name of the key to be exported from the HSM.
[in]	pvReserved	Reserved for future use (must be NULL).
[in]	wUsage	Key usage identifier, as described in ASC X9 TR 31-2018 Section A.5.1 table 6. The following options are accepted. Value Meaning EFT_ME_TR31_EXP_USAGE_AUTO Sets the identifier automatically. The following values are used: EFT_ME_TR31_EXP_USAGE_D0 for symmetric key and EFT_ME_TR31_EXP_USAGE_D1 for asymmetric key. EFT_ME_TR31_EXP_USAGE_B0 BDK Base Derivation Key EFT_ME_TR31_EXP_USAGE_B1 Initial DUKPT Key EFT_ME_TR31_EXP_USAGE_B2 Base Key Variant Key EFT_ME_TR31_EXP_USAGE_C0 CVK Card Verification Key EFT_ME_TR31_EXP_USAGE_D0 Symmetric Key for Data Encryption EFT_ME_TR31_EXP_USAGE_D1 Asymmetric Key for Data Encryption EFT_ME_TR31_EXP_USAGE_D2 Data Encryption Key for Decimalization Table EFT_ME_TR31_EXP_USAGE_E0 EMV/chip Issuer Master Key: Application cryptograms EFT_ME_TR31_EXP_USAGE_E1 EMV/chip Issuer Master Key: Secure Messaging for Confidentiality EFT_ME_TR31_EXP_USAGE_E2 EMV/chip Issuer Master Key: Secure Messaging for Integrity EFT_ME_TR31_EXP_USAGE_E3 EMV/chip Issuer Master Key: Data Authentication Code EFT_ME_TR31_EXP_USAGE_E4 EMV/chip Issuer Master Key: Dynamic Numbers EFT_ME_TR31_EXP_USAGE_E5 EMV/chip Issuer Master Key: Card Personalization EFT_ME_TR31_EXP_USAGE_E6 EMV/chip Issuer Master Key: Other EFT_ME_TR31_EXP_USAGE_I0 Initialization Vector (IV) EFT_ME_TR31_EXP_USAGE_K0 Key Encryption or wrapping EFT_ME_TR31_EXP_USAGE_K1 TR-31 Key Block Protection Key EFT_ME_TR31_EXP_USAGE_K2 TR-34 Asymmetric key EFT_ME_TR31_EXP_USAGE_K3 Asymmetric key for key agreement/key wrapping EFT_ME_TR31_EXP_USAGE_M0 ISO 16609 MAC algorithm 1 (using TDEA) EFT_ME_TR31_EXP_USAGE_M1 ISO 9797-1 MAC Algorithm 1 EFT_ME_TR31_EXP_USAGE_M2 ISO 9797-1 MAC Algorithm 2 EFT_ME_TR31_EXP_USAGE_M3 ISO 9797-1 MAC Algorithm 3 EFT_ME_TR31_EXP_USAGE_M4 ISO 9797-1 MAC Algorithm 4 EFT_ME_TR31_EXP_USAGE_M5 ISO 9797-1:1999 MAC Algorithm 5 EFT_ME_TR31_EXP_USAGE_M6 ISO 9797-1:2011 MAC Algorithm 5/CMAC EFT_ME_TR31_EXP_USAGE_M7 HMAC EFT_ME_TR31_EXP_USAGE_M8 ISO 9797-1:2011 MAC Algorithm 6 EFT_ME_TR31_EXP_USAGE_P0 PIN Encryption EFT_ME_TR31_EXP_USAGE_S0 Asymmetric key pair for digital signature EFT_ME_TR31_EXP_USAGE_S1 Asymmetric key pair, CA key EFT_ME_TR31_EXP_USAGE_S2 Asymmetric key pair, non-X9.24 key EFT_ME_TR31_EXP_USAGE_V0 PIN verification, KPV, other algorithm EFT_ME_TR31_EXP_USAGE_V1 PIN verification, IBM 3624 EFT_ME_TR31_EXP_USAGE_V2 PIN Verification, VISA PVV EFT_ME_TR31_EXP_USAGE_V3 PIN Verification, X9.132 algorithm 1 EFT_ME_TR31_EXP_USAGE_V4 PIN Verification, X9.132 algorithm 2
[in]	bMode	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 EFT_ME_TR31_EXP_MODE_AUTO Sets the usage mode identifier automatically. The following value is used EFT_ME_TR31_EXP_MODE_N. EFT_ME_TR31_EXP_MODE_B Both Encryption & Decryption / Wrap & Unwrap EFT_ME_TR31_EXP_MODE_C Both Generation & Verification EFT_ME_TR31_EXP_MODE_D Decryption / Unwrap Only EFT_ME_TR31_EXP_MODE_E Encryption / Wrap Only EFT_ME_TR31_EXP_MODE_G Generation Only EFT_ME_TR31_EXP_MODE_N No special restrictions (except those defined by the key usage identifier) EFT_ME_TR31_EXP_MODE_S Signature Only EFT_ME_TR31_EXP_MODE_T Both Signature & Decryption EFT_ME_TR31_EXP_MODE_V Verification only EFT_ME_TR31_EXP_MODE_X Key used to derive other key(s) EFT_ME_TR31_EXP_MODE_Y Key used to create key variants
[in]	bExport	Key exportability identifier, as described in ASC X9 TR 31-2018 Section A.5.5 table 10. The following options are accepted. Value Meaning EFT_ME_TR31_EXP_AUTO Sets the exportability identifier automatically. The following value is used EFT_ME_TR31_EXP_X9_24. 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. 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. 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.
[out]	pbOutBlock	Buffer that will contain the key block.
[in,out]	pdwOutBlockLen	Pointer to the size of the buffer passed pbOutBlock. After the API returns it will contain the actual size of the key block stored in pbOutBlock. If the size is not enough, this variable will contain the required size of pbOutBlock.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

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.c.

DEFTImportTR31()

int AAP_API DEFTImportTR31	(	HSESSIONCTX	hSession,
		const char *	szKBPK,
		const char *	szKey,
		DWORD	dwKeyAttributes,
		BYTE *	pbKeyBlock,
		DWORD	dwKeyBlockLen,
		DWORD	dwParam )

#include <dinamo.h>

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

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKBPK	Name of the KBPK key (Key Block Protection Key) used to derive the encryption and authentication keys.
[in]	szKey	Name of the key to be imported into the HSM.
[in]	dwKeyAttributes	Additional key parameters. See the options in the DGenerateKey() function.
[in]	pbKeyBlock	Buffer containing the key block.
[in]	dwKeyBlockLen	Size of the buffer passed pbKeyBlock.
[in]	dwParam	Reserved for future use (must be 0).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

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

Examples

export_import_tr31.c.