org.jpos.security.jceadapter

Class JCESecurityModule

java.lang.Object

org.jpos.security.BaseSMAdapter<SecureDESKey>

org.jpos.security.jceadapter.JCESecurityModule

All Implemented Interfaces:

Configurable, SMAdapter<SecureDESKey>, LogSource

public class JCESecurityModule
extends BaseSMAdapter<SecureDESKey>

JCESecurityModule is an implementation of a security module in software.

It doesn't require any hardware device to work.
JCESecurityModule also implements the SMAdapter, so you can view it: either as a self contained security module adapter that doesn't need a security module or a security module that plugs directly to jpos, so doesn't need a separate adapter.
It relies on Java(tm) Cryptography Extension (JCE), hence its name.
JCESecurityModule relies on the JCEHandler class to do the low level JCE work.

WARNING: This version of JCESecurityModule is meant for testing purposes and NOT for life operation, since the Local Master Keys are stored in CLEAR on the system's disk. Comming versions of JCESecurity Module will rely on java.security.KeyStore for a better protection of the Local Master Keys.

Field Summary

Fields

Modifier and Type	Field and Description
protected JCEHandler	jceHandler

Fields inherited from class org.jpos.security.BaseSMAdapter

cfg, logger, realm

Fields inherited from interface org.jpos.security.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 and Description
JCESecurityModule() Creates an uninitialized JCE Security Module, you need to setConfiguration to initialize it
JCESecurityModule(Configuration cfg, Logger logger, java.lang.String realm)
JCESecurityModule(java.lang.String lmkFile)
JCESecurityModule(java.lang.String lmkFile, java.lang.String jceProviderClassName)

Method Summary

