Class BaseSMAdapter<T>

java.lang.Object

org.jpos.security.BaseSMAdapter<T>

All Implemented Interfaces:

Configurable, SMAdapter<T>, LogSource

Direct Known Subclasses:

JCESecurityModule

public class BaseSMAdapter<T>
extends Object
implements SMAdapter<T>, Configurable, LogSource

Provides base functionality for the actual Security Module Adapter.

You adapter needs to override the methods that end with "Impl"

Field Summary

Fields

Modifier and Type	Field	Description
protected Configuration	cfg
protected Logger	logger
protected String	realm

Fields inherited from interface SMAdapter

FORMAT00, FORMAT01, FORMAT02, FORMAT03, FORMAT04, FORMAT05, FORMAT34, FORMAT35, FORMAT41, FORMAT42, LENGTH_DES, LENGTH_DES3_2KEY, LENGTH_DES3_3KEY, TYPE_BDK, TYPE_CVK, TYPE_DEK, TYPE_HMAC, TYPE_MK_AC, TYPE_MK_CVC3, TYPE_MK_DAC, TYPE_MK_DN, TYPE_MK_SMC, TYPE_MK_SMI, TYPE_PVK, TYPE_RSA_PK, TYPE_RSA_SK, TYPE_TAK, TYPE_TMK, TYPE_TPK, TYPE_ZAK, TYPE_ZEK, TYPE_ZMK, TYPE_ZPK

Constructor Summary

Constructors

Constructor	Description
BaseSMAdapter()
BaseSMAdapter(Configuration cfg, Logger logger, String realm)

Method Summary

Modifier and Type	Method	Description
String	calculateCAVV(String accountNo, T cvk, String upn, String authrc, String sfarc)	Calaculate a 3-D Secure CAVV/AAV.
protected String	calculateCAVVImpl(String accountNo, T cvk, String upn, String authrc, String sfarc)	Your SMAdapter should override this method if it has this functionality
String	calculateCVD(String accountNo, T cvkA, T cvkB, String expDate, String serviceCode)	Calaculate a Card Verification Digit (Code/Value).
protected String	calculateCVDImpl(String accountNo, T cvkA, T cvkB, String expDate, String serviceCode)	Your SMAdapter should override this method if it has this functionality
String	calculateCVV(String accountNo, T cvkA, T cvkB, Date expDate, String serviceCode)	Calaculate a Card Verification Code/Value.
protected String	calculateCVVImpl(String accountNo, T cvkA, T cvkB, Date expDate, String serviceCode)	Your SMAdapter should override this method if it has this functionality
String	calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, String decTab, String pinValData, int minPinLen)	Calculate an PIN Offset using the IBM 3624 method
String	calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, String decTab, String pinValData, int minPinLen, List<String> excludes)	Calculate an PIN Offset using the IBM 3624 method
String	calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, String decTab, String pinValData, int minPinLen)	Calculate an PIN Offset using the IBM 3624 method of customer selected PIN
String	calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, String decTab, String pinValData, int minPinLen, List<String> excludes)	Calculate an PIN Offset using the IBM 3624 method of customer selected PIN
protected String	calculateIBMPINOffsetImpl(EncryptedPIN pinUnderLmk, T pvk, String decTab, String pinValData, int minPinLen, List<String> excludes)	Your SMAdapter should override this method if it has this functionality
protected String	calculateIBMPINOffsetImpl(EncryptedPIN pinUnderKd1, T kd1, T pvk, String decTab, String pinValData, int minPinLen, List<String> excludes)	Your SMAdapter should override this method if it has this functionality
String	calculatePVV(EncryptedPIN pinUnderLMK, T pvkA, T pvkB, int pvkIdx)	Calculate PVV (VISA PIN Verification Value of PIN under LMK) with exclude list
String	calculatePVV(EncryptedPIN pinUnderLMK, T pvkA, T pvkB, int pvkIdx, List<String> excludes)	Calculate PVV (VISA PIN Verification Value of PIN under LMK)
String	calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx)	Calculate PVV (VISA PIN Verification Value of customer selected PIN)
String	calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx, List<String> excludes)	Calculate PVV (VISA PIN Verification Value of customer selected PIN)
protected String	calculatePVVImpl(EncryptedPIN pinUnderLMK, T pvkA, T pvkB, int pvkIdx, List<String> excludes)	Your SMAdapter should override this method if it has this functionality
protected String	calculatePVVImpl(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx, List<String> excludes)	Your SMAdapter should override this method if it has this functionality
byte[]	calculateSignature(MessageDigest hash, SecureKey privateKey, byte[] data)	Calculate signature of Data Block.
protected byte[]	calculateSignatureImpl(MessageDigest hash, SecureKey privateKey, byte[] data)	Your SMAdapter should override this method if it has this functionality
byte[]	dataDecrypt(T bdk, byte[] clearText)	Decrypt Data
byte[]	dataEncrypt(T bdk, byte[] clearText)	Encrypt Data
byte[]	decryptData(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv)	Decrypt Data Block.
byte[]	decryptData(SecureKey privKey, byte[] data, AlgorithmParameterSpec algspec, byte[] iv)	Decrypts encrypted Data Block with specified cipher.
protected byte[]	decryptDataImpl(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv)	Your SMAdapter should override this method if it has this functionality
protected byte[]	decryptDataImpl(SecureKey decKey, byte[] data, AlgorithmParameterSpec algspec, byte[] iv)	Decrypts Data Block encrypted with assymetric cipher.
String	decryptPIN(EncryptedPIN pinUnderLmk)	Decrypts an Encrypted PIN (under LMK).
protected String	decryptPINImpl(EncryptedPIN pinUnderLmk)	Your SMAdapter should override this method if it has this functionality
EncryptedPIN	deriveIBMPIN(String accountNo, T pvk, String decTab, String pinValData, int minPinLen, String offset)	Derive a PIN Using the IBM 3624 method
protected EncryptedPIN	deriveIBMPINImpl(String accountNo, T pvk, String decTab, String pinValData, int minPinLen, String offset)	Your SMAdapter should override this method if it has this functionality
byte[]	encryptData(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv)	Encrypt Data Block.
byte[]	encryptData(SecureKey encKey, byte[] data, AlgorithmParameterSpec algspec, byte[] iv)	Encrypts clear Data Block with specified cipher.
protected byte[]	encryptDataImpl(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv)	Your SMAdapter should override this method if it has this functionality
protected byte[]	encryptDataImpl(SecureKey encKey, byte[] data, AlgorithmParameterSpec algspec, byte[] iv)	Encrypts clear Data Block with specified cipher.
EncryptedPIN	encryptPIN(String pin, String accountNumber)	Encrypts a clear pin under LMK.
EncryptedPIN	encryptPIN(String pin, String accountNumber, boolean extract)	Encrypts a clear pin under LMK.
EncryptedPIN	encryptPIN(String pin, String accountNumber, T pek)	Encrypts a clear PIN under PEK.
protected EncryptedPIN	encryptPINImpl(String pin, String accountNumber)	Your SMAdapter should override this method if it has this functionality
protected EncryptedPIN	encryptPINImpl(String pin, String accountNumber, T pek)	Your SMAdapter should override this method if it has this functionality.
void	eraseOldLMK()	Erase the key change storage area of memory It is recommended that this command is used after keys stored by the Host have been translated from old to new LMKs.
protected void	eraseOldLMKImpl()	Erase the key change storage area of memory It is recommended that this command is used after keys stored by the Host have been translated from old to new LMKs.
byte[]	exportKey(SecureDESKey key, SecureDESKey kek)	Exports secure key to encryption under a KEK (Key-Encrypting Key).
SecureKey	exportKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec)	Exports secure key to encryption under a KEK (Key-Encrypting Key).
protected byte[]	exportKeyImpl(SecureDESKey key, SecureDESKey kek)	Your SMAdapter should override this method if it has this functionality
protected SecureKey	exportKeyImpl(SecureKey kek, SecureKey key, SecureKeySpec keySpec)	Your SMAdapter should override this method if it has this functionality.
EncryptedPIN	exportPIN(EncryptedPIN pinUnderLmk, T kd2, byte destinationPINBlockFormat)	Exports a PIN from encryption under LMK to encryption under a KD (Data Key).
protected EncryptedPIN	exportPINImpl(EncryptedPIN pinUnderLmk, T kd2, byte destinationPINBlockFormat)	Your SMAdapter should override this method if it has this functionality
SecureDESKey	formKEYfromClearComponents(short keyLength, String keyType, String... clearComponents)	Forms a key from 3 clear components and returns it encrypted under its corresponding LMK The corresponding LMK is determined from the keyType
byte[]	generateARPC(MKDMethod mkdm, SKDMethod skdm, T imkac, String accoutNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData)	Genarate Authorisation Response Cryptogram (ARPC)
protected byte[]	generateARPCImpl(MKDMethod mkdm, SKDMethod skdm, T imkac, String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData)	Your SMAdapter should override this method if it has this functionality
byte[]	generateCBC_MAC(byte[] data, T kd)	Generates CBC-MAC (Cipher Block Chaining Message Authentication Code) for some data.
protected byte[]	generateCBC_MACImpl(byte[] data, T kd)	Your SMAdapter should override this method if it has this functionality
byte[]	generateEDE_MAC(byte[] data, T kd)	Generates EDE-MAC (Encrypt Decrypt Encrypt Message Message Authentication Code) for some data.
protected byte[]	generateEDE_MACImpl(byte[] data, T kd)	Your SMAdapter should override this method if it has this functionality
SecureDESKey	generateKey(short keyLength, String keyType)	Generates a random DES Key.
SecureKey	generateKey(SecureKeySpec keySpec)	Generates a random Key.
byte[]	generateKeyCheckValue(T kd)	Generates key check value.
protected byte[]	generateKeyCheckValueImpl(T kd)	Your SMAdapter should override this method if it has this functionality
protected SecureDESKey	generateKeyImpl(short keyLength, String keyType)	Your SMAdapter should override this method if it has this functionality
protected SecureKey	generateKeyImpl(SecureKeySpec keySpec)	Your SMAdapter should override this method if it has this functionality.
org.javatuples.Pair<PublicKey, SecurePrivateKey>	generateKeyPair(AlgorithmParameterSpec spec)	Generate a public/private key pair.
org.javatuples.Pair<PublicKey, SecureKey>	generateKeyPair(SecureKeySpec keySpec)	Generate a public/private key pair.
protected org.javatuples.Pair<PublicKey, SecurePrivateKey>	generateKeyPairImpl(AlgorithmParameterSpec spec)	Your SMAdapter should override this method if it has this functionality
protected org.javatuples.Pair<PublicKey, SecureKey>	generateKeyPairImpl(SecureKeySpec keySpec)	Your SMAdapter should override this method if it has this functionality.
EncryptedPIN	generatePIN(String accountNumber, int pinLen)	Generate random pin under LMK
EncryptedPIN	generatePIN(String accountNumber, int pinLen, List<String> excludes)	Generate random pin under LMK with exclude list
protected EncryptedPIN	generatePINImpl(String accountNumber, int pinLen, List<String> excludes)	Your SMAdapter should override this method if it has this functionality
byte[]	generateSM_MAC(MKDMethod mkdm, SKDMethod skdm, T imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data)	Generate Secure Message MAC over suppiled message data
protected byte[]	generateSM_MACImpl(MKDMethod mkdm, SKDMethod skdm, T imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data)	Your SMAdapter should override this method if it has this functionality
Logger	getLogger()
String	getName()
String	getRealm()
static SMAdapter	getSMAdapter(String name)
SecureDESKey	importKey(short keyLength, String keyType, byte[] encryptedKey, SecureDESKey kek, boolean checkParity)	Imports a key from encryption under a KEK (Key-Encrypting Key) to protection under the security module.
SecureKey	importKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec, boolean checkParity)	Imports a key from encryption under a KEK (Key-Encrypting Key) to protection under the security module.
protected SecureDESKey	importKeyImpl(short keyLength, String keyType, byte[] encryptedKey, SecureDESKey kek, boolean checkParity)	Your SMAdapter should override this method if it has this functionality
protected SecureKey	importKeyImpl(SecureKey kek, SecureKey key, SecureKeySpec keySpec, boolean checkParity)	Your SMAdapter should override this method if it has this functionality.
EncryptedPIN	importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk)	Imports a PIN from encryption under a transaction key to encryption under LMK.
EncryptedPIN	importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, boolean tdes)	Imports a PIN from encryption under a transaction key to encryption under LMK.
EncryptedPIN	importPIN(EncryptedPIN pinUnderKd1, T kd1)	Imports a PIN from encryption under KD (Data Key) to encryption under LMK.
protected EncryptedPIN	importPINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk)	Deprecated.
protected EncryptedPIN	importPINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, boolean tdes)	Your SMAdapter should override this method if it has this functionality
protected EncryptedPIN	importPINImpl(EncryptedPIN pinUnderKd1, T kd1)	Your SMAdapter should override this method if it has this functionality
void	printPIN(String accountNo, EncryptedPIN pinUnderKd1, T kd1, String template, Map<String,String> fields)	Print PIN or PIN and solicitation data to the HSM configured printer.
protected void	printPINImpl(String accountNo, EncryptedPIN pinUnderKd1, T kd1, String template, Map<String,String> fields)	Your SMAdapter should override this method if it has this functionality
void	setConfiguration(Configuration cfg)
void	setLogger(Logger logger, String realm)
void	setName(String name)	associates this SMAdapter with a name using NameRegistrar
SecureDESKey	translateKeyFromOldLMK(SecureDESKey kd)	Translate key from encryption under the LMK held in key change storage to encryption under a new LMK.
SecureKey	translateKeyFromOldLMK(SecureKey key, SecureKeySpec keySpec)	Translate key from encryption under the LMK held in key change storage to encryption under a new LMK.
protected SecureDESKey	translateKeyFromOldLMKImpl(SecureDESKey kd)	Translate key from encryption under the LMK held in key change storage to encryption under a new LMK.
protected SecureKey	translateKeyFromOldLMKImpl(SecureKey key, SecureKeySpec keySpec)	Your SMAdapter should override this method if it has this functionality.
SecureDESKey	translateKeyScheme(SecureDESKey key, KeyScheme destKeyScheme)	Translate Key Scheme to more secure encription.
protected SecureDESKey	translateKeySchemeImpl(SecureDESKey key, KeyScheme destKeyScheme)	Your SMAdapter should override this method if it has this functionality
EncryptedPIN	translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat)	Translates a PIN from encryption under a transaction key to encryption under a KD (Data Key).
EncryptedPIN	translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat, boolean tdes)	Translates a PIN from encryption under a transaction key to encryption under a KD (Data Key).
EncryptedPIN	translatePIN(EncryptedPIN pinUnderKd1, T kd1, T kd2, byte destinationPINBlockFormat)	Translates a PIN from encrytion under KD1 to encryption under KD2.
org.javatuples.Pair<EncryptedPIN, byte[]>	translatePINGenerateSM_MAC(MKDMethod mkdm, SKDMethod skdm, PaddingMethod padm, T imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data, EncryptedPIN currentPIN, EncryptedPIN newPIN, T kd1, T imksmc, T imkac, byte destinationPINBlockFormat)	Translate PIN and generate MAC over suppiled message data
protected org.javatuples.Pair<EncryptedPIN, byte[]>	translatePINGenerateSM_MACImpl(MKDMethod mkdm, SKDMethod skdm, PaddingMethod padm, T imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data, EncryptedPIN currentPIN, EncryptedPIN newPIN, T kd1, T imksmc, T imkac, byte destinationPINBlockFormat)	Your SMAdapter should override this method if it has this functionality
protected EncryptedPIN	translatePINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat)	Deprecated.
protected EncryptedPIN	translatePINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat, boolean tdes)	Your SMAdapter should override this method if it has this functionality
protected EncryptedPIN	translatePINImpl(EncryptedPIN pinUnderKd1, T kd1, T kd2, byte destinationPINBlockFormat)	Your SMAdapter should override this method if it has this functionality
boolean	verifyARQC(MKDMethod mkdm, SKDMethod skdm, T imkac, String accoutNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] txnData)	Verify Application Cryptogram (ARQC or TC/AAC) Authorization Request Cryptogram (ARQC) - Online authorization Transaction certificate (TC) - Offline approval Application Authentication Cryptogram (AAC) - Offline decline
byte[]	verifyARQCGenerateARPC(MKDMethod mkdm, SKDMethod skdm, T imkac, String accoutNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] txnData, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData)	Verify Application Cryptogram (ARQC or TC/AAC) and Genarate Authorisation Response Cryptogram (ARPC) Authorization Request Cryptogram (ARQC) - Online authorization Transaction certificate (TC) - Offline approval Application Authentication Cryptogram (AAC) - Offline decline
protected byte[]	verifyARQCGenerateARPCImpl(MKDMethod mkdm, SKDMethod skdm, T imkac, String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] transData, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData)	Your SMAdapter should override this method if it has this functionality
protected boolean	verifyARQCImpl(MKDMethod mkdm, SKDMethod skdm, T imkac, String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] txnData)	Your SMAdapter should override this method if it has this functionality
boolean	verifyCAVV(String accountNo, T cvk, String cavv, String upn, String authrc, String sfarc)	Verify a 3-D Secure CAVV/AAV.
protected boolean	verifyCAVVImpl(String accountNo, T cvk, String cavv, String upn, String authrc, String sfarc)	Your SMAdapter should override this method if it has this functionality
boolean	verifyCVC3(T imkcvc3, String accountNo, String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm, String cvc3)	Verify a Dynamic Card Verification Code 3 (CVC3)
protected boolean	verifyCVC3Impl(T imkcvc3, String accountNo, String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm, String cvc3)	Your SMAdapter should override this method if it has this functionality
boolean	verifyCVD(String accountNo, T cvkA, T cvkB, String cvv, String expDate, String serviceCode)	Verify a Card Verification Digit (Code/Value).
boolean	verifyCVV(String accountNo, T cvkA, T cvkB, String cvv, Date expDate, String serviceCode)	Verify a Card Verification Code/Value.
protected boolean	verifyCVVImpl(String accountNo, T cvkA, T cvkB, String cvv, String expDate, String serviceCode)	Your SMAdapter should override this method if it has this functionality
protected boolean	verifyCVVImpl(String accountNo, T cvkA, T cvkB, String cvv, Date expDate, String serviceCode)	Your SMAdapter should override this method if it has this functionality
boolean	verifydCVV(String accountNo, T imkac, String dcvv, String expDate, String serviceCode, byte[] atc, MKDMethod mkdm)	Verify a Dynamic Card Verification Value (dCVV).
boolean	verifydCVV(String accountNo, T imkac, String dcvv, Date expDate, String serviceCode, byte[] atc, MKDMethod mkdm)	Verify a Dynamic Card Verification Value (dCVV).
protected boolean	verifydCVVImpl(String accountNo, T imkac, String dcvv, String expDate, String serviceCode, byte[] atc, MKDMethod mkdm)	Your SMAdapter should override this method if it has this functionality
protected boolean	verifydCVVImpl(String accountNo, T imkac, String dcvv, Date expDate, String serviceCode, byte[] atc, MKDMethod mkdm)	Your SMAdapter should override this method if it has this functionality
boolean	verifyIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, String offset, String decTab, String pinValData, int minPinLen)	Verify an PIN Offset using the IBM 3624 method
protected boolean	verifyIBMPINOffsetImpl(EncryptedPIN pinUnderKd, T kd, T pvk, String offset, String decTab, String pinValData, int minPinLen)	Your SMAdapter should override this method if it has this functionality
boolean	verifyPVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvki, String pvv)	Verify PVV (VISA PIN Verification Value of an LMK encrypted PIN)
protected boolean	verifyPVVImpl(EncryptedPIN pinUnderKd, T kd, T pvkA, T pvkB, int pvki, String pvv)	Your SMAdapter should override this method if it has this functionality

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface SMAdapter

