Detailed description

Electronic funds transfer operations.

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 `bOP`so 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:

The transport key is wrong;
The input PIN blocks are unknown or invalid;
There has been a failure in the derivation of the ICC or session keys;
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.

Detailed description

Settings 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

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