Modifier and Type	Method and Description
protected byte[]	calculateARPC(java.security.Key skarpc, byte[] arqc, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData) Calculate ARPC.
protected byte[]	calculateARQC(MKDMethod mkdm, SKDMethod skdm, SecureDESKey imkac, java.lang.String accountNo, java.lang.String accntSeqNo, byte[] atc, byte[] upn, byte[] transData) Calculate ARQC.
protected java.lang.String	calculateCAVVImpl(java.lang.String accountNo, SecureDESKey cvk, java.lang.String upn, java.lang.String authrc, java.lang.String sfarc) Your SMAdapter should override this method if it has this functionality
protected java.lang.String	calculateCVC3(SecureDESKey imkcvc3, java.lang.String accountNo, java.lang.String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm)
protected java.lang.String	calculateCVD(java.lang.String accountNo, java.security.Key cvk, java.lang.String expDate, java.lang.String serviceCode)
protected java.lang.String	calculateCVDImpl(java.lang.String accountNo, SecureDESKey cvkA, SecureDESKey cvkB, java.lang.String expDate, java.lang.String serviceCode) Your SMAdapter should override this method if it has this functionality
protected java.lang.String	calculateCVV(java.lang.String accountNo, java.security.Key cvk, java.util.Date expDate, java.lang.String serviceCode)
protected java.lang.String	calculateCVVImpl(java.lang.String accountNo, SecureDESKey cvkA, SecureDESKey cvkB, java.util.Date expDate, java.lang.String serviceCode) Your SMAdapter should override this method if it has this functionality
protected java.lang.String	calculatedCVV(java.lang.String accountNo, SecureDESKey imkac, java.lang.String expDate, java.lang.String serviceCode, byte[] atc, MKDMethod mkdm)
protected byte[]	calculateDerivedKey(KeySerialNumber ksn, SecureDESKey bdk, boolean tdes, boolean dataEncryption)
protected byte[]	calculateKeyCheckValue(java.security.Key key) Calculates a key check value over a clear key
protected java.lang.String	calculatePIN(byte[] pinBlock, byte pinBlockFormat, java.lang.String accountNumber) Calculates the clear pin (as entered by card holder on the pin entry device) givin the clear PIN block
protected byte[]	calculatePINBlock(java.lang.String pin, byte pinBlockFormat, java.lang.String accountNumber) Calculates the clear PIN Block
protected java.lang.String	calculatePVV(EncryptedPIN pinUnderLmk, java.security.Key key, int keyIdx, java.util.List<java.lang.String> excludes)
protected java.lang.String	calculatePVVImpl(EncryptedPIN pinUnderLmk, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx, java.util.List<java.lang.String> excludes) Your SMAdapter should override this method if it has this functionality
protected java.lang.String	calculatePVVImpl(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx, java.util.List<java.lang.String> excludes) Your SMAdapter should override this method if it has this functionality
protected void	checkCAVVArgs(java.lang.String upn, java.lang.String authrc, java.lang.String sfarc)
protected java.security.Key	concatKeys(SecureDESKey keyA, SecureDESKey keyB)
byte[]	dataDecrypt(SecureDESKey bdk, byte[] cypherText) Decrypt Data
byte[]	dataEncrypt(SecureDESKey bdk, byte[] clearText) Encrypt Data
byte[]	decryptDataImpl(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv) Your SMAdapter should override this method if it has this functionality
protected java.security.Key	decryptFromLMK(SecureDESKey secureDESKey) Decrypts a secure DES key from encryption under LMK
java.lang.String	decryptPINImpl(EncryptedPIN pinUnderLmk) Your SMAdapter should override this method if it has this functionality
protected java.security.Key	deriveICCMasterKey(java.security.Key imk, byte[] panpsn) Derive ICC Master Key from Issuer Master Key and preformated PAN/PANSeqNo Compute two 8-byte numbers: left part is a result of Tripple-DES encription panpsn with imk as the key right part is a result of Tripple-DES binary inverted panpsn with imk as the key concatenate left and right parts Described in EMV v4.2 Book 2, Annex A1.4.1 Master Key Derivation point 2
byte[]	encryptDataImpl(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv) Your SMAdapter should override this method if it has this functionality
EncryptedPIN	encryptPINImpl(java.lang.String pin, java.lang.String accountNumber) Your SMAdapter should override this method if it has this functionality
protected EncryptedPIN	encryptPINImpl(java.lang.String pin, java.lang.String accountNumber, SecureDESKey pek) Your SMAdapter should override this method if it has this functionality.
protected SecureDESKey	encryptToLMK(short keyLength, java.lang.String keyType, java.security.Key clearDESKey) Encrypts a clear DES Key under LMK to form a SecureKey
byte[]	exportKeyImpl(SecureDESKey key, SecureDESKey kek) Your SMAdapter should override this method if it has this functionality
EncryptedPIN	exportPIN(EncryptedPIN pinUnderLmk, KeySerialNumber ksn, SecureDESKey bdk, boolean tdes, byte destinationPINBlockFormat) Exports PIN to DUKPT Encryption.
EncryptedPIN	exportPINImpl(EncryptedPIN pinUnderLmk, SecureDESKey kd2, byte destinationPINBlockFormat) Your SMAdapter should override this method if it has this functionality
SecureDESKey	formKEYfromClearComponents(short keyLength, java.lang.String keyType, java.lang.String... components) Forms a key from 3 clear components and returns it encrypted under its corresponding LMK The corresponding LMK is determined from the keyType
SecureDESKey	formKEYfromThreeClearComponents(short keyLength, java.lang.String keyType, java.lang.String clearComponent1HexString, java.lang.String clearComponent2HexString, java.lang.String clearComponent3HexString) Forms a key from 3 clear components and returns it encrypted under its corresponding LMK The corresponding LMK is determined from the keyType
byte[]	generateARPCImpl(MKDMethod mkdm, SKDMethod skdm, SecureDESKey imkac, java.lang.String accountNo, java.lang.String accntSeqNo, byte[] arqc, byte[] atc, byte[] upn, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData) Your SMAdapter should override this method if it has this functionality
protected byte[]	generateCBC_MACImpl(byte[] data, SecureDESKey kd) Generates CBC-MAC (Cipher Block Chaining Message Authentication Code) for some data.
java.lang.String	generateClearKeyComponent(short keyLength) Generates a random clear key component.
protected byte[]	generateEDE_MACImpl(byte[] data, SecureDESKey kd) Generates EDE-MAC (Encrypt Decrypt Encrypt Message Authentication Code) for some data.
protected byte[]	generateKeyCheckValueImpl(SecureDESKey secureDESKey) Generates key check value.
SecureDESKey	generateKeyImpl(short keyLength, java.lang.String keyType) Your SMAdapter should override this method if it has this functionality
EncryptedPIN	generatePINImpl(java.lang.String accountNumber, int pinLen, java.util.List<java.lang.String> excludes) Your SMAdapter should override this method if it has this functionality
protected byte[]	generateSM_MACImpl(MKDMethod mkdm, SKDMethod skdm, SecureDESKey imksmi, java.lang.String accountNo, java.lang.String accntSeqNo, byte[] atc, byte[] arqc, byte[] data) Your SMAdapter should override this method if it has this functionality
SecureDESKey	importBDK(java.lang.String clearComponent1HexString, java.lang.String clearComponent2HexString, java.lang.String clearComponent3HexString)
SecureDESKey	importKeyImpl(short keyLength, java.lang.String keyType, byte[] encryptedKey, SecureDESKey kek, boolean checkParity) Your SMAdapter should override this method if it has this functionality
protected EncryptedPIN	importPINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, SecureDESKey bdk, boolean tdes) Your SMAdapter should override this method if it has this functionality
EncryptedPIN	importPINImpl(EncryptedPIN pinUnderKd1, SecureDESKey kd1) Your SMAdapter should override this method if it has this functionality
void	setConfiguration(Configuration cfg) Configures a JCESecurityModule
protected byte[]	specialDecrypt(byte[] data, byte[] key)
protected byte[]	specialEncrypt(byte[] data, byte[] key)
SecureDESKey	translateKeySchemeImpl(SecureDESKey key, KeyScheme keyScheme) Your SMAdapter should override this method if it has this functionality
protected org.javatuples.Pair<EncryptedPIN,byte[]>	translatePINGenerateSM_MACImpl(MKDMethod mkdm, SKDMethod skdm, PaddingMethod padm, SecureDESKey imksmi, java.lang.String accountNo, java.lang.String accntSeqNo, byte[] atc, byte[] arqc, byte[] data, EncryptedPIN currentPIN, EncryptedPIN newPIN, SecureDESKey kd1, SecureDESKey imksmc, SecureDESKey imkac, byte destinationPINBlockFormat) Your SMAdapter should override this method if it has this functionality
protected EncryptedPIN	translatePINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, SecureDESKey bdk, SecureDESKey kd2, byte destinationPINBlockFormat, boolean tdes) Your SMAdapter should override this method if it has this functionality
EncryptedPIN	translatePINImpl(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey kd2, byte destinationPINBlockFormat) Your SMAdapter should override this method if it has this functionality
byte[]	verifyARQCGenerateARPCImpl(MKDMethod mkdm, SKDMethod skdm, SecureDESKey imkac, java.lang.String accountNo, java.lang.String accntSeqNo, 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, SecureDESKey imkac, java.lang.String accountNo, java.lang.String accntSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] transData) Your SMAdapter should override this method if it has this functionality
protected boolean	verifyCAVVImpl(java.lang.String accountNo, SecureDESKey cvk, java.lang.String cavv, java.lang.String upn, java.lang.String authrc, java.lang.String sfarc) Your SMAdapter should override this method if it has this functionality
protected boolean	verifyCVC3Impl(SecureDESKey imkcvc3, java.lang.String accountNo, java.lang.String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm, java.lang.String cvc3) Your SMAdapter should override this method if it has this functionality
protected boolean	verifyCVVImpl(java.lang.String accountNo, SecureDESKey cvkA, SecureDESKey cvkB, java.lang.String cvv, java.util.Date expDate, java.lang.String serviceCode) Your SMAdapter should override this method if it has this functionality
protected boolean	verifyCVVImpl(java.lang.String accountNo, SecureDESKey cvkA, SecureDESKey cvkB, java.lang.String cvv, java.lang.String expDate, java.lang.String serviceCode) Your SMAdapter should override this method if it has this functionality
protected boolean	verifydCVVImpl(java.lang.String accountNo, SecureDESKey imkac, java.lang.String dcvv, java.util.Date expDate, java.lang.String serviceCode, byte[] atc, MKDMethod mkdm) Your SMAdapter should override this method if it has this functionality
protected boolean	verifydCVVImpl(java.lang.String accountNo, SecureDESKey imkac, java.lang.String dcvv, java.lang.String expDate, java.lang.String serviceCode, byte[] atc, MKDMethod mkdm) Your SMAdapter should override this method if it has this functionality
boolean	verifyPVVImpl(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvkA, SecureDESKey pvkB, int pvki, java.lang.String pvv) Your SMAdapter should override this method if it has this functionality