generateClearKeyComponent

Field Details

logger

protected Logger logger

realm

protected String realm

cfg

protected Configuration cfg

Constructor Details

BaseSMAdapter

public BaseSMAdapter()

BaseSMAdapter

public BaseSMAdapter(Configuration cfg,
 Logger logger,
 String realm)
              throws ConfigurationException

Throws:

ConfigurationException

Method Details

setConfiguration

public void setConfiguration(Configuration cfg)
                      throws ConfigurationException

Specified by:

setConfiguration in interface Configurable

Parameters:

cfg - Configuration object

Throws:

ConfigurationException

setLogger

public void setLogger(Logger logger,
 String realm)

Specified by:

setLogger in interface LogSource

getLogger

public Logger getLogger()

Specified by:

getLogger in interface LogSource

getRealm

public String getRealm()

Specified by:

getRealm in interface LogSource

setName

public void setName(String name)

associates this SMAdapter with a name using NameRegistrar

Parameters:

name - name to register

See Also:

• NameRegistrar

getName

public String getName()

Returns:

this SMAdapter's name ("" if no name was set)

getSMAdapter

public static SMAdapter getSMAdapter(String name)
                              throws NameRegistrar.NotFoundException

Parameters:

name -

Returns:

SMAdapter instance with given name.

Throws:

NameRegistrar.NotFoundException

See Also:

• NameRegistrar

generateKey

public SecureDESKey generateKey(short keyLength,
 String keyType)
                         throws SMException

Description copied from interface: SMAdapter

Generates a random DES Key.

Specified by:

generateKey in interface SMAdapter<T>

Parameters:

keyLength - bit length of the key to be generated (LENGTH_DES, LENGTH_DES3_2KEY...)

keyType - type of the key to be generated (TYPE_ZMK, TYPE_TMK...etc)

Returns:

the random key secured by the security module

Throws:

SMException

generateKey

public SecureKey generateKey(SecureKeySpec keySpec)
                      throws SMException

Description copied from interface: SMAdapter

Generates a random Key.

Specified by:

generateKey in interface SMAdapter<T>

Parameters:

keySpec - the specification of the key to be generated (length, type, usage, algorithm, etc)

Returns:

the random key secured by the security module

Throws:

SMException

See Also:

• SecureKeySpec

generateKeyCheckValue

public byte[] generateKeyCheckValue(T kd)
                             throws SMException

Description copied from interface: SMAdapter

Generates key check value.

Specified by:

