Detailed description

Operations for Electronic Funds Transfer.

See HSM technical documentation about operating details, specifications used, licenses and module trade name.

Definitions 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)

#define	DN_EFTD_MAX_KEK_LEN (159)

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)

int AAP_API	DEFTMergeX9_24KeyParts (HSESSIONCTX hSession, const char szDestKey, DWORD dwAttributes, const char szPart1, const char szPart2, const char szPart3, const BYTE *pbExpectedKcv, DWORD dwKcvLen, DWORD dwReserved)

int AAP_API	DEFTLmkEncrypt (HSESSIONCTX hSession, const char szLmk, BYTE bVariant, const char szKey, BYTE bKs, char szOut, DWORD pdwOutLen, 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 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 in parts in the ANSI X9.24 format.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in]

bKcvType

KCV type to be used in the export.

Value	Meaning
DN_EFT_GET_KCV_TYPE_X9_24	Generates the Key Check Value (KCV) of the key as defined in ANSI X.9.24 with a size of 3 bytes.
DN_EFT_GET_KCV_TYPE_CMAC	Generates the Key Check Value (KCV) of the key as defined in 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 key reconstruction.

[in] dwReserved Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values. Generates the Key Check Value (KCV) of the key 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 Key Check Value (KCV) of the key as defined in 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 length 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 Check Value (KCV) of the key 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 Key Check Value (KCV) of the key as defined in 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>

Length of the generated KCV (Key Check Value).

Examples: eft_merge_lmk_encrypt.c.

◆ DN_EFT_KCV_TYPE_CMAC_LEN

#define DN_EFT_KCV_TYPE_CMAC_LEN (3)

#include <dinamo.h>

Length of the generated KCV (Key Check Value).

◆ DN_EFTD_MAX_KEK_LEN

#define DN_EFTD_MAX_KEK_LEN (159)

#include <dinamo.h>

Maximum length of the output string generated by DEFTLmkEncrypt().

Examples: eft_merge_lmk_encrypt.c.

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>

Translates a PIN Block by decrypting it with one key and encrypting it with another. The input block format is automatically identified, and the output block format can be defined by the caller, provided that the format change is not from a PAN Unbound to a PAN Bound format. PAN Bound formats are those that incorporate PAN information in their composition. Therefore, it is possible to perform both key translation and format translation. The caller can enforce format validation by specifying the same format for the output as used in the input PIN Block.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in] szSrcPEK Identifier for the decryption key within the HSM.

[in] szDstPEK Identifier for the encryption key within the HSM.

[in]

bTransBlockType

Identifier for the output block format. As per the table below.

Value	Meaning
TP_TRANSLATE_TYPE_AUTO	Performs an opaque conversion, translating the block from the source key to the destination key, without analyzing the block's format or content. PAN Bound: not applicable.
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	Uses IBM 3624 block type. Not implemented.

[in] szPAN PAN (Primary Account Number).

[in] pbInPinBlock Buffer containing the input PIN Block. The buffer must be the size of a PIN Block, DES_BLOCK (8 bytes).

[out] pbOutPinBlock Buffer that will contain the output PIN Block. The buffer must be the size of a PIN Block, DES_BLOCK (8 bytes).