Methods inherited from class org.jpos.security.BaseSMAdapter

calculateCAVV, calculateCVD, calculateCVV, calculateIBMPINOffset, calculateIBMPINOffset, calculateIBMPINOffset, calculateIBMPINOffset, calculateIBMPINOffsetImpl, calculateIBMPINOffsetImpl, calculatePVV, calculatePVV, calculatePVV, calculatePVV, calculateSignature, calculateSignatureImpl, decryptData, decryptData, decryptDataImpl, decryptPIN, deriveIBMPIN, deriveIBMPINImpl, encryptData, encryptData, encryptDataImpl, encryptPIN, encryptPIN, encryptPIN, eraseOldLMK, eraseOldLMKImpl, exportKey, exportKey, exportKeyImpl, exportPIN, generateARPC, generateCBC_MAC, generateEDE_MAC, generateKey, generateKey, generateKeyCheckValue, generateKeyImpl, generateKeyPair, generateKeyPair, generateKeyPairImpl, generateKeyPairImpl, generatePIN, generatePIN, generateSM_MAC, getLogger, getName, getRealm, getSMAdapter, importKey, importKey, importKeyImpl, importPIN, importPIN, importPIN, importPINImpl, printPIN, printPINImpl, setLogger, setName, translateKeyFromOldLMK, translateKeyFromOldLMK, translateKeyFromOldLMKImpl, translateKeyFromOldLMKImpl, translateKeyScheme, translatePIN, translatePIN, translatePIN, translatePINGenerateSM_MAC, translatePINImpl, verifyARQC, verifyARQCGenerateARPC, verifyCAVV, verifyCVC3, verifyCVD, verifyCVV, verifydCVV, verifydCVV, verifyIBMPINOffset, verifyIBMPINOffsetImpl, verifyPVV