generateKeyCheckValue in interface SMAdapter<T>

Parameters:

kd - the key with untrusted or fake Key Check Value

Returns:

key check value bytes

Throws:

SMException

translateKeyScheme

public SecureDESKey translateKeyScheme(SecureDESKey key,
 KeyScheme destKeyScheme)
                                throws SMException

Description copied from interface: SMAdapter

Translate Key Scheme to more secure encription.

Converts an DES key encrypted using X9.17 methods to a more secure key using the variant method.

Specified by:

translateKeyScheme in interface SMAdapter<T>

Parameters:

key - key to be translated to destKeyScheme scheme

destKeyScheme - destination key scheme

Returns:

translated key with destKeyScheme scheme

Throws:

SMException

importKey

public SecureDESKey importKey(short keyLength,
 String keyType,
 byte[] encryptedKey,
 SecureDESKey kek,
 boolean checkParity)
                       throws SMException

Description copied from interface: SMAdapter

Imports a key from encryption under a KEK (Key-Encrypting Key) to protection under the security module.

Specified by:

importKey in interface SMAdapter<T>

Parameters:

keyLength - bit length of the key to be imported (LENGTH_DES, LENGTH_DES3_2KEY...etc)

keyType - type of the key to be imported (TYPE_ZMK, TYPE_TMK...etc)

encryptedKey - key to be imported encrypted under KEK

kek - the key-encrypting key

checkParity - if true, the key is not imported unless it has adjusted parity

Returns:

imported key secured by the security module

Throws:

SMException - if the parity of the imported key is not adjusted AND checkParity = true

importKey

public SecureKey importKey(SecureKey kek,
 SecureKey key,
 SecureKeySpec keySpec,
 boolean checkParity)
                    throws SMException

Description copied from interface: SMAdapter

Imports a key from encryption under a KEK (Key-Encrypting Key) to protection under the security module.

Specified by:

importKey in interface SMAdapter<T>

Parameters:

kek - the key-encrypting key

key - key to be imported and encrypted under KEK

keySpec - the specification of the key to be imported. It allows passing or change key block attributes.

checkParity - if true, the key is not imported unless it has adjusted parity

Returns:

imported key secured by the security module

Throws:

SMException - e.g: if the parity of the imported key is not adjusted and checkParity is true

exportKey

public byte[] exportKey(SecureDESKey key,
 SecureDESKey kek)
                 throws SMException

Description copied from interface: SMAdapter

Exports secure key to encryption under a KEK (Key-Encrypting Key).

Specified by:

exportKey in interface SMAdapter<T>

Parameters:

key - the secure key to be exported

kek - the key-encrypting key

Returns:

the exported key (key encrypted under kek)

Throws:

SMException

exportKey

public SecureKey exportKey(SecureKey kek,
 SecureKey key,
 SecureKeySpec keySpec)
                    throws SMException

Description copied from interface: SMAdapter

Exports secure key to encryption under a KEK (Key-Encrypting Key).

Specified by:

exportKey in interface SMAdapter<T>

Parameters:

kek - the key-encrypting key

key - the secure key to be exported

keySpec - the specification of the key to be exported. It allows passing or change key block attributes.

Returns:

the exported key (key encrypted under kek)

Throws:

SMException

encryptPIN

public EncryptedPIN encryptPIN(String pin,
 String accountNumber,
 boolean extract)
                        throws SMException

Description copied from interface: SMAdapter

Encrypts a clear pin under LMK.

CAUTION: The use of clear pin presents a significant security risk

Specified by:

encryptPIN in interface SMAdapter<T>

Parameters:

pin - clear pin as entered by cardholder

accountNumber - if extract is false then account number, including BIN and the check digit or if parameter extract is true then 12 right-most digits of the account number, excluding the check digit

extract - true to extract 12 right-most digits off the account number

Returns:

PIN under LMK

Throws:

SMException

encryptPIN

public EncryptedPIN encryptPIN(String pin,
 String accountNumber)
                        throws SMException

Description copied from interface: SMAdapter

Encrypts a clear pin under LMK.

CAUTION: The use of clear pin presents a significant security risk

Specified by:

encryptPIN in interface SMAdapter<T>

Parameters:

pin - clear pin as entered by card holder

accountNumber - account number, including BIN and the check digit

Returns:

PIN under LMK

Throws:

SMException

encryptPIN

public EncryptedPIN encryptPIN(String pin,
 String accountNumber,
 T pek)
                        throws SMException

Description copied from interface: SMAdapter

Encrypts a clear PIN under PEK.

CAUTION: The use of clear PIN presents a significant security risk.

Specified by:

encryptPIN in interface SMAdapter<T>

Parameters:

pin - Clear PIN as entered by cardholder.

accountNumber - account number, including BIN and the check digit.

pek - PIN encryption key.

Returns:

Return PIN under PEK.

Throws:

SMException

decryptPIN

public String decryptPIN(EncryptedPIN pinUnderLmk)
                  throws SMException

Description copied from interface: SMAdapter

Decrypts an Encrypted PIN (under LMK).

CAUTION: The use of clear pin presents a significant security risk

Specified by:

decryptPIN in interface SMAdapter<T>

Parameters:

pinUnderLmk -

Returns:

clear pin as entered by card holder

Throws:

SMException

importPIN

public EncryptedPIN importPIN(EncryptedPIN pinUnderKd1,
 T kd1)
                       throws SMException

Description copied from interface: SMAdapter

Imports a PIN from encryption under KD (Data Key) to encryption under LMK.

Specified by:

importPIN in interface SMAdapter<T>

Parameters:

pinUnderKd1 - the encrypted PIN

kd1 - Data Key under which the pin is encrypted

Returns:

pin encrypted under LMK

Throws:

SMException

translatePIN

public EncryptedPIN translatePIN(EncryptedPIN pinUnderKd1,
 T kd1,
 T kd2,
 byte destinationPINBlockFormat)
                          throws SMException

Description copied from interface: SMAdapter

Translates a PIN from encrytion under KD1 to encryption under KD2.

Specified by:

translatePIN in interface SMAdapter<T>

Parameters:

pinUnderKd1 - pin encrypted under KD1

kd1 - Data Key (also called session key) under which the pin is encrypted

kd2 - the destination Data Key 2 under which the pin will be encrypted

destinationPINBlockFormat - the PIN Block Format of the exported encrypted PIN

Returns:

pin encrypted under KD2

Throws:

SMException

importPIN

public EncryptedPIN importPIN(EncryptedPIN pinUnderDuk,
 KeySerialNumber ksn,
 T bdk)
                       throws SMException

Description copied from interface: SMAdapter

Imports a PIN from encryption under a transaction key to encryption under LMK.

The transaction key is derived from the Key Serial Number and the Base Derivation Key using DUKPT (Derived Unique Key per Transaction). See ANSI X9.24 for more information.

Specified by:

importPIN in interface SMAdapter<T>

Parameters:

pinUnderDuk - pin encrypted under a transaction key

ksn - Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction key

bdk - Base Derivation Key, used to derive the transaction key underwhich the pin is encrypted

Returns:

pin encrypted under LMK

Throws:

SMException

importPIN

public EncryptedPIN importPIN(EncryptedPIN pinUnderDuk,
 KeySerialNumber ksn,
 T bdk,
 boolean tdes)
                       throws SMException

Description copied from interface: SMAdapter

Imports a PIN from encryption under a transaction key to encryption under LMK.

The transaction key is derived from the Key Serial Number and the Base Derivation Key using DUKPT (Derived Unique Key per Transaction). See ANSI X9.24 for more information.

Specified by:

importPIN in interface SMAdapter<T>

Parameters:

pinUnderDuk - pin encrypted under a transaction key

ksn - Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction key

bdk - Base Derivation Key, used to derive the transaction key underwhich the pin is encrypted

tdes - Use Triple DES to calculate derived transaction key.

Returns:

pin encrypted under LMK

Throws:

SMException

translatePIN

public EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk,
 KeySerialNumber ksn,
 T bdk,
 T kd2,
 byte destinationPINBlockFormat)
                          throws SMException

Description copied from interface: SMAdapter

Translates a PIN from encryption under a transaction key to encryption under a KD (Data Key).

The transaction key is derived from the Key Serial Number and the Base Derivation Key using DUKPT (Derived Unique Key per Transaction). See ANSI X9.24 for more information.

Specified by:

translatePIN in interface SMAdapter<T>

Parameters:

pinUnderDuk - pin encrypted under a DUKPT transaction key

ksn - Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction key

bdk - Base Derivation Key, used to derive the transaction key underwhich the pin is encrypted

kd2 - the destination Data Key (also called session key) under which the pin will be encrypted

destinationPINBlockFormat - the PIN Block Format of the translated encrypted PIN

Returns:

pin encrypted under kd2

Throws:

SMException

translatePIN

public EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk,
 KeySerialNumber ksn,
 T bdk,
 T kd2,
 byte destinationPINBlockFormat,
 boolean tdes)
                          throws SMException

Description copied from interface: SMAdapter

Translates a PIN from encryption under a transaction key to encryption under a KD (Data Key).

The transaction key is derived from the Key Serial Number and the Base Derivation Key using DUKPT (Derived Unique Key per Transaction). See ANSI X9.24 for more information.

Specified by:

translatePIN in interface SMAdapter<T>

Parameters:

pinUnderDuk - pin encrypted under a DUKPT transaction key

ksn - Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction key

bdk - Base Derivation Key, used to derive the transaction key underwhich the pin is encrypted

kd2 - the destination Data Key (also called session key) under which the pin will be encrypted

destinationPINBlockFormat - the PIN Block Format of the translated encrypted PIN

tdes - Use Triple DES to calculate derived transaction key.

Returns:

pin encrypted under kd2

Throws:

SMException

exportPIN

public EncryptedPIN exportPIN(EncryptedPIN pinUnderLmk,
 T kd2,
 byte destinationPINBlockFormat)
                       throws SMException

Description copied from interface: SMAdapter

Exports a PIN from encryption under LMK to encryption under a KD (Data Key).

Specified by:

exportPIN in interface SMAdapter<T>

Parameters:

pinUnderLmk - pin encrypted under LMK

kd2 - the destination data key (also called session key) under which the pin will be encrypted

destinationPINBlockFormat - the PIN Block Format of the exported encrypted PIN

Returns:

pin encrypted under kd2

Throws:

SMException

generatePIN

public EncryptedPIN generatePIN(String accountNumber,
 int pinLen)
                         throws SMException

Description copied from interface: SMAdapter

Generate random pin under LMK

Specified by:

generatePIN in interface SMAdapter<T>

Parameters:

accountNumber - The 12 right-most digits of the account number excluding the check digit

pinLen - length of the pin, usually in range 4-12. Value 0 means that default length is assumed by HSM (usually 4)

Returns:

generated PIN under LMK

Throws:

SMException

generatePIN

public EncryptedPIN generatePIN(String accountNumber,
 int pinLen,
 List<String> excludes)
                         throws SMException

Description copied from interface: SMAdapter

Generate random pin under LMK with exclude list

Specified by:

generatePIN in interface SMAdapter<T>

Parameters:

accountNumber - The 12 right-most digits of the account number excluding the check digit

pinLen - length of the pin, usually in range 4-12. Value 0 means that default length is assumed by HSM (usually 4)

