Detailed description

Electronic funds transfer operations.

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

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

Functions
string	GenBDKName (byte[] pbKSI)
	Generates the BDK name from a KSI (Key Serial Identification).

string	GenBDKName (byte[] pbKSI, uint dwParam)
	Generates the BDK name from a KSI (Key Serial Identification).

string	GenDUKPT (byte[] pbKSI, byte[] pbDID_CTR, uint dwParam)
	It generates a DUKPT key within the HSM using a KSI (Key Serial Identification), a DID (Device ID) and a CTR (Transaction Counter) from the same KSN (Key Serial Number).

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

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

PinComponents	GenPIN (string pgk, string pan, GenPINOperation operation, int pinLen, string inPin)
	Performs PIN generation operations from the PAN (Personal Account Number) and PGK (Key Name) data entered, with or without the use of offset.

bool	VerifyPINBlock (string ptk, string pgk, string pan, string offset, byte[] pinblock)
	Checks the validity of a PIN in a PIN Block. First the PIN is extracted from the PIN Block with the PTK key, and then it is verified with the PGK key, the same one that was used to generate the PIN, with the GenPIN() function.

byte[]	ExportTR31 (string kbpk, string key, EftExportUsage usage, EftExportMode mode, EftExportExpType exp)
	Exports a key in TR-31 format according to the ASC X9 TR 31-2018 standard.

void	ImportTR31 (string kbpk, string key, bool isExportable, bool isTemporary, byte[] keyBlock)
	Import a key in TR-31 format according to the ASC X9 TR 31-2018 standard.

Enumerations

◆ GenPINOperation

enum GenPINOperation : UInt32

PIN operation options.

Enumerators
DEFAULT_PIN
USER_DEF_PIN
RANDOM_PIN

Examples: eft_gen_pin.cs.

Functions

◆ GenBDKName() [1/2]

string GenBDKName ( byte[] pbKSI )

inline

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

Parameters

pbKSI Buffer of size MIN_KSI_LEN containing the KSI.

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

Exceptions

DinamoException Throws exception in case of error.

Examples: dukpt.cs.

◆ GenBDKName() [2/2]

string GenBDKName	(	byte[]	pbKSI,
		uint	dwParam )

inline

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

Parameters

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

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

Exceptions

DinamoException Throws exception in case of error.

◆ GenDUKPT()

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

inline

It generates a DUKPT key within the HSM using a KSI (Key Serial Identification), a DID (Device ID) and a CTR (Transaction Counter) from the same KSN (Key Serial Number).

Parameters

pbKSI	Buffer of size MIN_KSI_LEN containing the KSI.
pbDID_CTR	Buffer of size MIN_CTR_LEN containing the DID and CTR (last 05 bytes of the KSN).
dwParam	Operation flags according to the table below. NEW_DUKPT_MODE_DUK : Generates a standard DUK (Derived Unique Key) key according to the ISO X9.24-1-2004 manual. NEW_DUKPT_MODE_PEK : Generates a PEK (PIN Encryption Key) key according to the ISO X9.24-1-2004 A manual by applying the XOR of the 0000 0000 0000 FF00 mask to the parts of the key. NEW_DUKPT_MODE_MEK : Generates a MEK key (MAC Encryption Key) according to the ISO X9.24-1-2004 A manual by applying the XOR of the mask 0000 0000 0000 00FF to the parts of the key. NEW_DUKPT_MODE_DE : Diversifies the key generated in Data Encryption format. It applies an XOR of the mask 0000 0000 00FF 0000 0000 00FF 0000 to the generated DUKPT key, encrypts the left key of the DUKPT using the generated DUKPT and repeats the encryption with the right key. After this operation, it joins the encrypted left and right parts to form the Data Encryption Key. As described in IDTECH USER MANUAL SecureMag Encrypted MagStripe Reader (80096504-001 RevL 06/19/14). Must be used in combination (via OR operation) with one of the flags: NEW_DUKPT_MODE_DUK, NEW_DUKPT_MODE_PEK or NEW_DUKPT_MODE_MEK NEW_DUKPT_MODE_EXP : Generates an exportable DUKPT key. This is an attribute flag and should be used in combination with other flags. Only use if specifically required. NEW_DUKPT_MODE_TMP : Generates a temporary DUKPT key. This is an attribute flag and should be used in combination with other flags. NEW_DUKPT_MODE_IPEK : Generates an IPEK key (Initially Loaded PIN Entry Device Key) in accordance with the ISO X9.24-1-2004 A-6 manual.

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

Exceptions

DinamoException Throws exception in case of error.

Examples: dukpt.cs.

◆ GenCVV()

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

inline

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

Parameters

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

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

Exceptions

DinamoException Throws exception in case of error.

Notes: The API is also compatible with the American Express standard.

Examples: eft_gen_verify_cvv.cs.

◆ VerifyCVV()

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

inline

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

Parameters

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

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

Exceptions

DinamoException Throws exception in case of error.

Examples: eft_gen_verify_cvv.cs.

◆ GenPIN()

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

inline

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

Parameters

pgk PGK (PIN Generation Key) key identifier, within the HSM.

pan PAN (Primary Account Number).

operation

Type of PIN generation. According to the table below.

Value	Meaning
GenPINOperation.DEFAULT_PIN	Generates the default PIN based on PAN and PGK. The inPin parameter must be null.
GenPINOperation.USER_DEF_PIN	Generates an offset for the PIN set by the caller. The inPin parameter must contain the PIN.
GenPINOperation.RANDOM_PIN	Randomly generates a PIN and offset based on PAN and PGK. `inPin` must be null.

Parameters

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

Return: PIN and offset.

Exceptions

DinamoException Throws exception in case of error.

Examples: eft_gen_pin.cs.

◆ VerifyPINBlock()

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

inline

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

Parameters

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

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

Exceptions

DinamoException Throws exception in case of error.

Examples: eft_verify_pinblock.cs.

◆ ExportTR31()

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

inline

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

Parameters

kbpk	Name of the KBPK key (Key Block Protection Key) used to derive the encryption and authentication keys.
key	Name of the key to be exported from the HSM.
usage	Key usage identifier, as described in ASC X9 TR 31-2018 Section A.5.1 table 6.
mode	Key usage mode identifier, as described in ASC X9 TR 31-2018 Section A.5.3 table 8.
exp	Key exportability identifier, as described in ASC X9 TR 31-2018 Section A.5.5 table 10.

Return: Key block

Exceptions

DinamoException Throws exception in case of error.

Notes

This API exports a key using the methods for generating key_block below.

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

Examples: export_import_tr31.cs.

◆ ImportTR31()

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

inline

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

Parameters

kbpk	Name of the KBPK key (Key Block Protection Key) used to derive the encryption and authentication keys.
key	Name of the key to be imported into the HSM.
isExportable	Defines whether the imported key is exportable.
isTemporary	Defines whether the imported key is temporary.
keyBlock	Key block in TR-31 format.

Exceptions

DinamoException Throws exception in case of error.

Notes

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

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

Examples: export_import_tr31.cs.

Detailed description

Data Structures

Enumerations

Functions

Enumerations

◆ GenPINOperation

Functions

◆ GenBDKName() [1/2]

◆ GenBDKName() [2/2]

◆ GenDUKPT()

◆ GenCVV()

◆ VerifyCVV()

◆ GenPIN()

◆ VerifyPINBlock()

◆ ExportTR31()

◆ ImportTR31()