[in] dwParam Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to 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 for use in PIN protection when submitted from the card chip 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 for generating card verification codes that support the 3-D Secure protocol. For Visa, the service implementing the protocol is Verified by Visa, and the HSM supports the CAVV (Cardholder Authentication Verification Value) standard, which is CVV2 with the ATN method. For Mastercard, 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 differentiated (case-sensitive). This key is the CVK (Card Verification Key), a 112-bit 3DES key, and must be the same one used for CVV verification. This key can be generated internally within the HSM or imported manually. Typically, this key is also used by Visa, sent encrypted by the ZCMK (Zone Control master Key). As determined in the Visa manual, the 112-bit 3DES key used as 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 size 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 PAN size must be exactly 16 digits; if shorter, it must be padded with leading zeros, and if longer, only the 16 rightmost digits should be used.
[in]	szExpirationDate	Expiration date. 4-digit size. For CVV and iCVV generation, the format must be YYMM. For CVV2 generation, the format must be MMYY. In CVC2 calculation, this field must be a null-terminated string containing the 4 least significant digits of the Transaction Sequence Number, found in the AVV (Accountholder Authentication Value) converted to its BCD decimal equivalent. Any value less than 4 digits must be padded with leading zeros to complete the 4 digits. For more details, consult the Mastercard document "SPA Algorithm for the MasterCard Implementation of 3-D Secure – v1.04". In CAVV calculation (CVV2 with the ATN Method), this field must be a null-terminated string containing the 4 least significant digits of the ATN (Authentication Tracking Number). For more details, consult the Visa document "3-D Secure Functional Requirements Access Control Server v. 1.0.2".
[in]	szServiceCode	Service Code. 3-digit size. For iCVV (Alternate Card Verification Value) generation, the Service Code must be 999. For CVV2 generation, the Service Code must be 000. For traditional CVV generation, the Service Code is typically 101.
[out]	szCVV	Output buffer that will contain the generated CVV string. 3 digits long. The generated value can also be a CVV2 or iCVV, depending on the provided Service Code values.
[in]	dwParam	Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes: The API is also compatible with the American Express card scheme 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>

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	Key identifier 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 one used for CVV generation.
[in]	szPAN	PAN (Primary Account Number). 12 to 19 characters long. See more details about this field in the DGenerateCVV() API.
[in]	szExpirationDate	Expiration date. 4 digits long. For CVV and iCVV verification, the format must be YYMM. For CVV2 verification, the format must be MMYY. For information on supporting 3-D Secure protocol algorithms, see more details about this field in the DGenerateCVV() API.
[in]	szServiceCode	Service Code. 3 digits long. For iCVV (Alternate Card Verification Value) verification, the Service Code must be 999. For CVV2 verification, the Service Code must be 000.
[in]	szCVV	CVV to be validated. 3 digits long. The provided value can also be a CVV2 or iCVV, depending on the provided Service Code values.
[in]	dwParam	Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to 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 based on the provided PAN (Personal Account Number) data and key name (PGK), with or without the use of an 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, as per the table below.

Value	Meaning
GP_DEFAULT_PIN	Generates the default PIN based on the PAN and PGK. The szInPin parameter must be NULL.
GP_USER_DEF_PIN	Generates an offset related to the PIN defined by the caller. The szInPin parameter must contain a string with the PIN.
GP_RANDOM_PIN	Randomly generates a PIN and offset based on PAN and PGK. `szInPin` must be NULL.

[in] nPinLen PIN length to be used/generated in the operation. It must have a length between MIN_EFT_PIN_LEN and MAX_EFT_PIN_LEN.

[in] szInPin Input PIN. The buffer must have a size between MIN_EFT_PIN_LEN + 1 and MAX_EFT_PIN_LEN + 1.

[out] szOffset Buffer that will contain the offset string. The buffer must have a size between MIN_EFT_PIN_LEN + 1 and MAX_EFT_PIN_LEN + 1.

[out] szOutPin Buffer that will contain the output PIN string. The buffer must have a size between MIN_EFT_PIN_LEN + 1 and MAX_EFT_PIN_LEN + 1.

[in] dwParam Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to 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>

Verifies the validity of a PIN within a PIN Block. First, the PIN is extracted from the PIN Block using the PTK key, and then its verification is performed with the PGK key, which was used for PIN generation, using the DGeneratePIN() function.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szPTK	Identifier for the 'PIN Block' decryption key within the HSM. This is the PIN Transport Key.
[in]	szPGK	Identifier for the key to be used in PIN verification within the HSM. This is the PIN Generation Key.
[in]	szPAN	PAN (Primary Account Number).
[in]	szOffset	PIN offset. The buffer size must be between MIN_EFT_PIN_LEN + 1 and MAX_EFT_PIN_LEN + 1.
[in]	pbInPinBlock	Buffer that will contain the input PIN Block to be verified. The expected PIN Block format is ISO PIN Block Format 0 (equivalent to ANSI PIN Block Format 0 and VISA PIN Block Format 1). The buffer must have the size of a PIN Block, DES_BLOCK (8 bytes).
[in]	dwParam	Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to 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>

Verifies the validity of VISA key parts against their respective verification values, in the format described in the VISA Payment Technology Standards Manual, October 2007.

Parameters