excludes - list of pins which won't be generated. Each pin has to be pinLen length

Returns:

generated PIN under LMK

Throws:

SMException

printPIN

public void printPIN(String accountNo,
 EncryptedPIN pinUnderKd1,
 T kd1,
 String template,
 Map<String,String> fields)
              throws SMException

Description copied from interface: SMAdapter

Print PIN or PIN and solicitation data to the HSM configured printer.

If kd1 includes an encrypted PIN block then is first imported, Also template is updated if needed in HSM storage. Then the PIN and solicitation data are included into the template and result are printed to the HSM attached printer.

Specified by:

printPIN in interface SMAdapter<T>

Parameters:

accountNo - The 12 right-most digits of the account number excluding the check digit.

pinUnderKd1 - pin block under Key Data 1

kd1 - Data Key 1 ZPK, TPK may be null if pinUnderKd1 contains PIN under LMK

template - template text (PCL, PostScript or other) for PIN Mailer printer. Its format depends on used HSM. This template should includes placeholders tags (e.g. in format ${tag}) indicationg place where coresponding value or PIN should be inserted. Tags values are passed in fields map argument except PIN which is passed in argument pinUnderKd1.

fields - map of tags values representing solicitation data to include in template. null if no solicitation data are passed

Throws:

SMException

calculatePVV

public String calculatePVV(EncryptedPIN pinUnderLMK,
 T pvkA,
 T pvkB,
 int pvkIdx)
                    throws SMException

Description copied from interface: SMAdapter

Calculate PVV (VISA PIN Verification Value of PIN under LMK) with exclude list

NOTE: pvkA and pvkB should be single length keys but at least one of them may be double length key

Specified by:

calculatePVV in interface SMAdapter<T>

Parameters:

pinUnderLMK - PIN under LMK

pvkA - first key PVK in PVK pair

pvkB - second key PVK in PVK pair

pvkIdx - index of the PVK, in range 0-6, if not present 0 is assumed

Returns:

PVV (VISA PIN Verification Value)

Throws:

SMException - if PIN is on exclude list WeakPINException is thrown

calculatePVV

public String calculatePVV(EncryptedPIN pinUnderLMK,
 T pvkA,
 T pvkB,
 int pvkIdx,
 List<String> excludes)
                    throws SMException

Description copied from interface: SMAdapter

Calculate PVV (VISA PIN Verification Value of PIN under LMK)

NOTE: pvkA and pvkB should be single length keys but at least one of them may be double length key

Specified by:

calculatePVV in interface SMAdapter<T>

Parameters:

pinUnderLMK - PIN under LMK

pvkA - first key PVK in PVK pair

pvkB - second key PVK in PVK pair

pvkIdx - index of the PVK, in range 0-6, if not present 0 is assumed

excludes - list of pins which won't be generated. Each pin has to be pinLen length

Returns:

PVV (VISA PIN Verification Value)

Throws:

SMException

calculatePVV

public String calculatePVV(EncryptedPIN pinUnderKd1,
 T kd1,
 T pvkA,
 T pvkB,
 int pvkIdx)
                    throws SMException

Description copied from interface: SMAdapter

Calculate PVV (VISA PIN Verification Value of customer selected PIN)

NOTE: pvkA and pvkB should be single length keys but at least one of them may be double length key

Specified by:

calculatePVV in interface SMAdapter<T>

Parameters:

pinUnderKd1 - the encrypted PIN

kd1 - Data Key under which the pin is encrypted

pvkA - first key PVK in PVK pair

pvkB - second key PVK in PVK pair

pvkIdx - index of the PVK, in range 0-6, if not present 0 is assumed

Returns:

PVV (VISA PIN Verification Value)

Throws:

SMException

calculatePVV

public String calculatePVV(EncryptedPIN pinUnderKd1,
 T kd1,
 T pvkA,
 T pvkB,
 int pvkIdx,
 List<String> excludes)
                    throws SMException

Description copied from interface: SMAdapter

Calculate PVV (VISA PIN Verification Value of customer selected PIN)

NOTE: pvkA and pvkB should be single length keys but at least one of them may be double length key

Specified by:

calculatePVV in interface SMAdapter<T>

Parameters:

pinUnderKd1 - the encrypted PIN

kd1 - Data Key under which the pin is encrypted

pvkA - first key PVK in PVK pair

pvkB - second key PVK in PVK pair

pvkIdx - index of the PVK, in range 0-6, if not present 0 is assumed

excludes - list of pins which won't be generated. Each pin has to be pinLen length

Returns:

PVV (VISA PIN Verification Value)

Throws:

SMException

verifyPVV

public boolean verifyPVV(EncryptedPIN pinUnderKd1,
 T kd1,
 T pvkA,
 T pvkB,
 int pvki,
 String pvv)
                  throws SMException

Description copied from interface: SMAdapter

Verify PVV (VISA PIN Verification Value of an LMK encrypted PIN)

NOTE: pvkA and pvkB should be single length keys but at least one of them may be double length key

Specified by:

verifyPVV in interface SMAdapter<T>

Parameters:

pinUnderKd1 - pin block under kd1

kd1 - Data Key (also called session key) under which the pin is encrypted (ZPK or TPK)

pvkA - first PVK in PVK pair

pvkB - second PVK in PVK pair

pvki - index of the PVK, in range 0-6, if not present 0 is assumed

pvv - (VISA PIN Verification Value)

Returns:

true if pin is valid false if not

Throws:

SMException

calculateIBMPINOffset

public String calculateIBMPINOffset(EncryptedPIN pinUnderLmk,
 T pvk,
 String decTab,
 String pinValData,
 int minPinLen)
                             throws SMException

Description copied from interface: SMAdapter

Calculate an PIN Offset using the IBM 3624 method

Using that method is not recomendated. PVV method is prefrred, but it may be need in some legacy systms

Specified by:

calculateIBMPINOffset in interface SMAdapter<T>

Parameters:

pinUnderLmk - PIN under LMK

pvk - accepts single, double, triple size key length. Single key length is recomendated

decTab - decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configuration

pinValData - pin validation data. User-defined data consisting of hexadecimal characters and the character N, which indicates to the HSM where to insert the last 5 digits of the account number. Usualy it consists the first digits of the card number

minPinLen - pin minimal length

Returns:

IBM PIN Offset

Throws:

SMException

calculateIBMPINOffset

public String calculateIBMPINOffset(EncryptedPIN pinUnderLmk,
 T pvk,
 String decTab,
 String pinValData,
 int minPinLen,
 List<String> excludes)
                             throws SMException

Description copied from interface: SMAdapter

Calculate an PIN Offset using the IBM 3624 method

Using that method is not recomendated. PVV method is prefrred, but it may be need in some legacy systms

Specified by:

calculateIBMPINOffset in interface SMAdapter<T>

Parameters:

pinUnderLmk - PIN under LMK

pvk - accepts single, double, triple size key length. Single key length is recomendated

decTab - decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configuration

pinValData - pin validation data. User-defined data consisting of hexadecimal characters and the character N, which indicates to the HSM where to insert the last 5 digits of the account number. Usualy it consists the first digits of the card number

minPinLen - pin minimal length

excludes - list of pins which won't be generated. Each pin has to be pinLen length

Returns:

IBM PIN Offset

Throws:

SMException

calculateIBMPINOffset

public String calculateIBMPINOffset(EncryptedPIN pinUnderKd1,
 T kd1,
 T pvk,
 String decTab,
 String pinValData,
 int minPinLen)
                             throws SMException

Description copied from interface: SMAdapter

Calculate an PIN Offset using the IBM 3624 method of customer selected PIN

Using that method is not recomendated. PVV method is prefrred, but it may be need in some legacy systms

Specified by:

calculateIBMPINOffset in interface SMAdapter<T>

Parameters:

pinUnderKd1 - the encrypted PIN

kd1 - Data Key under which the pin is encrypted

pvk - accepts single, double, triple size key length. Single key length is recomendated

decTab - decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configuration

pinValData - pin validation data. User-defined data consisting of hexadecimal characters and the character N, which indicates to the HSM where to insert the last 5 digits of the account number. Usualy it consists the first digits of the card number

minPinLen - pin minimal length

Returns:

IBM PIN Offset

Throws:

SMException

calculateIBMPINOffset

public String calculateIBMPINOffset(EncryptedPIN pinUnderKd1,
 T kd1,
 T pvk,
 String decTab,
 String pinValData,
 int minPinLen,
 List<String> excludes)
                             throws SMException

Description copied from interface: SMAdapter

Calculate an PIN Offset using the IBM 3624 method of customer selected PIN

Using that method is not recomendated. PVV method is prefrred, but it may be need in some legacy systms

Specified by:

calculateIBMPINOffset in interface SMAdapter<T>

Parameters:

pinUnderKd1 - the encrypted PIN

kd1 - Data Key under which the pin is encrypted

pvk - accepts single, double, triple size key length. Single key length is recomendated

decTab - decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configuration

pinValData - pin validation data. User-defined data consisting of hexadecimal characters and the character N, which indicates to the HSM where to insert the last 5 digits of the account number. Usualy it consists the first digits of the card number

minPinLen - pin minimal length

excludes - list of pins which won't be generated. Each pin has to be pinLen length

Returns:

IBM PIN Offset

Throws:

SMException

verifyIBMPINOffset

public boolean verifyIBMPINOffset(EncryptedPIN pinUnderKd1,
 T kd1,
 T pvk,
 String offset,
 String decTab,
 String pinValData,
 int minPinLen)
                           throws SMException

Description copied from interface: SMAdapter

Verify an PIN Offset using the IBM 3624 method

Specified by:

verifyIBMPINOffset in interface SMAdapter<T>

Parameters:

pinUnderKd1 - pin block under kd1

kd1 - Data Key (also called session key) under which the pin is encrypted (ZPK or TPK)

pvk - accepts single, double, triple size key length. Single key length is recomendated

offset - IBM PIN Offset

decTab - decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configuration

pinValData - pin validation data. User-defined data consisting of hexadecimal characters and the character N, which indicates to the HSM where to insert the last 5 digits of the account number. Usualy it consists the first digits of the card number

minPinLen - min pin length

Returns:

true if pin offset is valid false if not

Throws:

SMException

deriveIBMPIN

public EncryptedPIN deriveIBMPIN(String accountNo,
 T pvk,
 String decTab,
 String pinValData,
 int minPinLen,
 String offset)
                          throws SMException

Description copied from interface: SMAdapter

Derive a PIN Using the IBM 3624 method

That method derive pin from pin offset (not exacly that same but working). Therefore that metod is not recomendated. It is similar to obtain pin from encrypted pinblock, but require (encrypted) decimalisation table handling is more complicated and returned pin may differ from pin what user has selected It may be uable e.g. in migration from pin offset method to PVV method

Specified by:

deriveIBMPIN in interface SMAdapter<T>

Parameters:

accountNo - the 12 right-most digits of the account number excluding the check digit

pvk - accepts single, double, triple size key length. Single key length is recomendated

decTab - decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configuration

pinValData - pin validation data. User-defined data consisting of hexadecimal characters and the character N, which indicates to the HSM where to insert the last 5 digits of the account number. Usualy it consists the first digits of the card number

minPinLen - min pin length

offset - IBM PIN Offset