Methods inherited from class java.lang.Object

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

Field Detail

jceHandler

protected JCEHandler jceHandler

Constructor Detail

JCESecurityModule

public JCESecurityModule()

Creates an uninitialized JCE Security Module, you need to setConfiguration to initialize it

JCESecurityModule

public JCESecurityModule(java.lang.String lmkFile)
                  throws SMException

Parameters:

lmkFile - Local Master Keys filename of the JCE Security Module

Throws:

SMException

JCESecurityModule

public JCESecurityModule(java.lang.String lmkFile,
                         java.lang.String jceProviderClassName)
                  throws SMException

Throws:

SMException

JCESecurityModule

public JCESecurityModule(Configuration cfg,
                         Logger logger,
                         java.lang.String realm)
                  throws ConfigurationException

Throws:

ConfigurationException

Method Detail

setConfiguration

public void setConfiguration(Configuration cfg)
                      throws ConfigurationException

Configures a JCESecurityModule

Specified by:

setConfiguration in interface Configurable

Overrides:

setConfiguration in class BaseSMAdapter<SecureDESKey>

Parameters:

cfg - The following properties are read:
lmk: Local Master Keys file (The only required parameter)
jce: JCE Provider Class Name, if not provided, it defaults to: com.sun.crypto.provider.SunJCE
rebuildlmk: (true/false), rebuilds the Local Master Keys file with new keys (WARNING: old keys will be erased)
cbc-mac: Cipher Block Chaining MAC algorithm name for given JCE Provider.
Default is ISO9797ALG3MACWITHISO7816-4PADDING from BouncyCastle provider (known as Retail-MAC)
that is suitable for most of interfaces with double length MAC key
ANSI X9.19 aka ISO/IEC 9797-1 MAC algorithm 3 padding method 2 - ISO7816
ede-mac: Encrypt Decrypt Encrypt MAC algorithm name for given JCE Provider.
Default is DESEDEMAC from BouncyCastle provider
that is suitable for BASE24 with double length MAC key
ANSI X9.19

Throws:

ConfigurationException

generateKeyImpl

public SecureDESKey generateKeyImpl(short keyLength,
                                    java.lang.String keyType)
                             throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

generateKeyImpl in class BaseSMAdapter<SecureDESKey>

Returns:

generated key

Throws:

SMException

importKeyImpl

public SecureDESKey importKeyImpl(short keyLength,
                                  java.lang.String keyType,
                                  byte[] encryptedKey,
                                  SecureDESKey kek,
                                  boolean checkParity)
                           throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

importKeyImpl in class BaseSMAdapter<SecureDESKey>

Returns:

imported key

Throws:

SMException

exportKeyImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

exportKeyImpl in class BaseSMAdapter<SecureDESKey>

Returns:

exported key

Throws:

SMException

encryptPINImpl

public EncryptedPIN encryptPINImpl(java.lang.String pin,
                                   java.lang.String accountNumber)
                            throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

encryptPINImpl in class BaseSMAdapter<SecureDESKey>

Returns:

encrypted PIN under LMK

Throws:

SMException

encryptPINImpl

protected EncryptedPIN encryptPINImpl(java.lang.String pin,
                                      java.lang.String accountNumber,
                                      SecureDESKey pek)
                               throws SMException

Description copied from class: BaseSMAdapter

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

Overrides:

encryptPINImpl in class BaseSMAdapter<SecureDESKey>

Returns:

encrypted PIN under PEK.

Throws:

SMException

decryptPINImpl

public java.lang.String decryptPINImpl(EncryptedPIN pinUnderLmk)
                                throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

decryptPINImpl in class BaseSMAdapter<SecureDESKey>

Returns:

clear pin as entered by card holder

Throws:

SMException