[in]	nKeyAlgId	Key algorithm to be verified.
[in]	pstKeyParts	Pointer to an EFT_VISA_KEY_PARTS structure containing the key parts to be verified and their respective verification values.
[in]	dwParam	Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes: Only the key parts are verified with their respective verification values; the complete, assembled key is not verified in this test.

◆ DGenerateDUKPT()

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

#include <dinamo.h>

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 MIN_KSI_LEN size containing the KSI (first 05 bytes of the KSN).

[in] pbDID_CTR Buffer of MIN_CTR_LEN size containing the DID and CTR (last 05 bytes of the KSN).

[out] szDUKPT Buffer of size MAX_OBJ_ID that will contain the DUKPT key name generated from the provided parameters.

[in]

dwParam

Operation 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 (PIN Encryption Key) according to ISO X9.24-1-2004 A by XORing the mask 0000 0000 0000 FF00 with the key parts.
NEW_DUKPT_MODE_MEK	Generates an MEK (MAC Encryption Key) according to ISO X9.24-1-2004 A by XORing the mask 0000 0000 0000 00FF with the key parts.
NEW_DUKPT_MODE_DE	Diversifies the generated key into Data Encryption format. It applies an XOR of the mask 0000 0000 00FF 0000 0000 0000 00FF 0000 to the generated DUKPT key, encrypts the left part of the DUKPT key using the generated DUKPT, and repeats the encryption with the right part. After this operation, the encrypted left and right parts are combined to form the Data Encryption Key, as described in IDTECH USER MANUAL SecureMag Encrypted MagStripe Reader (80096504-001 RevL 06/19/14). It must be used in combination (via OR operation) with one of the flags: 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 must be used in combination with other flags. Use only if specifically required.
NEW_DUKPT_MODE_TMP	Generates a temporary DUKPT key. This is an attribute flag and must be used in combination with other flags.
NEW_DUKPT_MODE_IPEK	Generates an IPEK (Initially Loaded PIN Entry Device Key) according to ISO X9.24-1-2004 A-6.

Returns: 0 (ZERO) if the function is successful.
Refer to 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 provided in pbKSI.
[in]	dwParam	Reserved for future use (must be 0).

Returns: 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 DUKPT name from the provided 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 provided in pbKSI and pbCTR.
[in]	dwParam	Reserved for future use (must be 0).

Returns: 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>

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 that will contain the generated PVV string. It must have a minimum size of EFT_PVV_LEN + 1 (null terminator).
[in]	dwParam	Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to 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>

Generates a DAC (Data Authentication Code), taking 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).

Returns: 0 (ZERO) if the function is successful.
Refer to 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>

Verifies a DAC (Data Authentication Code) by 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).
[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).

Returns: 0 (ZERO) if the function is successful.
Refer to 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 an SAD (Static Application Data) for 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	Size of the buffer pointed to by `pbSDA_DATA`.
[in]	pbSDA_DATA	Buffer containing the SDA (Static Application Data) to be signed of the size specified in `dwSDA_DATALen`.
[in,out]	pdwSigLen	Pointer to a DWORD that contains 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).

Returns: 0 (ZERO) if the function is successful.
Refer to 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).

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 Size of the buffer pointed to by pbDDA_DATA.

[in] pbDDA_DATA Buffer containing the certificate data to be signed. Pass 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 size of the pbSig buffer.

[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).

Returns: 0 (ZERO) if the function is successful.
Refer to 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 Master Keys for the ICC (Integrated Circuit Card).

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 that contains 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).

Returns: 0 (ZERO) if the function is successful.
Refer to 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>

Generates an EMV standard cryptogram or MAC (Message Authentication Code), 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.
EMV_OP_ISO_9797_1_M2_VISA	ISO 9797-1 Padding Method 2 VISA.
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 for the szPAN, pbSEQ, and pbNONCE parameters.
EMV_OP_ISO_9797_1_M1_VISA_CRYPTOGRAM_PADD_V10	ISO 9797-1 Padding Method 1 VISA.
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 diversification material used in MAC generation, must have size DES_BLOCK.