Returns:

PIN under LMK

Throws:

SMException

calculateCVV

public String calculateCVV(String accountNo,
 T cvkA,
 T cvkB,
 Date expDate,
 String serviceCode)
                    throws SMException

Description copied from interface: SMAdapter

Calaculate a Card Verification Code/Value.

NOTE: cvkA and cvkB should be single length keys but at least one of them may be double length key

Specified by:

calculateCVV in interface SMAdapter<T>

Parameters:

accountNo - The account number including BIN and the check digit

cvkA - the first CVK in CVK pair

cvkB - the second CVK in CVK pair

expDate - the card expiration date

serviceCode - the card service code Service code should be:

• the value which will be placed onto card's magnetic stripe for encoding CVV1/CVC1
• "000" for printing CVV2/CVC2 on card's signature stripe
• "999" for inclusion iCVV/Chip CVC on EMV chip card

Returns:

Card Verification Code/Value

Throws:

SMException

calculateCVD

public String calculateCVD(String accountNo,
 T cvkA,
 T cvkB,
 String expDate,
 String serviceCode)
                    throws SMException

Description copied from interface: SMAdapter

Calaculate a Card Verification Digit (Code/Value).

NOTE: cvkA and cvkB should be single length keys but at least one of them may be double length key

Specified by:

calculateCVD in interface SMAdapter<T>

Parameters:

accountNo - The account number including BIN and the check digit

cvkA - the first CVK in CVK pair

cvkB - the second CVK in CVK pair

expDate - the card expiration date

serviceCode - the card service code Service code should be:

• the value which will be placed onto card's magnetic stripe for encoding CVV1/CVC1
• "000" for printing CVV2/CVC2 on card's signature stripe
• "999" for inclusion iCVV/Chip CVC on EMV chip card

Returns:

Card Verification Digit (Code/Value)

Throws:

SMException

calculateCAVV

public String calculateCAVV(String accountNo,
 T cvk,
 String upn,
 String authrc,
 String sfarc)
                     throws SMException

Description copied from interface: SMAdapter

Calaculate a 3-D Secure CAVV/AAV.

• Visa uses CAVV (Cardholder Authentication Verification Value)
• MasterCard uses AAV (Accountholder Authentication Value)

NOTE: Algorithm used to calculation CAVV/AAV is same as for CVV/CVC calculation. Only has been changed meaning of parameters expDate and serviceCode.

Specified by:

calculateCAVV in interface SMAdapter<T>

Parameters:

accountNo - the account number including BIN and the check digit.

cvk - the key used to CVV/CVC generation

upn - the unpredictable number. Calculated value based on Transaction Identifier (xid) from PAReq. A 4 decimal digits value must be supplied.

authrc - the Authentication Results Code. A value based on the Transaction Status (status) that will be used in PARes. A 1 decimal digit value must be supplied.

sfarc - the Second Factor Authentication Results Code. A value based on the result of second factor authentication. A 2 decimal digits value must be suppiled.

Returns:

Cardholder Authentication Verification Value/Accountholder Authentication Value

Throws:

SMException

verifyCVV

public boolean verifyCVV(String accountNo,
 T cvkA,
 T cvkB,
 String cvv,
 Date expDate,
 String serviceCode)
                  throws SMException

Description copied from interface: SMAdapter

Verify a Card Verification Code/Value.

NOTE: cvkA and cvkB should be single length keys but at least one of them may be double length key

Specified by:

verifyCVV in interface SMAdapter<T>

Parameters:

accountNo - The account number including BIN and the check digit

cvkA - the first CVK in CVK pair

cvkB - the second CVK in CVK pair

cvv - Card Verification Code/Value

expDate - the card expiration date

serviceCode - the card service code Service code should be:

• taken from card's magnetic stripe for verifing CVV1/CVC1
• "000" for verifing CVV2/CVC2 printed on card's signature stripe
• "999" for verifing iCVV/Chip CVC included on EMV chip card

Returns:

true if CVV/CVC is valid or false if not

Throws:

SMException

verifyCVD

public boolean verifyCVD(String accountNo,
 T cvkA,
 T cvkB,
 String cvv,
 String expDate,
 String serviceCode)
                  throws SMException

Description copied from interface: SMAdapter

Verify a Card Verification Digit (Code/Value).

NOTE: cvkA and cvkB should be single length keys but at least one of them may be double length key

Specified by:

verifyCVD in interface SMAdapter<T>

Parameters:

accountNo - The account number including BIN and the check digit

cvkA - the first CVK in CVK pair

cvkB - the second CVK in CVK pair

cvv - Card Verification Code/Value

expDate - the card expiration date

serviceCode - the card service code Service code should be:

• taken from card's magnetic stripe for verifing CVV1/CVC1
• "000" for verifing CVV2/CVC2 printed on card's signature stripe
• "999" for verifing iCVV/Chip CVC included on EMV chip card

Returns:

true if CVV/CVC is valid or false otherwise

Throws:

SMException

verifyCAVV

public boolean verifyCAVV(String accountNo,
 T cvk,
 String cavv,
 String upn,
 String authrc,
 String sfarc)
                   throws SMException

Description copied from interface: SMAdapter

Verify a 3-D Secure CAVV/AAV.

• Visa uses CAVV (Cardholder Authentication Verification Value)
• MasterCard uses AAV (Accountholder Authentication Value)

NOTE: Algorithm used to verification CAVV/AAV is same as for CVV/CVC verification. Only has been changed meaning of parameters expDate and serviceCode.

Specified by:

verifyCAVV in interface SMAdapter<T>

Parameters:

accountNo - the account number including BIN and the check digit.

cvk - the key used to CVV/CVC generation

cavv - the Cardholder Authentication Verification Value or Accountholder Authentication Value.

upn - the unpredictable number. Calculated value based on Transaction Identifier (xid) from PAReq. A 4 decimal digits value must be supplied.

authrc - the Authentication Results Code. A value based on the Transaction Status (status) that will be used in PARes. A 1 decimal digit value must be supplied.

sfarc - the Second Factor Authentication Results Code. A value based on the result of second factor authentication. A 2 decimal digits value must be suppiled.

Returns:

true if CAVV/AAV is valid or false if not

Throws:

SMException

verifydCVV

public boolean verifydCVV(String accountNo,
 T imkac,
 String dcvv,
 Date expDate,
 String serviceCode,
 byte[] atc,
 MKDMethod mkdm)
                   throws SMException

Description copied from interface: SMAdapter

Verify a Dynamic Card Verification Value (dCVV).

The EMV "Track 2 Equivalent Data", provided in the authorisation message and originating from the contactless smart card, is the source for the following data elements used in this function:

accountNo

expDate

serviceCode

atc

dCVV

Specified by:

verifydCVV in interface SMAdapter<T>

Parameters:

accountNo - The account number including BIN and the check digit

imkac - the issuer master key for generating and verifying Application Cryptograms

dcvv - dynamic Card Verification Value

expDate - the card expiration date

serviceCode - the card service code

atc - application transactin counter. This is used for ICC Master Key derivation. A 2 byte value must be supplied.

mkdm - ICC Master Key Derivation Method. If null specified is assumed.

Returns:

true if dcvv is valid, or false if not

Throws:

SMException

verifydCVV

public boolean verifydCVV(String accountNo,
 T imkac,
 String dcvv,
 String expDate,
 String serviceCode,
 byte[] atc,
 MKDMethod mkdm)
                   throws SMException

Description copied from interface: SMAdapter

Verify a Dynamic Card Verification Value (dCVV).

The EMV "Track 2 Equivalent Data", provided in the authorisation message and originating from the contactless smart card, is the source for the following data elements used in this function:

• accountNo
• expDate
• serviceCode
• atc
• dCVV

Specified by:

verifydCVV in interface SMAdapter<T>

Parameters:

accountNo - The account number including BIN and the check digit

imkac - the issuer master key for generating and verifying Application Cryptograms

dcvv - dynamic Card Verification Value

expDate - the card expiration date

serviceCode - the card service code

atc - application transactin counter. This is used for ICC Master Key derivation. A 2 byte value must be supplied.

mkdm - ICC Master Key Derivation Method. If null specified is assumed.

Returns:

true if dcvv is valid, or false if not

Throws:

SMException

verifyCVC3

public boolean verifyCVC3(T imkcvc3,
 String accountNo,
 String acctSeqNo,
 byte[] atc,
 byte[] upn,
 byte[] data,
 MKDMethod mkdm,
 String cvc3)
                   throws SMException

Description copied from interface: SMAdapter

Verify a Dynamic Card Verification Code 3 (CVC3)

The EMV "Track 2 Equivalent Data", provided in the authorisation message and originating from the contactless smart card, is the source for the following data elements used in this function:

• accountNo
• expDate
• serviceCode
• atc
• unpredictable number
• cvc3

Specified by:

verifyCVC3 in interface SMAdapter<T>

Parameters:

imkcvc3 - the issuer master key for generating and verifying CVC3

accountNo - The account number including BIN and the check digit

acctSeqNo - account sequence number, 2 decimal digits

atc - application transactin counter. This is used for ICC Master Key derivation. A 2 byte value must be supplied.

upn - unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied.

data - track data

mkdm - ICC Master Key Derivation Method. If null specified is assumed.

cvc3 - dynamic Card Verification Code 3

Returns:

true if cvc3 is valid false if not

Throws:

SMException

verifyARQC

public boolean verifyARQC(MKDMethod mkdm,
 SKDMethod skdm,
 T imkac,
 String accoutNo,
 String acctSeqNo,
 byte[] arqc,
 byte[] atc,
 byte[] upn,
 byte[] txnData)
                   throws SMException

Description copied from interface: SMAdapter

Verify Application Cryptogram (ARQC or TC/AAC)

• Authorization Request Cryptogram (ARQC) - Online authorization
• Transaction certificate (TC) - Offline approval
• Application Authentication Cryptogram (AAC) - Offline decline

Specified by:

verifyARQC in interface SMAdapter<T>

Parameters:

mkdm - ICC Master Key Derivation Method. For skdm equals SKDMethod.VSDC and SKDMethod.MCHIP this parameter is ignored and MKDMethod.OPTION_A is always used.

skdm - Session Key Derivation Method

imkac - the issuer master key for generating and verifying Application Cryptograms

accoutNo - account number including BIN and check digit

acctSeqNo - account sequence number, 2 decimal digits

arqc - ARQC/TC/AAC. A 8 byte value must be supplied.

atc - application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.

upn - unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.

txnData - transaction data. Transaction data elements and them order is dependend to proper cryptogram version. If the data supplied is a multiple of 8 bytes, no extra padding is added. If it is not a multiple of 8 bytes, additional zero padding is added. If alternative padding methods are required, it have to be applied before.

Returns:

true if ARQC/TC/AAC is passed or false if not

Throws:

SMException

generateARPC

public byte[] generateARPC(MKDMethod mkdm,
 SKDMethod skdm,
 T imkac,
 String accoutNo,
 String acctSeqNo,
 byte[] arqc,
 byte[] atc,
 byte[] upn,
 ARPCMethod arpcMethod,
 byte[] arc,
 byte[] propAuthData)
                    throws SMException

Description copied from interface: SMAdapter

Genarate Authorisation Response Cryptogram (ARPC)

Specified by:

generateARPC in interface SMAdapter<T>

Parameters:

mkdm - ICC Master Key Derivation Method. For skdm equals SKDMethod.VSDC and SKDMethod.MCHIP this parameter is ignored and MKDMethod.OPTION_A is always used.

skdm - Session Key Derivation Method

imkac - the issuer master key for generating and verifying Application Cryptograms

accoutNo - account number including BIN and check digit

acctSeqNo - account sequence number, 2 decimal digits

arqc - ARQC/TC/AAC. A 8 byte value must be supplied.

atc - application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.

upn - unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.

arpcMethod - ARPC calculating method. For skdm equals SKDMethod.VSDC, SKDMethod.MCHIP, SKDMethod.AEPIS_V40 only ARPCMethod.METHOD_1 is valid

arc - the Authorisation Response Code. A 2 byte value must be supplied. For arpcMethod equals ARPCMethod.METHOD_2 it is csu - Card Status Update. Then a 4 byte value must be supplied.

propAuthData - Proprietary Authentication Data. Up to 8 bytes. Contains optional issuer data for transmission to the card in the Issuer Authentication Data of an online transaction. It may by used only for arpcMethod equals ARPCMethod.METHOD_2 in other case is ignored.

Returns:

calculated 8 bytes ARPC or if arpcMethod equals ARPCMethod.METHOD_2 4 bytes ARPC

Throws:

SMException

verifyARQCGenerateARPC

public byte[] verifyARQCGenerateARPC(MKDMethod mkdm,
 SKDMethod skdm,
 T imkac,
 String accoutNo,
 String acctSeqNo,
 byte[] arqc,
 byte[] atc,
 byte[] upn,
 byte[] txnData,
 ARPCMethod arpcMethod,
 byte[] arc,
 byte[] propAuthData)
                              throws SMException

Description copied from interface: SMAdapter

Verify Application Cryptogram (ARQC or TC/AAC) and Genarate Authorisation Response Cryptogram (ARPC)

• Authorization Request Cryptogram (ARQC) - Online authorization
• Transaction certificate (TC) - Offline approval
• Application Authentication Cryptogram (AAC) - Offline decline

Specified by:

verifyARQCGenerateARPC in interface SMAdapter<T>

Parameters:

mkdm - ICC Master Key Derivation Method. For skdm equals SKDMethod.VSDC and SKDMethod.MCHIP this parameter is ignored and MKDMethod.OPTION_A is always used.

skdm - Session Key Derivation Method

imkac - the issuer master key for generating and verifying Application Cryptograms

accoutNo - account number including BIN and check digit

acctSeqNo - account sequence number, 2 decimal digits

arqc - ARQC/TC/AAC. A 8 byte value must be supplied.

atc - application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.

upn - unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.

txnData - transaction data. Transaction data elements and them order is dependend to proper cryptogram version. If the data supplied is a multiple of 8 bytes, no extra padding is added. If it is not a multiple of 8 bytes, additional zero padding is added. If alternative padding methods are required, it have to be applied before.

arpcMethod - ARPC calculating method. For skdm equals SKDMethod.VSDC, SKDMethod.MCHIP, SKDMethod.AEPIS_V40 only ARPCMethod.METHOD_1 is valid

arc - the Authorisation Response Code. A 2 byte value must be supplied. For arpcMethod equals ARPCMethod.METHOD_2 it is csu - Card Status Update. Then a 4 byte value must be supplied.

propAuthData - Proprietary Authentication Data. Up to 8 bytes. Contains optional issuer data for transmission to the card in the Issuer Authentication Data of an online transaction. It may by used only for arpcMethod equals ARPCMethod.METHOD_2 in other case is ignored.

Returns:

if ARQC/TC/AAC verification passed then calculated 8 bytes ARPC or for arpcMethod equals ARPCMethod.METHOD_2 4 bytes ARPC, null in other case

Throws:

SMException

generateSM_MAC

public byte[] generateSM_MAC(MKDMethod mkdm,
 SKDMethod skdm,
 T imksmi,
 String accountNo,
 String acctSeqNo,
 byte[] atc,
 byte[] arqc,
 byte[] data)
                      throws SMException

Description copied from interface: SMAdapter

Generate Secure Message MAC over suppiled message data

This method is used by issuer to generate MAC over message data send from the issuer back to the card

Specified by:

generateSM_MAC in interface SMAdapter<T>

Parameters:

mkdm - ICC Master Key Derivation Method. For skdm equals SKDMethod.VSDC and SKDMethod.MCHIP this parameter is ignored and MKDMethod.OPTION_A is always used.

skdm - Session Key Derivation Method

imksmi - the issuer master key for Secure Messaging Integrity

accountNo - account number including BIN and check digit

acctSeqNo - account sequence number, 2 decimal digits

atc - application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used. Second usage is as part of data which will be macked

arqc - ARQC/TC/AAC. A 8 byte value must be supplied. For skdm equals SKDMethod.MCHIP RAND should be suppiled. RAND is ARQC incremeted by 1 (with overflow) after each script command for that same ATC value

data - for which MAC will be generated. Should contain APDU command e.g. PIN Unblock, Application block/unblock with some additional application dependent data

Returns:

generated 8 bytes MAC

Throws:

SMException

translatePINGenerateSM_MAC

public org.javatuples.Pair<EncryptedPIN, byte[]> translatePINGenerateSM_MAC(MKDMethod mkdm,
 SKDMethod skdm,
 PaddingMethod padm,
 T imksmi,
 String accountNo,
 String acctSeqNo,
 byte[] atc,
 byte[] arqc,
 byte[] data,
 EncryptedPIN currentPIN,
 EncryptedPIN newPIN,
 T kd1,
 T imksmc,
 T imkac,
 byte destinationPINBlockFormat)
                                                                     throws SMException

Description copied from interface: SMAdapter

Translate PIN and generate MAC over suppiled message data

This method is used by issuer to:

• translate standard ATM PIN block format encrypted under zone or terminal key kd1 to an application specific PIN block format, encrypted under a confidentiality session key, derived from imksmc
• generate MAC over suppiled message data and translated PIN block

Specified by:

translatePINGenerateSM_MAC in interface SMAdapter<T>

Parameters:

mkdm - ICC Master Key Derivation Method. For skdm equals SKDMethod.VSDC and SKDMethod.MCHIP this parameter is ignored and MKDMethod.OPTION_A is always used.

skdm - Session Key Derivation Method

padm - padding method. If null padm is derived as follow:

skdm value	derived padm value
SKDMethod.VSDC	PaddingMethod.VSDC
SKDMethod.MCHIP	PaddingMethod.MCHIP
SKDMethod.EMV_CSKD	PaddingMethod.CCD

Other variations require to explicite pass padm value

imksmi - the issuer master key for Secure Messaging Integrity

accountNo - account number including BIN and check digit

acctSeqNo - account sequence number, 2 decimal digits

atc - application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used. Second usage is as part of data which will be macked

arqc - ARQC/TC/AAC. A 8 byte value must be supplied. For skdm equals SKDMethod.MCHIP RAND should be suppiled. RAND is ARQC incremeted by 1 (with overflow) after each script command for that same ATC value

data - for which MAC will be generated. Should contain APDU command PIN Change with some additional application dependent data

currentPIN - encrypted under kd1 current PIN. Used when destinationPINBlockFormat equals SMAdapter.FORMAT42

newPIN - encrypted under kd1 new PIN.

kd1 - Data Key (also called transport key) under which the source pin is encrypted

imksmc - the issuer master key for Secure Messaging Confidentiality

imkac - the issuer master key for generating and verifying Application Cryptograms. Used when destinationPINBlockFormat equals SMAdapter.FORMAT41 or SMAdapter.FORMAT42 in other cases is ignored

destinationPINBlockFormat - the PIN Block Format of the translated encrypted PIN

Allowed values:

SMAdapter.FORMAT34 Standard EMV PIN Block

SMAdapter.FORMAT35 Europay/Mastercard

SMAdapter.FORMAT41 Visa/Amex format without using Current PIN

SMAdapter.FORMAT42 Visa/Amex format using Current PIN

Returns:

Pair of values, encrypted PIN and 8 bytes MAC

Throws:

SMException

encryptData

public byte[] encryptData(CipherMode cipherMode,
 SecureDESKey kd,
 byte[] data,
 byte[] iv)
                   throws SMException

Encrypt Data Block.

Specified by:

encryptData in interface SMAdapter<T>

Parameters:

cipherMode - block cipher mode

kd - DEK or ZEK key used to encrypt data

data - data to be encrypted

iv - initial vector

Returns:

encrypted data

Throws:

SMException

decryptData

public byte[] decryptData(CipherMode cipherMode,
 SecureDESKey kd,
 byte[] data,
 byte[] iv)
                   throws SMException

Decrypt Data Block.

Specified by:

decryptData in interface SMAdapter<T>

Parameters:

cipherMode - block cipher mode

kd - DEK or ZEK key used to decrypt data

data - data to be decrypted

iv - initial vector

Returns:

decrypted data

Throws:

SMException

generateCBC_MAC

public byte[] generateCBC_MAC(byte[] data,
 T kd)
                       throws SMException

Description copied from interface: SMAdapter

Generates CBC-MAC (Cipher Block Chaining Message Authentication Code) for some data.

Specified by:

generateCBC_MAC in interface SMAdapter<T>

Parameters:

data - the data to be MACed

kd - the key used for MACing

Returns:

the MAC

Throws:

SMException

generateEDE_MAC

public byte[] generateEDE_MAC(byte[] data,
 T kd)
                       throws SMException

Description copied from interface: SMAdapter

Generates EDE-MAC (Encrypt Decrypt Encrypt Message Message Authentication Code) for some data.

Specified by:

generateEDE_MAC in interface SMAdapter<T>

Parameters:

data - the data to be MACed

kd - the key used for MACing

Returns:

the MAC

Throws:

SMException

translateKeyFromOldLMK

public SecureDESKey translateKeyFromOldLMK(SecureDESKey kd)
                                    throws SMException

Description copied from interface: SMAdapter

Translate key from encryption under the LMK held in key change storage to encryption under a new LMK.

Specified by:

translateKeyFromOldLMK in interface SMAdapter<T>

Parameters:

kd - the key encrypted under old LMK

Returns:

key encrypted under the new LMK

Throws:

SMException

translateKeyFromOldLMK

public SecureKey translateKeyFromOldLMK(SecureKey key,
 SecureKeySpec keySpec)
                                 throws SMException

Description copied from interface: SMAdapter

Translate key from encryption under the LMK held in key change storage to encryption under a new LMK.

Specified by:

translateKeyFromOldLMK in interface SMAdapter<T>

Parameters:

key - the key encrypted under old LMK

keySpec - the specification of the key to be translated. It allows passing new key block attributes.

Returns:

key encrypted under the new LMK

Throws:

SMException

generateKeyPair

public org.javatuples.Pair<PublicKey, SecurePrivateKey> generateKeyPair(AlgorithmParameterSpec spec)
                                                                 throws SMException

Description copied from interface: SMAdapter

Generate a public/private key pair.

Specified by:

generateKeyPair in interface SMAdapter<T>

Parameters:

spec - algorithm specific parameters, e.g. algorithm, key size, public key exponent.

Returns:

key pair generated according to passed parameters