importPINImpl

public EncryptedPIN importPINImpl(EncryptedPIN pinUnderKd1,
                                  SecureDESKey kd1)
                           throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

importPINImpl in class BaseSMAdapter<SecureDESKey>

Returns:

imported pin

Throws:

SMException

exportPINImpl

public EncryptedPIN exportPINImpl(EncryptedPIN pinUnderLmk,
                                  SecureDESKey kd2,
                                  byte destinationPINBlockFormat)
                           throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

exportPINImpl in class BaseSMAdapter<SecureDESKey>

Returns:

exported pin

Throws:

SMException

generatePINImpl

public EncryptedPIN generatePINImpl(java.lang.String accountNumber,
                                    int pinLen,
                                    java.util.List<java.lang.String> excludes)
                             throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

generatePINImpl in class BaseSMAdapter<SecureDESKey>

Returns:

generated PIN under LMK

Throws:

SMException

concatKeys

protected java.security.Key concatKeys(SecureDESKey keyA,
                                       SecureDESKey keyB)
                                throws SMException

Throws:

SMException

calculateCVV

protected java.lang.String calculateCVV(java.lang.String accountNo,
                                        java.security.Key cvk,
                                        java.util.Date expDate,
                                        java.lang.String serviceCode)
                                 throws SMException

Throws:

SMException

calculateCVD

protected java.lang.String calculateCVD(java.lang.String accountNo,
                                        java.security.Key cvk,
                                        java.lang.String expDate,
                                        java.lang.String serviceCode)
                                 throws SMException

Throws:

SMException

calculateCVVImpl

protected java.lang.String calculateCVVImpl(java.lang.String accountNo,
                                            SecureDESKey cvkA,
                                            SecureDESKey cvkB,
                                            java.util.Date expDate,
                                            java.lang.String serviceCode)
                                     throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

calculateCVVImpl in class BaseSMAdapter<SecureDESKey>

Returns:

Card Verification Code/Value

Throws:

SMException

calculateCVDImpl

protected java.lang.String calculateCVDImpl(java.lang.String accountNo,
                                            SecureDESKey cvkA,
                                            SecureDESKey cvkB,
                                            java.lang.String expDate,
                                            java.lang.String serviceCode)
                                     throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

calculateCVDImpl in class BaseSMAdapter<SecureDESKey>

Returns:

Card Verification Digit (Code/Value)

Throws:

SMException

checkCAVVArgs

protected void checkCAVVArgs(java.lang.String upn,
                             java.lang.String authrc,
                             java.lang.String sfarc)
                      throws SMException

Throws:

SMException

calculateCAVVImpl

protected java.lang.String calculateCAVVImpl(java.lang.String accountNo,
                                             SecureDESKey cvk,
                                             java.lang.String upn,
                                             java.lang.String authrc,
                                             java.lang.String sfarc)
                                      throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

calculateCAVVImpl in class BaseSMAdapter<SecureDESKey>

Returns:

Cardholder Authentication Verification Value

Throws:

SMException

verifyCVVImpl

protected boolean verifyCVVImpl(java.lang.String accountNo,
                                SecureDESKey cvkA,
                                SecureDESKey cvkB,
                                java.lang.String cvv,
                                java.util.Date expDate,
                                java.lang.String serviceCode)
                         throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifyCVVImpl in class BaseSMAdapter<SecureDESKey>

Returns:

true if CVV/CVC is falid or false if not

Throws:

SMException

verifyCVVImpl

protected boolean verifyCVVImpl(java.lang.String accountNo,
                                SecureDESKey cvkA,
                                SecureDESKey cvkB,
                                java.lang.String cvv,
                                java.lang.String expDate,
                                java.lang.String serviceCode)
                         throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifyCVVImpl in class BaseSMAdapter<SecureDESKey>

Returns:

true if CVV/CVC is valid or false otherwise

Throws:

SMException

verifyCAVVImpl

protected boolean verifyCAVVImpl(java.lang.String accountNo,
                                 SecureDESKey cvk,
                                 java.lang.String cavv,
                                 java.lang.String upn,
                                 java.lang.String authrc,
                                 java.lang.String sfarc)
                          throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifyCAVVImpl in class BaseSMAdapter<SecureDESKey>

Returns:

Cardholder Authentication Verification Value

Throws:

SMException

calculatedCVV

protected java.lang.String calculatedCVV(java.lang.String accountNo,
                                         SecureDESKey imkac,
                                         java.lang.String expDate,
                                         java.lang.String serviceCode,
                                         byte[] atc,
                                         MKDMethod mkdm)
                                  throws SMException

