EFT Module

Detailed description

Operations for Electronic Funds Transfer.

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

Electronic Funds Transfer Operations. More...

Functions
String	generateDUKPT (byte[] baKSI, byte[] baDID_CTR, int dwParam) throws TacException
	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	generateDUKPTName (byte[] baKSI, byte[] baDID_CTR) throws TacException
	Generates the DUKPT name from the provided KSI and CTR.
String	generateBDKName (byte[] baKSI) throws TacException
	Generates the BDK name from a KSI (Key Serial Identification).
byte[]	translatePINBlock (String srcPEK, String dstPEK, int transBlockType, String PAN, byte[] inPINBlock) throws TacException
	Translates a PIN Block by decrypting the block with one key and encrypting it with another.
byte[]	exportTR31 (String kbpk, String key, int usage, byte mode, byte export) throws TacException
	Exports a key in TR-31 format according to the ASC X9 TR 31-2018 standard.
void	importTR31 (String kbpk, String key, int keyAttributes, byte[] keyBlock) throws TacException
	Imports a key in TR-31 format according to the ASC X9 TR 31-2018 standard.
void	mergeX9_24KeyParts (String destKey, int attributes, String part1, String part2, String part3, byte[] expectedKcv) throws TacException
	Generates a symmetric key by combining 2 or 3 key components using XOR, as defined in the ANSI X9.24 standard.
EftKeyParts	exportKeyParts (String keyId, int flags) throws TacException
	Export a ZPK (Zone PIN Key) or ZMK (Zone Master Key) key.
void	importKeyParts (String keyId, int keyAlg, EftKeyParts parts, int flags) throws TacException
String	generateCVV (String keyId, String pan, String expirationDate, String serviceCode, int params) throws TacException
	Generates a CVV (Card Verification Value), CVV2, or iCVV using a key within the HSM.
boolean	verifyCVV (String keyId, String pan, String expirationDate, String serviceCode, String cvv, int params) throws TacException
	Checks a CVV (Card Verification Value), CVV2 or iCVV using a key inside the HSM.
boolean	verifyPINBlock (String ptk, String pgk, String pan, String offset, byte[] pinBlock, int param) throws TacException
	Checks the validity of a PIN in a PIN Block.

Functions

generateDUKPT()

String generateDUKPT	(	byte[]	baKSI,
		byte[]	baDID_CTR,
		int	dwParam ) throws TacException

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

baKSI	Buffer of size TacNDJavaLib.MIN_KSI_LEN containing the KSI (first 05 bytes of the KSN).
baDID_CTR	Buffer of size TacNDJavaLib.MIN_CTR_LEN containing the DID and CTR (last 05 bytes of the KSN).
dwParam	Operation flags according to the table below. Value Meaning TacNDJavaLib.NEW_DUKPT_MODE_DUK Generates a standard DUK (Derived Unique Key) according to the ISO X9.24-1-2004 manual. TacNDJavaLib.NEW_DUKPT_MODE_PEK Generates a PEK (PIN Encryption Key) according to the ISO X9.24-1-2004 A-1,A-6 manual by applying an XOR with the mask 0000 0000 0000 FF00 to the key parts. TacNDJavaLib.NEW_DUKPT_MODE_MEK Generates an MEK (MAC Encryption Key) according to the ISO X9.24-1-2004 A-1,A-6 manual by applying an XOR with the mask 0000 0000 0000 00FF to the key parts. TacNDJavaLib.NEW_DUKPT_MODE_DE Diversifies the generated key in Data Encryption format. It applies an XOR of the 0000 0000 00FF 0000 0000 00FF 0000 mask 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). It must be used in combination (via OR operation) with one of the flags: TacNDJavaLib.NEW_DUKPT_MODE_DUK, TacNDJavaLib.NEW_DUKPT_MODE_PEK or TacNDJavaLib.NEW_DUKPT_MODE_MEK. TacNDJavaLib.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. TacNDJavaLib.NEW_DUKPT_MODE_TMP Generates a temporary DUKPT key. This is an attribute flag and must be used in combination with other flags.

Returns

Returns the name of the generated DUKPT key.

Exceptions

TacException

generateDUKPTName()

String generateDUKPTName	(	byte[]	baKSI,
		byte[]	baDID_CTR ) throws TacException

Generates the DUKPT name from the provided KSI and CTR.

Parameters

baKSI	Buffer of size TacNDJavaLib.MIN_KSI_LEN containing the KSI (first 05 bytes of the KSN).
baDID_CTR	Buffer of size TacNDJavaLib.MIN_CTR_LEN containing the DID and CTR (last 05 bytes of the KSN).

Returns

Returns the DUKPT key name.

Exceptions

TacException

generateBDKName()

String generateBDKName

(

byte[]

baKSI

)

throws TacException

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

Parameters

baKSI

Buffer of size TacNDJavaLib.MIN_KSI_LEN containing the KSI (first 05 bytes of the KSN).

Returns

Returns the BDK key name.

Exceptions

TacException

translatePINBlock()