Throws:

SMException

generateKeyPair

public org.javatuples.Pair<PublicKey, SecureKey> generateKeyPair(SecureKeySpec keySpec)
                                                          throws SMException

Description copied from interface: SMAdapter

Generate a public/private key pair.

Specified by:

generateKeyPair in interface SMAdapter<T>

Parameters:

keySpec - the specification of the key to be generated. It allows passing key algorithm type, size and key block attributes. NOTE: For pass an extra key usage of the RSA key, possible is use e.g. keySpec.setVariant() or keySpec.setReserved()

Returns:

key pair generated according to passed parameters

Throws:

SMException

calculateSignature

public byte[] calculateSignature(MessageDigest hash,
 SecureKey privateKey,
 byte[] data)
                          throws SMException

Description copied from interface: SMAdapter

Calculate signature of Data Block.

Specified by:

calculateSignature in interface SMAdapter<T>

Parameters:

hash - identifier of the hash algorithm used to hash passed data.

privateKey - private key used to compute data signature.

data - data to be signed.

Returns:

signature of passed data.

Throws:

SMException

encryptData

public byte[] encryptData(SecureKey encKey,
 byte[] data,
 AlgorithmParameterSpec algspec,
 byte[] iv)
                   throws SMException

Description copied from interface: SMAdapter

Encrypts clear Data Block with specified cipher.

NOTE: This is a more general version of the SMAdapter.encryptData(CipherMode, SecureDESKey, byte[], byte[])

Specified by:

encryptData in interface SMAdapter<T>

Parameters:

encKey - the data encryption key e.g:

• when RSA public key encapsulated in SecurePrivateKey
• when DES/TDES DEK SecureDESKey

data - clear data block to encrypt

algspec - algorithm specification or null if not required. Used to pass additional algorithm parameters e.g: OAEPParameterSpec or custom extension of AlgorithmParameterSpec to pass symetric cipher mode ECB, CBC

iv - the inital vector or null if not used (e.g: RSA cipher or ECB mode). If used, after operation will contain new iv value.

Returns:

encrypted data block

Throws:

SMException

decryptData

public byte[] decryptData(SecureKey privKey,
 byte[] data,
 AlgorithmParameterSpec algspec,
 byte[] iv)
                   throws SMException

Description copied from interface: SMAdapter

Decrypts encrypted Data Block with specified cipher.

NOTE: This is a more general version of the SMAdapter.decryptData(CipherMode, SecureDESKey, byte[], byte[])

Specified by:

decryptData in interface SMAdapter<T>

Parameters:

privKey - the data decryption key e.g:

• when RSA private key encapsulated in SecurePrivateKey
• when DES/TDES DEK SecureDESKey

data - encrypted data block to decrypt

algspec - algorithm specification or null if not required. Used to pass additional algorithm parameters e.g: OAEPParameterSpec or custom extension of AlgorithmParameterSpec to pass symetric cipher mode ECB, CBC

iv - the inital vector or null if not used (e.g: RSA cipher or ECB mode). If used, after operation will contain new iv value.

Returns:

decrypted data block

Throws:

SMException

eraseOldLMK

public void eraseOldLMK()
                 throws SMException

Description copied from interface: SMAdapter

Erase the key change storage area of memory It is recommended that this command is used after keys stored by the Host have been translated from old to new LMKs.

Specified by:

eraseOldLMK in interface SMAdapter<T>

Throws:

SMException

generateKeyImpl

protected SecureDESKey generateKeyImpl(short keyLength,
 String keyType)
                                throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

keyLength -

keyType -

Returns:

generated key

Throws:

SMException

generateKeyImpl

protected SecureKey generateKeyImpl(SecureKeySpec keySpec)
                             throws SMException

Your SMAdapter should override this method if it has this functionality.

Parameters:

keySpec -

Returns:

generated key

Throws:

SMException

generateKeyCheckValueImpl

protected byte[] generateKeyCheckValueImpl(T kd)
                                    throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

kd -

Returns:

generated Key Check Value

Throws:

SMException

translateKeySchemeImpl

protected SecureDESKey translateKeySchemeImpl(SecureDESKey key,
 KeyScheme destKeyScheme)
                                       throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

key -

destKeyScheme -

Returns:

translated key with destKeyScheme scheme

Throws:

SMException

importKeyImpl

protected SecureDESKey importKeyImpl(short keyLength,
 String keyType,
 byte[] encryptedKey,
 SecureDESKey kek,
 boolean checkParity)
                              throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

keyLength -

keyType -

encryptedKey -

kek -

checkParity -

Returns:

imported key

Throws:

SMException

importKeyImpl

protected SecureKey importKeyImpl(SecureKey kek,
 SecureKey key,
 SecureKeySpec keySpec,
 boolean checkParity)
                           throws SMException

Your SMAdapter should override this method if it has this functionality.

Parameters:

kek -

key -

keySpec -

checkParity -

Returns:

imported key

Throws:

SMException

exportKeyImpl

protected byte[] exportKeyImpl(SecureDESKey key,
 SecureDESKey kek)
                        throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

key -

kek -

Returns:

exported key

Throws:

SMException

exportKeyImpl

protected SecureKey exportKeyImpl(SecureKey kek,
 SecureKey key,
 SecureKeySpec keySpec)
                           throws SMException

Your SMAdapter should override this method if it has this functionality.

Parameters:

kek -

key -

keySpec -

Returns:

exported key

Throws:

SMException

encryptPINImpl

protected EncryptedPIN encryptPINImpl(String pin,
 String accountNumber)
                               throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pin -

accountNumber -

Returns:

encrypted PIN under LMK

Throws:

SMException

encryptPINImpl

protected EncryptedPIN encryptPINImpl(String pin,
 String accountNumber,
 T pek)
                               throws SMException

Your SMAdapter should override this method if it has this functionality.

Parameters:

pin -

accountNumber -

pek -

Returns:

encrypted PIN under PEK.

Throws:

SMException

decryptPINImpl

protected String decryptPINImpl(EncryptedPIN pinUnderLmk)
                         throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderLmk -

Returns:

clear pin as entered by card holder

Throws:

SMException

importPINImpl

protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderKd1,
 T kd1)
                              throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderKd1 -

kd1 -

Returns:

imported pin

Throws:

SMException

translatePINImpl

protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderKd1,
 T kd1,
 T kd2,
 byte destinationPINBlockFormat)
                                 throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderKd1 -

kd1 -

kd2 -

destinationPINBlockFormat -

Returns:

translated pin

Throws:

SMException

importPINImpl

@Deprecated
protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderDuk,
 KeySerialNumber ksn,
 T bdk)
                              throws SMException

Deprecated.

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderDuk -

ksn -

bdk -

Returns:

imported pin

Throws:

SMException

importPINImpl

protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderDuk,
 KeySerialNumber ksn,
 T bdk,
 boolean tdes)
                              throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderDuk -

ksn -

bdk -

tdes -

Returns:

imported pin

Throws:

SMException

translatePINImpl

@Deprecated
protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderDuk,
 KeySerialNumber ksn,
 T bdk,
 T kd2,
 byte destinationPINBlockFormat)
                                 throws SMException

Deprecated.

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderDuk -

ksn -

bdk -

kd2 -

destinationPINBlockFormat -

Returns:

translated pin

Throws:

SMException

translatePINImpl

protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderDuk,
 KeySerialNumber ksn,
 T bdk,
 T kd2,
 byte destinationPINBlockFormat,
 boolean tdes)
                                 throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderDuk -

ksn -

bdk -

kd2 -

destinationPINBlockFormat -

tdes -

Returns:

translated pin

Throws:

SMException

exportPINImpl

protected EncryptedPIN exportPINImpl(EncryptedPIN pinUnderLmk,
 T kd2,
 byte destinationPINBlockFormat)
                              throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderLmk -

kd2 -

destinationPINBlockFormat -

Returns:

exported pin

Throws:

SMException

generatePINImpl

protected EncryptedPIN generatePINImpl(String accountNumber,
 int pinLen,
 List<String> excludes)
                                throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

accountNumber -

pinLen -

excludes -

Returns:

generated PIN under LMK

Throws:

SMException

printPINImpl

protected void printPINImpl(String accountNo,
 EncryptedPIN pinUnderKd1,
 T kd1,
 String template,
 Map<String,String> fields)
                     throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

accountNo -

pinUnderKd1 -

kd1 -

template -

fields -

Throws:

SMException

calculatePVVImpl

protected String calculatePVVImpl(EncryptedPIN pinUnderLMK,
 T pvkA,
 T pvkB,
 int pvkIdx,
 List<String> excludes)
                           throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderLMK -

pvkA -

pvkB -

pvkIdx -

excludes -

Returns:

PVV (VISA PIN Verification Value)

Throws:

SMException

calculatePVVImpl

protected String calculatePVVImpl(EncryptedPIN pinUnderKd1,
 T kd1,
 T pvkA,
 T pvkB,
 int pvkIdx,
 List<String> excludes)
                           throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderKd1 -

kd1 -

pvkA -

pvkB -

pvkIdx -

excludes -

Returns:

PVV (VISA PIN Verification Value)

Throws:

SMException

verifyPVVImpl

protected boolean verifyPVVImpl(EncryptedPIN pinUnderKd,
 T kd,
 T pvkA,
 T pvkB,
 int pvki,
 String pvv)
                         throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderKd -

kd -

pvkA -

pvkB -

pvki -

pvv -

Returns:

true if pin is valid false if not

Throws:

SMException

calculateIBMPINOffsetImpl

protected String calculateIBMPINOffsetImpl(EncryptedPIN pinUnderLmk,
 T pvk,
 String decTab,
 String pinValData,
 int minPinLen,
 List<String> excludes)
                                    throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderLmk -

pvk -

decTab -

pinValData -

minPinLen -

excludes -

Returns:

IBM PIN Offset

Throws:

SMException

calculateIBMPINOffsetImpl

protected String calculateIBMPINOffsetImpl(EncryptedPIN pinUnderKd1,
 T kd1,
 T pvk,
 String decTab,
 String pinValData,
 int minPinLen,
 List<String> excludes)
                                    throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderKd1 -

kd1 -

pvk -

decTab -

pinValData -

minPinLen -

excludes -

Returns:

IBM PIN Offset

Throws:

SMException

verifyIBMPINOffsetImpl

protected boolean verifyIBMPINOffsetImpl(EncryptedPIN pinUnderKd,
 T kd,
 T pvk,
 String offset,
 String decTab,
 String pinValData,
 int minPinLen)
                                  throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

pinUnderKd -

kd -

pvk -

offset -

decTab -

pinValData -

minPinLen -

Returns:

true if pin is valid false if not

Throws:

SMException

deriveIBMPINImpl

protected EncryptedPIN deriveIBMPINImpl(String accountNo,
 T pvk,
 String decTab,
 String pinValData,
 int minPinLen,
 String offset)
                                 throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

accountNo -

pvk -

decTab -

pinValData -

minPinLen -

offset -

Returns:

derived PIN under LMK

Throws:

SMException

calculateCVVImpl

protected String calculateCVVImpl(String accountNo,
 T cvkA,
 T cvkB,
 Date expDate,
 String serviceCode)
                           throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

accountNo -