Throws:

SMException

verifydCVVImpl

protected boolean verifydCVVImpl(java.lang.String accountNo,
                                 SecureDESKey imkac,
                                 java.lang.String dcvv,
                                 java.util.Date expDate,
                                 java.lang.String serviceCode,
                                 byte[] atc,
                                 MKDMethod mkdm)
                          throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifydCVVImpl in class BaseSMAdapter<SecureDESKey>

Returns:

true if dcvv is valid false if not

Throws:

SMException

verifydCVVImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifydCVVImpl in class BaseSMAdapter<SecureDESKey>

Returns:

true if dcvv is valid false if not

Throws:

SMException

calculateCVC3

protected java.lang.String calculateCVC3(SecureDESKey imkcvc3,
                                         java.lang.String accountNo,
                                         java.lang.String acctSeqNo,
                                         byte[] atc,
                                         byte[] upn,
                                         byte[] data,
                                         MKDMethod mkdm)
                                  throws SMException

Throws:

SMException

verifyCVC3Impl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifyCVC3Impl in class BaseSMAdapter<SecureDESKey>

Returns:

true if cvc3 is valid false if not

Throws:

SMException

deriveICCMasterKey

protected java.security.Key deriveICCMasterKey(java.security.Key imk,
                                               byte[] panpsn)
                                        throws JCEHandlerException

Derive ICC Master Key from Issuer Master Key and preformated PAN/PANSeqNo Compute two 8-byte numbers:

left part is a result of Tripple-DES encription panpsn with imk as the key right part is a result of Tripple-DES binary inverted panpsn with imk as the key concatenate left and right parts
Described in EMV v4.2 Book 2, Annex A1.4.1 Master Key Derivation point 2

Parameters:

imk - 16-bytes Issuer Master Key

panpsn - preformated PAN and PAN Sequence Number

Returns:

derived 16-bytes ICC Master Key with adjusted DES parity

Throws:

JCEHandlerException

calculatePVV

protected java.lang.String calculatePVV(EncryptedPIN pinUnderLmk,
                                        java.security.Key key,
                                        int keyIdx,
                                        java.util.List<java.lang.String> excludes)
                                 throws SMException

Throws:

SMException

calculatePVVImpl

protected java.lang.String calculatePVVImpl(EncryptedPIN pinUnderLmk,
                                            SecureDESKey pvkA,
                                            SecureDESKey pvkB,
                                            int pvkIdx,
                                            java.util.List<java.lang.String> excludes)
                                     throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

calculatePVVImpl in class BaseSMAdapter<SecureDESKey>

Returns:

PVV (VISA PIN Verification Value)

Throws:

SMException

calculatePVVImpl

protected java.lang.String calculatePVVImpl(EncryptedPIN pinUnderKd1,
                                            SecureDESKey kd1,
                                            SecureDESKey pvkA,
                                            SecureDESKey pvkB,
                                            int pvkIdx,
                                            java.util.List<java.lang.String> excludes)
                                     throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

calculatePVVImpl in class BaseSMAdapter<SecureDESKey>

Returns:

PVV (VISA PIN Verification Value)

Throws:

SMException

verifyPVVImpl

public boolean verifyPVVImpl(EncryptedPIN pinUnderKd1,
                             SecureDESKey kd1,
                             SecureDESKey pvkA,
                             SecureDESKey pvkB,
                             int pvki,
                             java.lang.String pvv)
                      throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifyPVVImpl in class BaseSMAdapter<SecureDESKey>

Returns:

true if pin is valid false if not

Throws:

SMException

translatePINImpl

public EncryptedPIN translatePINImpl(EncryptedPIN pinUnderKd1,
                                     SecureDESKey kd1,
                                     SecureDESKey kd2,
                                     byte destinationPINBlockFormat)
                              throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

translatePINImpl in class BaseSMAdapter<SecureDESKey>

Returns:

translated pin

Throws:

SMException

calculateARQC

protected byte[] calculateARQC(MKDMethod mkdm,
                               SKDMethod skdm,
                               SecureDESKey imkac,
                               java.lang.String accountNo,
                               java.lang.String accntSeqNo,
                               byte[] atc,
                               byte[] upn,
                               byte[] transData)
                        throws SMException

Calculate ARQC.

Entry point e.g. for simulator systems

Throws:

SMException

verifyARQCImpl

protected boolean verifyARQCImpl(MKDMethod mkdm,
                                 SKDMethod skdm,
                                 SecureDESKey imkac,
                                 java.lang.String accountNo,
                                 java.lang.String accntSeqNo,
                                 byte[] arqc,
                                 byte[] atc,
                                 byte[] upn,
                                 byte[] transData)
                          throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifyARQCImpl in class BaseSMAdapter<SecureDESKey>