Operation type according to parameter bOP	NONCE
EMV_OP_ISO_9797_1_M2_COMMON	ATC (2 bytes)\|\|00\|\|00\|\|00\|\|00\|\|00\|\|00
EMV_OP_ISO_9797_1_M2_MCHIP	CVN10 and CVN11: ATC (2 bytes)\|\|00\|\|00\|\|UC (Unpredictable Number) CVN14 and CVN15: ATC (2 bytes)\|\|00\|\|00\|\|00\|\|00\|\|00\|\|00
EMV_OP_ISO_9797_1_M2_VISA	00\|\|00\|\|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
EMV_OP_ISO_9797_1_M2_JCB	00\|\|00\|\|00\|\|00\|\|00\|\|00\|\|ATC (2 bytes)
EMV_OP_ISO_9797_1_M1_JCB	00\|\|00\|\|00\|\|00\|\|00\|\|00\|\|ATC (2 bytes)
EMV_OP_ISO_9797_1_M1_JCB_CRYPTOGRAM	00\|\|00\|\|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 version of the CVN, when applicable.
For more information on which CVN to use, consult your card scheme administrator.

[in] dwDataLen Size of the buffer pointed to by pbData.

[in] pbData Buffer of the 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 bOP parameter, so the calling application should not pad the data in pbData.

[out] pbMAC Buffer of size DES_BLOCK that will contain the generated MAC.

[in] dwParam Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to 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>

Verifies 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).

Returns: 0 (ZERO) if the function is successful.
Refer to 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 diversification material used in data encryption; its size must be DES_BLOCK.

[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 diversification material used in MAC generation; its size must be DES_BLOCK.

[in] szPAN PAN (Primary Account Number).

[in] pbSEQ Buffer of size EFT_EMV_SDA_SEQ_LEN containing the SEQ (PAN Sequence Number).

[in] dwDataLen Size of the buffer pointed to by pbData.

[in] pbData Buffer of size specified by dwDataLen, containing the data that will be used for encryption/MAC generation.

[in,out] pdwEncDataLen Pointer to a DWORD that contains 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 DES_BLOCK-sized buffer containing the generated MAC. It can be NULL if szMacIK and pbMacNONCE are NULL.

[in] dwParam Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to 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, with HASH being of size EFT_EMV_CSR_VISA_HASH_SIZE.
EFT_EMV_OP_CSR_MASTER	MASTERCARD process standard. The pbCSR buffer will contain CSR + HASH, with HASH being 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 expiration 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).

Returns: 0 (ZERO) if the function is successful.
Refer to 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 `pdbCSR` buffer 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 `pdbCSR` buffer will contain the CSR and `pbHash` the HASH. `pbHash` must be previously allocated with EFT_EMV_CSR_MASTER_HASH_SIZE.
EFT_EMV_OP_CSR_ELO	ELO process standard. The `pdbCSR` buffer will contain the CSR. `pbHash` must be NULL and no HASH will be returned.
EFT_EMV_OP_CSR_JCB	JCB process pattern. The `pdbCSR` buffer 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 expiration date in MMYY format. It must be in ASCII format.

[out] pdbCSR Pointer to a DBLOB that will contain the CSR and its size. The pvData member must be freed with DFree() after use.

[out] pbHash Buffer that will contain the HASH. Refer to the table in bOP for the expected values for this parameter.

[in] dwParam Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to 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 for the derivation type of operational keys used to generate the output block. As per the table below.

Value	Meaning
PBC_EMV_PIN_BLOCK_OP_MCHIP	Operational keys and the output block will be generated according to 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 according to "EMV book 2 v4.2, A1.4.1 option A and A1.4.2 option B" - for card and session keys, respectively. The block will be generated according to "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".
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 card and session keys (the session key is equal to the ICC key). The block will be generated according to "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".
PBC_EMV_PIN_BLOCK_OP_ELO	Operational keys and output blocks will be generated according to 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 according to the JCB IC Card Specification Manual, Version 2.0 - October, 2012.

[in]

pbNONCE

Buffer containing the diversification material, must have size DES_BLOCK.

Identifier used in the bOP parameter	NONCE
PBC_EMV_PIN_BLOCK_OP_MCHIP	Encode as specified by the MCHIP manual: ATC (2 bytes) \|\|00\|\|00\|\|00\|\|00\|\|00\|\|00.
PBC_EMV_PIN_BLOCK_OP_VISA	00\|\|00\|\|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
PBC_EMV_PIN_BLOCK_OP_JCB	00\|\|00\|\|00\|\|00\|\|00\|\|00\|\|ATC (2 bytes). JCB IC Card Specification, Version 2.0 - October, 2012.