cvkA -

cvkB -

expDate -

serviceCode -

Returns:

Card Verification Code/Value

Throws:

SMException

calculateCVDImpl

protected String calculateCVDImpl(String accountNo,
 T cvkA,
 T cvkB,
 String expDate,
 String serviceCode)
                           throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

accountNo -

cvkA -

cvkB -

expDate -

serviceCode -

Returns:

Card Verification Digit (Code/Value)

Throws:

SMException

calculateCAVVImpl

protected String calculateCAVVImpl(String accountNo,
 T cvk,
 String upn,
 String authrc,
 String sfarc)
                            throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

accountNo -

cvk -

upn -

authrc -

sfarc -

Returns:

Cardholder Authentication Verification Value

Throws:

SMException

verifyCVVImpl

protected boolean verifyCVVImpl(String accountNo,
 T cvkA,
 T cvkB,
 String cvv,
 Date expDate,
 String serviceCode)
                         throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

accountNo -

cvkA -

cvkB -

cvv -

expDate -

serviceCode -

Returns:

true if CVV/CVC is falid or false if not

Throws:

SMException

verifyCVVImpl

protected boolean verifyCVVImpl(String accountNo,
 T cvkA,
 T cvkB,
 String cvv,
 String expDate,
 String serviceCode)
                         throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

accountNo -

cvkA -

cvkB -

cvv -

expDate -

serviceCode -

Returns:

true if CVV/CVC is valid or false otherwise

Throws:

SMException

verifyCAVVImpl

protected boolean verifyCAVVImpl(String accountNo,
 T cvk,
 String cavv,
 String upn,
 String authrc,
 String sfarc)
                          throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

accountNo -

cvk -

cavv -

upn -

authrc -

sfarc -

Returns:

Cardholder Authentication Verification Value

Throws:

SMException

verifydCVVImpl

protected boolean verifydCVVImpl(String accountNo,
 T imkac,
 String dcvv,
 Date expDate,
 String serviceCode,
 byte[] atc,
 MKDMethod mkdm)
                          throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

accountNo -

imkac -

dcvv -

expDate -

serviceCode -

atc -

mkdm -

Returns:

true if dcvv is valid false if not

Throws:

SMException

verifydCVVImpl

protected boolean verifydCVVImpl(String accountNo,
 T imkac,
 String dcvv,
 String expDate,
 String serviceCode,
 byte[] atc,
 MKDMethod mkdm)
                          throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

accountNo -

imkac -

dcvv -

expDate -

serviceCode -

atc -

mkdm -

Returns:

true if dcvv is valid false if not

Throws:

SMException

verifyCVC3Impl

protected boolean verifyCVC3Impl(T imkcvc3,
 String accountNo,
 String acctSeqNo,
 byte[] atc,
 byte[] upn,
 byte[] data,
 MKDMethod mkdm,
 String cvc3)
                          throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

imkcvc3 -

accountNo -

acctSeqNo -

atc -

upn -

data -

mkdm -

cvc3 -

Returns:

true if cvc3 is valid false if not

Throws:

SMException

verifyARQCImpl

protected boolean verifyARQCImpl(MKDMethod mkdm,
 SKDMethod skdm,
 T imkac,
 String accountNo,
 String acctSeqNo,
 byte[] arqc,
 byte[] atc,
 byte[] upn,
 byte[] txnData)
                          throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

mkdm -

skdm -

imkac -

accountNo -

acctSeqNo -

arqc -

atc -

upn -

txnData -

Returns:

true if ARQC/TC/AAC is valid or false if not

Throws:

SMException

generateARPCImpl

protected byte[] generateARPCImpl(MKDMethod mkdm,
 SKDMethod skdm,
 T imkac,
 String accountNo,
 String acctSeqNo,
 byte[] arqc,
 byte[] atc,
 byte[] upn,
 ARPCMethod arpcMethod,
 byte[] arc,
 byte[] propAuthData)
                           throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

mkdm -

skdm -

imkac -

accountNo -

acctSeqNo -

arqc -

atc -

upn -

arpcMethod -

arc -

propAuthData -

Returns:

calculated ARPC

Throws:

SMException

verifyARQCGenerateARPCImpl

protected byte[] verifyARQCGenerateARPCImpl(MKDMethod mkdm,
 SKDMethod skdm,
 T imkac,
 String accountNo,
 String acctSeqNo,
 byte[] arqc,
 byte[] atc,
 byte[] upn,
 byte[] transData,
 ARPCMethod arpcMethod,
 byte[] arc,
 byte[] propAuthData)
                                     throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

mkdm -

skdm -

imkac -

accountNo -

acctSeqNo -

arqc -

atc -

upn -

transData -

arpcMethod -

arc -

propAuthData -

Returns:

calculated ARPC

Throws:

SMException

generateSM_MACImpl

protected byte[] generateSM_MACImpl(MKDMethod mkdm,
 SKDMethod skdm,
 T imksmi,
 String accountNo,
 String acctSeqNo,
 byte[] atc,
 byte[] arqc,
 byte[] data)
                             throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

mkdm -

skdm -

imksmi -

accountNo -

acctSeqNo -

atc -

arqc -

data -

Returns:

generated 8 bytes MAC

Throws:

SMException

translatePINGenerateSM_MACImpl

protected org.javatuples.Pair<EncryptedPIN, byte[]> translatePINGenerateSM_MACImpl(MKDMethod mkdm,
 SKDMethod skdm,
 PaddingMethod padm,
 T imksmi,
 String accountNo,
 String acctSeqNo,
 byte[] atc,
 byte[] arqc,
 byte[] data,
 EncryptedPIN currentPIN,
 EncryptedPIN newPIN,
 T kd1,
 T imksmc,
 T imkac,
 byte destinationPINBlockFormat)
                                                                            throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

mkdm -

skdm -

padm -

imksmi -

accountNo -

acctSeqNo -

atc -

arqc -

data -

currentPIN -

newPIN -

kd1 -

imksmc -

imkac -

destinationPINBlockFormat -

Returns:

Pair of values, encrypted PIN and 8 bytes MAC

Throws:

SMException

encryptDataImpl

protected byte[] encryptDataImpl(CipherMode cipherMode,
 SecureDESKey kd,
 byte[] data,
 byte[] iv)
                          throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

cipherMode -

kd -

data -

iv -

Returns:

encrypted data

Throws:

SMException

decryptDataImpl

protected byte[] decryptDataImpl(CipherMode cipherMode,
 SecureDESKey kd,
 byte[] data,
 byte[] iv)
                          throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

cipherMode -

kd -

data -

iv -

Returns:

decrypted data

Throws:

SMException

generateCBC_MACImpl

protected byte[] generateCBC_MACImpl(byte[] data,
 T kd)
                              throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

data -

kd -

Returns:

generated CBC-MAC

Throws:

SMException

generateEDE_MACImpl

protected byte[] generateEDE_MACImpl(byte[] data,
 T kd)
                              throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

data -

kd -

Returns:

generated EDE-MAC

Throws:

SMException

translateKeyFromOldLMKImpl

protected SecureDESKey translateKeyFromOldLMKImpl(SecureDESKey kd)
                                           throws SMException

Translate key from encryption under the LMK held in key change storage to encryption under a new LMK.

Parameters:

kd - the key encrypted under old LMK

Returns:

key encrypted under the new LMK

Throws:

SMException - if the parity of the imported key is not adjusted AND checkParity = true

translateKeyFromOldLMKImpl

protected SecureKey translateKeyFromOldLMKImpl(SecureKey key,
 SecureKeySpec keySpec)
                                        throws SMException

Your SMAdapter should override this method if it has this functionality.

Parameters:

key -

keySpec -

Returns:

key encrypted under the new LMK

Throws:

SMException - if the parity of the imported key is not adjusted AND checkParity = true

generateKeyPairImpl

protected org.javatuples.Pair<PublicKey, SecurePrivateKey> generateKeyPairImpl(AlgorithmParameterSpec spec)
                                                                        throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

spec - algorithm specific parameters (contains e.g. key size)

Returns:

key pair generated according to passed parameters

Throws:

SMException

generateKeyPairImpl

protected org.javatuples.Pair<PublicKey, SecureKey> generateKeyPairImpl(SecureKeySpec keySpec)
                                                                 throws SMException

Your SMAdapter should override this method if it has this functionality.

Parameters:

keySpec -

Returns:

key pair generated according to passed parameters

Throws:

SMException

calculateSignatureImpl

protected byte[] calculateSignatureImpl(MessageDigest hash,
 SecureKey privateKey,
 byte[] data)
                                 throws SMException

Your SMAdapter should override this method if it has this functionality

Parameters:

hash - identifier of the hash algorithm used to hash passed data.

privateKey - private key used to compute data signature.

data - data to be sifned.

Returns:

signature of passed data.

Throws:

SMException

encryptDataImpl

protected byte[] encryptDataImpl(SecureKey encKey,
 byte[] data,
 AlgorithmParameterSpec algspec,
 byte[] iv)
                          throws SMException

Encrypts clear Data Block with specified cipher.

Parameters:

encKey - the data encryption key

data - data block to encrypt

algspec - algorithm specification

iv - the inital vector

Returns:

encrypted data block

Throws:

SMException

decryptDataImpl

protected byte[] decryptDataImpl(SecureKey decKey,
 byte[] data,
 AlgorithmParameterSpec algspec,
 byte[] iv)
                          throws SMException

Decrypts Data Block encrypted with assymetric cipher.

Parameters:

decKey - the data decryption key

data - data block to decrypt

algspec - algorithm specification

iv - the inital vector

Returns:

decrypted data block

Throws:

SMException

eraseOldLMKImpl

protected void eraseOldLMKImpl()
                        throws SMException

Erase the key change storage area of memory It is recommended that this command is used after keys stored by the Host have been translated from old to new LMKs.

Throws:

SMException

dataEncrypt

public byte[] dataEncrypt(T bdk,
 byte[] clearText)
                   throws SMException

Description copied from interface: SMAdapter

Encrypt Data

Specified by:

dataEncrypt in interface SMAdapter<T>

Parameters:

bdk - base derivation key

clearText - clear Text

Returns:

cyphertext

Throws:

SMException

dataDecrypt

public byte[] dataDecrypt(T bdk,
 byte[] clearText)
                   throws SMException

Description copied from interface: SMAdapter

Decrypt Data

Specified by:

dataDecrypt in interface SMAdapter<T>

Parameters:

bdk - base derivation key

clearText - clear Text

Returns:

cleartext

Throws:

SMException

formKEYfromClearComponents

public SecureDESKey formKEYfromClearComponents(short keyLength,
 String keyType,
 String... clearComponents)
                                        throws SMException

Description copied from interface: SMAdapter

Forms a key from 3 clear components and returns it encrypted under its corresponding LMK The corresponding LMK is determined from the keyType

Specified by:

formKEYfromClearComponents in interface SMAdapter<T>

Parameters:

keyLength - e.g. LENGTH_DES, LENGTH_DES3_2, LENGTH_DES3_3, ..

keyType - possible values are those defined in the SecurityModule inteface. e.g., ZMK, TMK,...

clearComponents - up to three HexStrings containing key components

Returns:

forms an SecureDESKey from two clear components

Throws:

SMException