Returns:

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

Throws:

SMException

generateARPCImpl

public byte[] generateARPCImpl(MKDMethod mkdm,
                               SKDMethod skdm,
                               SecureDESKey imkac,
                               java.lang.String accountNo,
                               java.lang.String accntSeqNo,
                               byte[] arqc,
                               byte[] atc,
                               byte[] upn,
                               ARPCMethod arpcMethod,
                               byte[] arc,
                               byte[] propAuthData)
                        throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

generateARPCImpl in class BaseSMAdapter<SecureDESKey>

Returns:

calculated ARPC

Throws:

SMException

verifyARQCGenerateARPCImpl

public byte[] verifyARQCGenerateARPCImpl(MKDMethod mkdm,
                                         SKDMethod skdm,
                                         SecureDESKey imkac,
                                         java.lang.String accountNo,
                                         java.lang.String accntSeqNo,
                                         byte[] arqc,
                                         byte[] atc,
                                         byte[] upn,
                                         byte[] transData,
                                         ARPCMethod arpcMethod,
                                         byte[] arc,
                                         byte[] propAuthData)
                                  throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifyARQCGenerateARPCImpl in class BaseSMAdapter<SecureDESKey>

Returns:

calculated ARPC

Throws:

SMException

calculateARPC

protected byte[] calculateARPC(java.security.Key skarpc,
                               byte[] arqc,
                               ARPCMethod arpcMethod,
                               byte[] arc,
                               byte[] propAuthData)
                        throws SMException

Calculate ARPC.

Entry point e.g. for simulator systems

Throws:

SMException

generateSM_MACImpl

protected byte[] generateSM_MACImpl(MKDMethod mkdm,
                                    SKDMethod skdm,
                                    SecureDESKey imksmi,
                                    java.lang.String accountNo,
                                    java.lang.String accntSeqNo,
                                    byte[] atc,
                                    byte[] arqc,
                                    byte[] data)
                             throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

generateSM_MACImpl in class BaseSMAdapter<SecureDESKey>

Returns:

generated 8 bytes MAC

Throws:

SMException

translatePINGenerateSM_MACImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

translatePINGenerateSM_MACImpl in class BaseSMAdapter<SecureDESKey>

Returns:

Pair of values, encrypted PIN and 8 bytes MAC

Throws:

SMException

encryptDataImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

encryptDataImpl in class BaseSMAdapter<SecureDESKey>

Returns:

encrypted data

Throws:

SMException

decryptDataImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

decryptDataImpl in class BaseSMAdapter<SecureDESKey>

Returns:

decrypted data

Throws:

SMException

generateCBC_MACImpl

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

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

Overrides:

generateCBC_MACImpl in class BaseSMAdapter<SecureDESKey>

Parameters:

data - the data to be MACed

kd - the key used for MACing

Returns:

generated CBC-MAC bytes

Throws:

SMException

generateEDE_MACImpl

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

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

Overrides:

generateEDE_MACImpl in class BaseSMAdapter<SecureDESKey>

Parameters:

data - the data to be MACed

kd - the key used for MACing

Returns:

generated EDE-MAC bytes

Throws:

SMException

generateClearKeyComponent

public java.lang.String generateClearKeyComponent(short keyLength)
                                           throws SMException

Generates a random clear key component.

Parameters:

keyLength -

Returns:

clear key componenet

Throws:

SMException

generateKeyCheckValueImpl

protected byte[] generateKeyCheckValueImpl(SecureDESKey secureDESKey)
                                    throws SMException

Generates key check value.

Overrides:

generateKeyCheckValueImpl in class BaseSMAdapter<SecureDESKey>

Parameters:

secureDESKey - SecureDESKey with untrusted or fake Key Check Value

Returns:

generated Key Check Value

Throws:

SMException

translateKeySchemeImpl

public SecureDESKey translateKeySchemeImpl(SecureDESKey key,
                                           KeyScheme keyScheme)
                                    throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

translateKeySchemeImpl in class BaseSMAdapter<SecureDESKey>

Returns:

translated key with destKeyScheme scheme

Throws:

SMException

formKEYfromThreeClearComponents

public SecureDESKey formKEYfromThreeClearComponents(short keyLength,
                                                    java.lang.String keyType,
                                                    java.lang.String clearComponent1HexString,
                                                    java.lang.String clearComponent2HexString,
                                                    java.lang.String clearComponent3HexString)
                                             throws SMException

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

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,...