[in] szTransportKey Identifier for the transport key within the HSM. This key must be of type DES or 3DES.

[in] szISSUER_MK Identifier for the "Issuer MK" key within the HSM. This key must be of type 3DES 112 bits. This key may be identical to the "Issuer SMC MK" key in certain cases.

[in] szISSUER_SMC_MK Identifier for 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 be of size DES_BLOCK (8 bytes). It should be passed as NULL if the PIN Block with the current password is not required. ISO 0/1/2/3 format blocks 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). ISO 0/1/2/3 format blocks are supported.

[out] pbOutBlock Buffer that will contain the output data segment. A buffer with a maximum 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 to 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).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes

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

The transport key is incorrect;
The input PIN Blocks are unknown or invalid;
Failure occurred in the derivation of ICC or session keys;
The operation type 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 (Authorisation Response Cryptogram) following the EMV Book 2 (v4.2, 2008), Section 8.2.1, ARPC Method 1 standard.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szIssuerMK	Name of the issuer 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	Buffer of DES_BLOCK size containing the ARQC (Authorisation Request Cryptogram).
[in]	pbARC	Buffer of 2 (two bytes) size containing the ARC (Authorisation Response Code).
[out]	pbARPC	Buffer of DES_BLOCK size that will contain the generated ARPC.
[in]	dwParam	Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

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

Examples: eft_calc_arpc.c.

◆ 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 according to EMV Book 2 (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 the pvInData parameter.
DN_CALC_ARPC_EMV_4_2_M1_SK	Calculates an ARPC according to EMV Book 2 (v4.2, 2008), Section 8.2.1, ARPC Method 1, using the session key derived from the issuer key within the HSM. Use the DN_CALC_ARPC_EMV_METHOD_1 structure as the pvInData parameter.
DN_CALC_ARPC_EMV_4_2_M2	Calculates an ARPC according to EMV Book 2 (v4.2, 2008), Section 8.2.1, ARPC Method 2, using the session key derived from the issuer key within the HSM. Use the DN_CALC_ARPC_EMV_METHOD_2 structure as the pvInData parameter.

[in] pvInData Input data for calculating the ARPC, as described in the dwOP parameter.

[out] pbARPC Buffer of DES_BLOCK size that will contain the generated ARPC.

[in] dwParam Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes: The calculation for ARPC EMV Book 2 (v4.2, 2008), Section 8.2.1, ARPC Method 2 can also be performed 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>

Generates a MAC (Message Authentication Code) according to ISO/IEC 9797-1 Method 2. This operation is performed offline in the library, outside the HSM.

Parameters

[in]	dwType	Type of operation to be performed, according to the table below.
[in]	pbKey	The buffer containing the key used to generate the MAC must be the same size as the key type entered in `dwAlg`.
[in]	dwAlg	Key type used for MAC generation.
[in]	pbMsg	Buffer that will undergo the MAC process.
[in]	dwMsgLen	Buffer size `pbMsg`.
[out]	pbMAC	Buffer that will contain the generated MAC; its size must be DES_BLOCK.

Returns: 0 (ZERO) if the function is successful.
Refer to 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>

Imports a key in parts using EFT formats.

Used for importing keys in 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 the VISA Payment Technology Standards Manual, October 2007 Chapter 7 and Appendix C. Use the EFT_VISA_KEY_PARTS structure as the `pstKeyParts` parameter.
ALG_AES_128, ALG_AES_192 or ALG_AES_256	Import an AES key in ANSI X9.24 (2004) format , XOR method (KCV described in Annex C). Use the EFT_AES_KEY_PARTS_DATA structure as the `pstKeyParts` parameter.

[in] pstKeyParts Pointer to a structure containing the data for reconstructing the key as described in nKeyAlgId.

[in]

dwParam

Pass 0, or one of the values below.

Value	Meaning
DN_EFT_AES_KCV_TYPE_CMAC	Used for importing AES keys in ANSI X9.24 format, with CMAC-type KCV. In accordance with PCI "PIN Security Requirements".

Returns: 0 (ZERO) if the function is successful.
Refer to 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). The export is performed in parts, including their respective Key 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 key to be exported.