byte[] translatePINBlock	(	String	srcPEK,
		String	dstPEK,
		int	transBlockType,
		String	PAN,
		byte[]	inPINBlock ) throws TacException

Translates a PIN Block by decrypting the block 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. PAN Bound formats are those that incorporate PAN information in their structure. Therefore, both key translation and format translation are possible. The caller can enforce format validation by specifying the same output format as used in the input PIN Block.

Parameters

srcPEK	Identifier for the decryption key within the HSM.
dstPEK	Identifier for the encryption key within the HSM.
transBlockType	Identifier for the output block format. As per the table below. Value Meaning TacNDJavaLib.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. TacNDJavaLib.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. TacNDJavaLib.TP_TRANSLATE_TYPE_ISO_1 Uses ISO PIN Block Format 1. PAN Bound: no. TacNDJavaLib.TP_TRANSLATE_TYPE_ISO_3 Uses ISO PIN Block Format 3. PAN Bound: yes. TacNDJavaLib.TP_TRANSLATE_TYPE_IBM_3624 Uses IBM 3624 block type. Not implemented.
PAN	PAN (Primary Account Number).
inPINBlock	PIN Block input. The buffer must have the size of a PIN Block, TacNDJavaLib.DES_BLOCK (8 bytes)

Returns

Output PIN block.

Exceptions

TacException

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.

exportTR31()

byte[] exportTR31	(	String	kbpk,
		String	key,
		int	usage,
		byte	mode,
		byte	export ) throws TacException

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

Parameters

kbpk	Name of the KBPK (Key Block Protection Key) used to derive 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. The following options are accepted. Value Meaning TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_AUTO Sets the identifier automatically. The following values are used: TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D0 for symmetric key and TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D1 for asymmetric key. TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_B0 BDK Base Derivation Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_B1 Initial DUKPT Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_B2 Base Key Variant Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_C0 CVK Card Verification Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D0 Symmetric Key for Data Encryption TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D1 Asymmetric Key for Data Encryption TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_D2 Data Encryption Key for Decimalization Table TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E0 EMV/chip Issuer Master Key: Application cryptograms TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E1 EMV/chip Issuer Master Key: Secure Messaging for Confidentiality TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E2 EMV/chip Issuer Master Key: Secure Messaging for Integrity TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E3 EMV/chip Issuer Master Key: Data Authentication Code TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E4 EMV/chip Issuer Master Key: Dynamic Numbers TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E5 EMV/chip Issuer Master Key: Card Personalization TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_E6 EMV/chip Issuer Master Key: Other TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_I0 Initialization Vector (IV) TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_K0 Key Encryption or wrapping TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_K1 TR-31 Key Block Protection Key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_K2 TR-34 Asymmetric key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_K3 Asymmetric key for key agreement/key wrapping TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M0 ISO 16609 MAC algorithm 1 (using TDEA) TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M1 ISO 9797-1 MAC Algorithm 1 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M2 ISO 9797-1 MAC Algorithm 2 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M3 ISO 9797-1 MAC Algorithm 3 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M4 ISO 9797-1 MAC Algorithm 4 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M5 ISO 9797-1:1999 MAC Algorithm 5 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M6 ISO 9797-1:2011 MAC Algorithm 5/CMAC TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M7 HMAC TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_M8 ISO 9797-1:2011 MAC Algorithm 6 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_P0 PIN Encryption TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_S0 Asymmetric key pair for digital signature TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_S1 Asymmetric key pair, CA key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_S2 Asymmetric key pair, nonX9.24 key TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V0 PIN verification, KPV, other algorithm TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V1 PIN verification, IBM 3624 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V2 PIN Verification, VISA PVV TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V3 PIN Verification, X9.132 algorithm 1 TacNDJavaLib.EFT_ME_TR31_EXP_USAGE_V4 PIN Verification, X9.132 algorithm 2
mode	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 TacNDJavaLib.EFT_ME_TR31_EXP_MODE_AUTO Sets the usage mode identifier automatically. The following value is used TacNDJavaLib.EFT_ME_TR31_EXP_MODE_N. TacNDJavaLib.EFT_ME_TR31_EXP_MODE_B Both Encryption & Decryption / Wrap & Unwrap TacNDJavaLib.EFT_ME_TR31_EXP_MODE_C Both Generation & Verification TacNDJavaLib.EFT_ME_TR31_EXP_MODE_D Decryption / Unwrap Only TacNDJavaLib.EFT_ME_TR31_EXP_MODE_E Encryption / Wrap Only TacNDJavaLib.EFT_ME_TR31_EXP_MODE_G Generation Only TacNDJavaLib.EFT_ME_TR31_EXP_MODE_N No special restrictions (except those defined by the key usage identifier) TacNDJavaLib.EFT_ME_TR31_EXP_MODE_S Signature Only TacNDJavaLib.EFT_ME_TR31_EXP_MODE_T Both Signature & Decryption TacNDJavaLib.EFT_ME_TR31_EXP_MODE_V Verification Only TacNDJavaLib.EFT_ME_TR31_EXP_MODE_X Key used to derive other key(s) TacNDJavaLib.EFT_ME_TR31_EXP_MODE_Y Key used to create key variants
export	Key exportability identifier, as described in ASC X9 TR 31-2018 Section A.5.5 Table 10. The following options are accepted. Value Meaning TacNDJavaLib.EFT_ME_TR31_EXP_AUTO Defines the exportability identifier automatically. The following value is used TacNDJavaLib.EFT_ME_TR31_EXP_X9_24. TacNDJavaLib.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. TacNDJavaLib.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. TacNDJavaLib.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.