clearComponent1HexString - HexString containing the first component

clearComponent2HexString - HexString containing the second component

clearComponent3HexString - HexString containing the second component

Returns:

forms an SecureDESKey from two clear components

Throws:

SMException

formKEYfromClearComponents

public SecureDESKey formKEYfromClearComponents(short keyLength,
                                               java.lang.String keyType,
                                               java.lang.String... components)
                                        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<SecureDESKey>

Overrides:

formKEYfromClearComponents in class BaseSMAdapter<SecureDESKey>

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,...

components - up to three HexStrings containing key components

Returns:

forms an SecureDESKey from two clear components

Throws:

SMException

calculateKeyCheckValue

protected byte[] calculateKeyCheckValue(java.security.Key key)
                                 throws SMException

Calculates a key check value over a clear key

Parameters:

key -

Returns:

the key check value

Throws:

SMException

encryptToLMK

protected SecureDESKey encryptToLMK(short keyLength,
                                    java.lang.String keyType,
                                    java.security.Key clearDESKey)
                             throws SMException

Encrypts a clear DES Key under LMK to form a SecureKey

Parameters:

keyLength -

keyType -

clearDESKey -

Returns:

secureDESKey

Throws:

SMException

decryptFromLMK

protected java.security.Key decryptFromLMK(SecureDESKey secureDESKey)
                                    throws SMException

Decrypts a secure DES key from encryption under LMK

Parameters:

secureDESKey - (Key under LMK)

Returns:

clear key

Throws:

SMException

calculatePINBlock

protected byte[] calculatePINBlock(java.lang.String pin,
                                   byte pinBlockFormat,
                                   java.lang.String accountNumber)
                            throws SMException

Calculates the clear PIN Block

Parameters:

pin - as entered by the card holder on the PIN entry device

pinBlockFormat -

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

Returns:

The clear PIN Block

Throws:

SMException

calculatePIN

protected java.lang.String calculatePIN(byte[] pinBlock,
                                        byte pinBlockFormat,
                                        java.lang.String accountNumber)
                                 throws SMException

Calculates the clear pin (as entered by card holder on the pin entry device) givin the clear PIN block

Parameters:

pinBlock - clear PIN Block

pinBlockFormat -

accountNumber -

Returns:

the pin

Throws:

SMException

specialEncrypt

protected byte[] specialEncrypt(byte[] data,
                                byte[] key)
                         throws JCEHandlerException

Throws:

JCEHandlerException

specialDecrypt

protected byte[] specialDecrypt(byte[] data,
                                byte[] key)
                         throws JCEHandlerException

Throws:

JCEHandlerException

dataEncrypt

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

Description copied from interface: SMAdapter

Encrypt Data

Specified by:

dataEncrypt in interface SMAdapter<SecureDESKey>

Overrides:

dataEncrypt in class BaseSMAdapter<SecureDESKey>

Parameters:

bdk - base derivation key

clearText - clear Text

Returns:

cyphertext

Throws:

SMException

dataDecrypt

public byte[] dataDecrypt(SecureDESKey bdk,
                          byte[] cypherText)
                   throws SMException

Description copied from interface: SMAdapter

Decrypt Data

Specified by:

dataDecrypt in interface SMAdapter<SecureDESKey>

Overrides:

dataDecrypt in class BaseSMAdapter<SecureDESKey>

Parameters:

bdk - base derivation key

cypherText - clear Text

Returns:

cleartext

Throws:

SMException

calculateDerivedKey

protected byte[] calculateDerivedKey(KeySerialNumber ksn,
                                     SecureDESKey bdk,
                                     boolean tdes,
                                     boolean dataEncryption)
                              throws SMException

Throws:

SMException

importBDK

public SecureDESKey importBDK(java.lang.String clearComponent1HexString,
                              java.lang.String clearComponent2HexString,
                              java.lang.String clearComponent3HexString)
                       throws SMException

Throws:

SMException

translatePINImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

translatePINImpl in class BaseSMAdapter<SecureDESKey>

Returns:

translated pin

Throws:

SMException

importPINImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

importPINImpl in class BaseSMAdapter<SecureDESKey>

Returns:

imported pin

Throws:

SMException

exportPIN

public EncryptedPIN exportPIN(EncryptedPIN pinUnderLmk,
                              KeySerialNumber ksn,
                              SecureDESKey bdk,
                              boolean tdes,
                              byte destinationPINBlockFormat)
                       throws SMException

Exports PIN to DUKPT Encryption.

Parameters:

pinUnderLmk -

ksn -

bdk -

tdes -

destinationPINBlockFormat -

Returns:

The encrypted pin

Throws:

SMException