[out] pnKeySize Size of the exported key.

[out] pstKeyParts Pointer to an EFT_VISA_KEY_PARTS structure that will contain the parts of the key to be exported and its KCVs (Key Check Value).

[in]

dwParam

The following options are accepted.

Value	Meaning
0	Generates the Key Check Value (KCV) of the key as defined in ANSI X.9.24 with a size of 3 bytes.
DN_EXP_ZPK_FLAG_FULL_CKS	Generate the key's KCV (Key Check Value) as defined in ANSI X.9.24 with a size of 8 bytes. Use the EFT_FULL_CKS_KEY_PARTS structure as the `pstKeyParts` parameter.

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes: It can be used for exporting keys that follow the segmented export standard described in the document VISA Payment Technology Standards Manual, october 2007 Chapter 7 e Appendix C. For example, it can be used for ZPK (Zone PIN Key), ZMK (Zone Master Key)/ZCMK (Zone Control Master Key) keys.

◆ 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

Key type to be used for KCV generation.

Value	Meaning
DN_EFT_GET_KCV_TYPE_X9_24	Generates the Key Check Value (KCV) of the key 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 PCI PIN Security Requirements with a size of 3 bytes.

[in] szKeyId Name of the key to be used for KCV generation.

[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 Size of the pbKcv buffer. At the end of the call it will contain the size of the generated KCV.

[in] dwReserved Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to 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) for an offline key.

Parameters

[in]

dwType

KCV type.

Value	Meaning
DN_EFT_GEN_OFFLINE_KCV_TYPE_X9_24	Generates the KCV (Key Check Value) for the key as defined in ANSI X.9.24 with a length of DN_EFT_KCV_TYPE_X9_24_LEN.
DN_EFT_GEN_OFFLINE_KCV_TYPE_CMAC	Generates the KCV (Key Check Value) for the key as defined in PCI PIN Security Requirements with a length 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 that contains the key.

[in] dwKeyLen Key length.

[out] pbKCV Pointer to the buffer that will contain the generated KCV.

[in,out] pdwKCVLen Size of the pbKCV buffer. At the end of the call it will contain the size of the generated KCV.

[in] reserved Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to 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 Block Protection Key) used to derive 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	Automatically defines the identifier. The following values are used: EFT_ME_TR31_EXP_USAGE_D0 for symmetric keys and EFT_ME_TR31_EXP_USAGE_D1 for asymmetric keys.
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, nonX9.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	Automatically defines the usage mode identifier. 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	Automatically defines the exportability identifier. 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 compliant with 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. This 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 compliant 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. Upon return from the API 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).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

Notes

This API exports a key using the generation methods for 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>

Imports 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 Block Protection Key) used to derive encryption and authentication keys.
[in]	szKey	Name of the key to be imported into the HSM.
[in]	dwKeyAttributes	Additional key parameters. See 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).

Returns: 0 (ZERO) if the function is successful.
Refer to 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.

◆ DEFTMergeX9_24KeyParts()

int AAP_API DEFTMergeX9_24KeyParts	(	HSESSIONCTX	hSession,
		const char *	szDestKey,
		DWORD	dwAttributes,
		const char *	szPart1,
		const char *	szPart2,
		const char *	szPart3,
		const BYTE *	pbExpectedKcv,
		DWORD	dwKcvLen,
		DWORD	dwReserved )

#include <dinamo.h>

Generates a symmetric key by combining 2 or 3 key components using XOR, as defined in the ANSI X9.24 standard. After generation, theKey Check Value(KCV) of the generated key is calculated and compared with the expected value to verify the integrity of the resulting key. If the KCV does not match, the generated key is discarded and the function returns an error.

The parties must have the #AUP_X9_24_KEY_PART flag set in order to be used in this function.

It currently supports AES, DES, and 3DES keys.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szDestKey	Name of the destination key to be created on the HSM.
[in]	dwAttributes	Attributes of the generated key. See the options in the DGenerateKey() function. The export attribute is prohibited (EXPORTABLE_KEY must not be used).
[in]	szPart1	Name of the first key component within the HSM.
[in]	szPart2	Name of the second key component within the HSM.
[in]	szPart3	Name of the third key component within the HSM. May be `NULL` for operations involving only two components.
[in]	pbExpectedKcv	A buffer containing the expected KCV of the resulting key, with a size of DN_EFT_KCV_TYPE_X9_24_LEN bytes, as defined in ANSI X.9.24.
[in]	dwKcvLen	Size of the `pbExpectedKcv` buffer. Must be equal to DN_EFT_KCV_TYPE_X9_24_LEN.
[in]	dwReserved	Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