Returns

key block

Exceptions

TacException

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

importTR31()

void importTR31	(	String	kbpk,
		String	key,
		int	keyAttributes,
		byte[]	keyBlock ) throws TacException

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

Parameters

kbpk	Name of the KBPK (Key Block Protection Key) used to derive encryption and authentication keys.
key	Name of the key to be imported into the HSM.
keyAttributes	Additional key parameters. See the options in the createKey() method.
keyBlock	key block

Exceptions

TacException

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

mergeX9_24KeyParts()

void mergeX9_24KeyParts	(	String	destKey,
		int	attributes,
		String	part1,
		String	part2,
		String	part3,
		byte[]	expectedKcv ) throws TacException

Generates a symmetric key by combining 2 or 3 key components using XOR, as defined in the ANSI X9.24 standard.

After generation, the KCV of the generated key is compared with expectedKcv. If they do not match, the generated key is removed and the function returns an error.

Parameters

destKey	Name of the destination key to be created on the HSM.
attributes	Attributes of the generated key. See the options in createKey(). TacNDJavaLib#EXPORTABLE_KEY is prohibited.
part1	Name of the first key component in the HSM. Must have the attribute TacNDJavaLib#AUP_EFT_X9_24_PART.
part2	Name of the second key component in the HSM. Must have the attribute TacNDJavaLib#AUP_EFT_X9_24_PART.
part3	Name of the third key component in the HSM. May be null for operations with only two components. Must have the attribute TacNDJavaLib#AUP_EFT_X9_24_PART.
expectedKcv	Buffer of TacNDJavaLib#DN_EFT_KCV_TYPE_X9_24_LEN bytes with the expected KCV of the resulting key, as per ANSI X9.24.

Exceptions

TacException

If the KCV does not match the expected value or in the event of an error.

See also

importTR31

exportKeyParts()

EftKeyParts exportKeyParts	(	String	keyId,
		int	flags ) throws TacException

Export 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

keyId	Name of the key to be exported.
flags	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. TacNDJavaLib.DN_EXP_ZPK_FLAG_FULL_CKS Generates the KCV (Key Check Value) of the key as defined in ANSI X.9.24 with a size of 8 bytes.

Returns

Returns the export values of the ZPK or ZMK key, containing the KCV (Key Check Value) and the check values needed to reconstruct the key.

See also

EftKeyParts

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.

Exceptions

TacException

importKeyParts()

void importKeyParts	(	String	keyId,
		int	keyAlg,
		EftKeyParts	parts,
		int	flags ) throws TacException

generateCVV()

String generateCVV	(	String	keyId,
		String	pan,
		String	expirationDate,
		String	serviceCode,
		int	params ) throws TacException

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

keyId	Key name. 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 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.
expirationDate	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".
serviceCode	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.
params	Reserved for future use (must be 0).

Returns

3-digit length.
The value generated can also be a CVV2 or iCVV, depending on the Service Code values entered.

Exceptions

TacException

Notes

The API is also compatible with the American Express card scheme standard.

verifyCVV()

boolean verifyCVV	(	String	keyId,
		String	pan,
		String	expirationDate,
		String	serviceCode,
		String	cvv,
		int	params ) throws TacException

Checks a CVV (Card Verification Value), CVV2 or iCVV using a key inside 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 generateCVV() API.

Parameters

keyId	Key name. 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 generateCVV() 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 generateCVV() 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 digits long. The provided value can also be a CVV2 or iCVV, depending on the provided Service Code values.
params	Reserved for future use (must be 0).

Returns

Returns true if the CVV is valid, or false if it is not.

Exceptions

TacException

verifyPINBlock()

boolean verifyPINBlock	(	String	ptk,
		String	pgk,
		String	pan,
		String	offset,
		byte[]	pinBlock,
		int	param ) throws TacException

Checks the validity of a PIN in a PIN Block.

Parameters

ptk	Identifier for the 'PIN Block' decryption key within the HSM. This is the PIN Transport Key.
pgk	Identifier for the key to be used in PIN verification within the HSM. This is the PIN Generation Key.
pan	PAN (Primary Account Number). Length from 12 to 19 characters.
offset	PIN offset. It must be between TacNDJavaLib.MIN_EFT_PIN_LEN and TacNDJavaLib.MAX_EFT_PIN_LEN.
pinBlock	PIN Block to be validated. 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, TacNDJavaLib.DES_BLOCK (8 bytes).
param	Reserved for future use (must be 0).

Returns

Returns true if the PIN is valid, or false if it is not.

Exceptions

TacException