See also: DEFTGetKcv(), DGenerateKey()

Examples: eft_merge_lmk_encrypt.c.

◆ DEFTLmkEncrypt()

int AAP_API DEFTLmkEncrypt	(	HSESSIONCTX	hSession,
		const char *	szLmk,
		BYTE	bVariant,
		const char *	szKey,
		BYTE	bKs,
		char *	szOut,
		DWORD *	pdwOutLen,
		DWORD	dwParam )

#include <dinamo.h>

Exports a symmetric key encrypted with the EFTd module's LMK (Local Master Key).

It currently supports 3DES keys.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szLmk	Name of the LMK (Local Master Key) in the HSM.
[in]	bVariant	LMK variant. See the host operator's manual, sections 7.6.1 and 7.6.2.
[in]	szKey	Name of the key to be exported to the HSM.
[in]	bKs	Key Scheme. Use '0' for legacy/unused. See Appendix 19 of the host operator's manual.
[out]	szOut	Output buffer for the exported key in string format. It can be `NULL` to obtain the required size from `pdwOutLen`.
[in,out]	pdwOutLen	Buffer size `szOut`. If `szOut` is `NULL`, it is set to the maximum required size (DN_EFTD_MAX_KEK_LEN + 1).
[in]	dwParam	Reserved for future use (must be 0).

Returns: 0 (ZERO) if the function is successful.
Refer to the Return Codes section for other values.

See also: DEFTMergeX9_24KeyParts()

Examples: eft_merge_lmk_encrypt.c.

Detailed description

Definitions and Macros

Functions

Definitions and macros

◆ DN_CALC_ARPC_EMV_4_2_M1_ICC

◆ DN_CALC_ARPC_EMV_4_2_M1_SK

◆ DN_CALC_ARPC_EMV_4_2_M2

◆ DN_EFT_AES_KCV_TYPE_CMAC

◆ DN_EFT_GET_KCV_TYPE_X9_24

◆ DN_EFT_GET_KCV_TYPE_CMAC

◆ DN_EXP_ZPK_FLAG_FULL_CKS

◆ DN_EFT_GET_KCV_MAX_LEN

◆ DN_EFT_GEN_OFFLINE_KCV_TYPE_X9_24

◆ DN_EFT_GEN_OFFLINE_KCV_TYPE_CMAC

◆ DN_EFT_KCV_TYPE_X9_24_LEN

◆ DN_EFT_KCV_TYPE_CMAC_LEN

◆ DN_EFTD_MAX_KEK_LEN

Functions

◆ DPINBlockTranslate()

◆ DGenerateCVV()

◆ DVerifyCVV()

◆ DGeneratePIN()

◆ DVerifyPINBlock()

◆ DEFTCheckKeyParts()

◆ DGenerateDUKPT()

◆ DGenerateBDKName()

◆ DGenerateDUKPTName()

◆ DGeneratePVV()

◆ DGenerateDAC()

◆ DVerifyDAC()

◆ DSignSDA()

◆ DGenerateDDA_ICCCert()

◆ DGenerateICCMK()

◆ DGenerateEMV_HMAC()

◆ DGenerateEMV_MAC()

◆ DCheckIDN()

◆ DEncryptEMV()

◆ DGenerateEMV_CSR()

◆ DGenerateEMV_CSREx()

◆ DGenerateEMV_PinBlock()

◆ DDeriveEMV_Key()

◆ DCalculateARPC()

◆ DCalculateARPC_Ex()

◆ DMAC_ISO9797_1_Met2()

◆ DEFTImportKey()

◆ DEFTExportAESKeyParts()

◆ DEFTExportKey()

◆ DEFTKeKImport()

◆ DEFTExportZPK()

◆ DEFTGetKcv()

◆ DEFTGenKCVOffline()

◆ DEFTExportTR31()

◆ DEFTImportTR31()

◆ DEFTMergeX9_24KeyParts()

◆ DEFTLmkEncrypt()