Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.jpos.security
Class BaseSMAdapter

java.lang.Object
  extended by org.jpos.security.BaseSMAdapter
All Implemented Interfaces:
Configurable, SMAdapter, LogSource
Direct Known Subclasses:
JCESecurityModule
public class BaseSMAdapter
extends Object
implements SMAdapter, Configurable, LogSource

Provides base functionality for the actual Security Module Adapter.

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

Version:
$Revision$ $Date$
Author:
Hani S. Kirollos

Field Summary
protected  Configuration cfg
           
protected  Logger logger
           
protected  String 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_MK_AC, TYPE_MK_CVC3, TYPE_MK_SMC, TYPE_MK_SMI, TYPE_PVK, TYPE_TAK, TYPE_TMK, TYPE_TPK, TYPE_ZAK, TYPE_ZMK, TYPE_ZPK
 
Constructor Summary
BaseSMAdapter()
           
BaseSMAdapter(Configuration cfg, Logger logger, String realm)
           
 
Method Summary
 String calculateCVV(String accountNo, SecureDESKey cvkA, SecureDESKey cvkB, Date expDate, String serviceCode)
          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
protected  String calculateCVVImpl(String accountNo, SecureDESKey cvkA, SecureDESKey cvkB, Date expDate, String serviceCode)
          Your SMAdapter should override this method if it has this functionality
 String calculateIBMPINOffset(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvk, String decTab, String pinValData, int minPinLen)
          Calculate an PIN Offset using the IBM 3624 method of customer selected PIN Using that method is not recomendated.
 String calculateIBMPINOffset(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvk, String decTab, String pinValData, int minPinLen, List<String> excludes)
          Calculate an PIN Offset using the IBM 3624 method of customer selected PIN Using that method is not recomendated.
 String calculateIBMPINOffset(EncryptedPIN pinUnderLmk, SecureDESKey pvk, String decTab, String pinValData, int minPinLen)
          Calculate an PIN Offset using the IBM 3624 method Using that method is not recomendated.
 String calculateIBMPINOffset(EncryptedPIN pinUnderLmk, SecureDESKey pvk, String decTab, String pinValData, int minPinLen, List<String> excludes)
          Calculate an PIN Offset using the IBM 3624 method Using that method is not recomendated.
protected  String calculateIBMPINOffsetImpl(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey 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 pinUnderLmk, SecureDESKey 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, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx)
          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
 String calculatePVV(EncryptedPIN pinUnderLMK, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx, List<String> excludes)
          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
 String calculatePVV(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx)
          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
 String calculatePVV(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx, List<String> excludes)
          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
protected  String calculatePVVImpl(EncryptedPIN pinUnderLMK, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx, List<String> excludes)
          Your SMAdapter should override this method if it has this functionality
protected  String calculatePVVImpl(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx, List<String> excludes)
          Your SMAdapter should override this method if it has this functionality
 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, SecureDESKey pvk, String decTab, String pinValData, int minPinLen, String offset)
          Derive a PIN Using the IBM 3624 method That method derive pin from pin offset (not exacly that same but working).
protected  EncryptedPIN deriveIBMPINImpl(String accountNo, SecureDESKey pvk, String decTab, String pinValData, int minPinLen, String offset)
          Your SMAdapter should override this method if it has this functionality
 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.
protected  EncryptedPIN encryptPINImpl(String pin, String accountNumber)
          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).
protected  byte[] exportKeyImpl(SecureDESKey key, SecureDESKey kek)
          Your SMAdapter should override this method if it has this functionality
 EncryptedPIN exportPIN(EncryptedPIN pinUnderLmk, SecureDESKey kd2, byte destinationPINBlockFormat)
          Exports a PIN from encryption under LMK to encryption under a KD (Data Key).
protected  EncryptedPIN exportPINImpl(EncryptedPIN pinUnderLmk, SecureDESKey kd2, byte destinationPINBlockFormat)
          Your SMAdapter should override this method if it has this functionality
 byte[] generateARPC(MKDMethod mkdm, SKDMethod skdm, SecureDESKey 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, SecureDESKey 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, SecureDESKey kd)
          Generates CBC-MAC (Cipher Block Chaining Message Authentication Code) for some data.
protected  byte[] generateCBC_MACImpl(byte[] data, SecureDESKey kd)
          Your SMAdapter should override this method if it has this functionality
 byte[] generateEDE_MAC(byte[] data, SecureDESKey kd)
          Generates EDE-MAC (Encrypt Decrypt Encrypt Message Message Authentication Code) for some data.
protected  byte[] generateEDE_MACImpl(byte[] data, SecureDESKey kd)
          Your SMAdapter should override this method if it has this functionality
 SecureDESKey generateKey(short keyLength, String keyType)
          Generates a random DES Key.
 byte[] generateKeyCheckValue(SecureDESKey kd)
          Generates key check value.
protected  byte[] generateKeyCheckValueImpl(SecureDESKey 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
 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, SecureDESKey imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data)
          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
protected  byte[] generateSM_MACImpl(MKDMethod mkdm, SKDMethod skdm, SecureDESKey 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.
protected  SecureDESKey importKeyImpl(short keyLength, String keyType, byte[] encryptedKey, SecureDESKey kek, boolean checkParity)
          Your SMAdapter should override this method if it has this functionality
 EncryptedPIN importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, SecureDESKey bdk)
          Imports a PIN from encryption under a transaction key to encryption under LMK.
 EncryptedPIN importPIN(EncryptedPIN pinUnderKd1, SecureDESKey kd1)
          Imports a PIN from encryption under KD (Data Key) to encryption under LMK.
protected  EncryptedPIN importPINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, SecureDESKey bdk)
          Your SMAdapter should override this method if it has this functionality
protected  EncryptedPIN importPINImpl(EncryptedPIN pinUnderKd1, SecureDESKey kd1)
          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.
protected  SecureDESKey translateKeyFromOldLMKImpl(SecureDESKey kd)
          Translate key from encryption under the LMK held in “key change storage” to encryption under a new LMK.
 EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, SecureDESKey bdk, SecureDESKey kd2, byte destinationPINBlockFormat)
          Translates a PIN from encryption under a transaction key to encryption under a KD (Data Key).
 EncryptedPIN translatePIN(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey 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, SecureDESKey imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data, EncryptedPIN currentPIN, EncryptedPIN newPIN, SecureDESKey kd1, SecureDESKey imksmc, SecureDESKey imkac, byte destinationPINBlockFormat)
          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
protected  org.javatuples.Pair<EncryptedPIN,byte[]> translatePINGenerateSM_MACImpl(MKDMethod mkdm, SKDMethod skdm, SecureDESKey imksmi, String accountNo, String acctSeqNo, 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)
          Your SMAdapter should override this method if it has this functionality
protected  EncryptedPIN translatePINImpl(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey kd2, byte destinationPINBlockFormat)
          Your SMAdapter should override this method if it has this functionality
 boolean verifyARQC(MKDMethod mkdm, SKDMethod skdm, SecureDESKey imkac, String accoutNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] transData)
          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, SecureDESKey imkac, String accoutNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] transData, 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, SecureDESKey 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, SecureDESKey imkac, String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] transData)
          Your SMAdapter should override this method if it has this functionality
 boolean verifyCVC3(SecureDESKey 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(SecureDESKey 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 verifyCVV(String accountNo, SecureDESKey cvkA, SecureDESKey cvkB, String cvv, Date expDate, String serviceCode)
          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
protected  boolean verifyCVVImpl(String accountNo, SecureDESKey cvkA, SecureDESKey cvkB, String cvv, Date expDate, String serviceCode)
          Your SMAdapter should override this method if it has this functionality
 boolean verifydCVV(String accountNo, SecureDESKey imkac, String dcvv, Date expDate, String serviceCode, byte[] atc, MKDMethod mkdm)
          Verify a Dynamic Card Verification Value (CVV) 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
protected  boolean verifydCVVImpl(String accountNo, SecureDESKey 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, SecureDESKey kd1, SecureDESKey pvk, String offset, String decTab, String pinValData, int minPinLen)
          Verify an PIN Offset using the IBM 3624 method
protected  boolean verifyIBMPINOffsetImpl(EncryptedPIN pinUnderKd, SecureDESKey kd, SecureDESKey pvk, String offset, String decTab, String pinValData, int minPinLen)
          Your SMAdapter should override this method if it has this functionality
 boolean verifyPVV(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvkA, SecureDESKey pvkB, int pvki, String pvv)
          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
protected  boolean verifyPVVImpl(EncryptedPIN pinUnderKd, SecureDESKey kd, SecureDESKey pvkA, SecureDESKey pvkB, int pvki, String pvv)
          Your SMAdapter should override this method if it has this functionality
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

logger

protected Logger logger

realm

protected String realm

cfg

protected Configuration cfg
Constructor Detail

BaseSMAdapter

public BaseSMAdapter()

BaseSMAdapter

public BaseSMAdapter(Configuration cfg,
                     Logger logger,
                     String realm)
              throws ConfigurationException
Throws:
ConfigurationException
Method Detail

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

generateKeyCheckValue

public byte[] generateKeyCheckValue(SecureDESKey kd)
                             throws SMException
Description copied from interface: SMAdapter
Generates key check value.

Specified by:
generateKeyCheckValue in interface SMAdapter
Parameters:
kd - SecureDESKey with untrusted or fake Key Check Value
Returns:
key check value bytes
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
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

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
Parameters:
key - the secure key to be exported
kek - the key-encrypting key
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
Parameters:
pin - clear pin as entered by card holder
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
Parameters:
pin - clear pin as entered by card holder
accountNumber - account number, including BIN and the check digit
Returns:
PIN under LMK
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
Returns:
clear pin as entered by card holder
Throws:
SMException

importPIN

public EncryptedPIN importPIN(EncryptedPIN pinUnderKd1,
                              SecureDESKey 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
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,
                                 SecureDESKey kd1,
                                 SecureDESKey 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
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,
                              SecureDESKey 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
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

translatePIN

public EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk,
                                 KeySerialNumber ksn,
                                 SecureDESKey bdk,
                                 SecureDESKey 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
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

exportPIN

public EncryptedPIN exportPIN(EncryptedPIN pinUnderLmk,
                              SecureDESKey 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
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
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
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

calculatePVV

public String calculatePVV(EncryptedPIN pinUnderLMK,
                           SecureDESKey pvkA,
                           SecureDESKey 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
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,
                           SecureDESKey pvkA,
                           SecureDESKey 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
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,
                           SecureDESKey kd1,
                           SecureDESKey pvkA,
                           SecureDESKey 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
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,
                           SecureDESKey kd1,
                           SecureDESKey pvkA,
                           SecureDESKey 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
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:
WeakPINException - if passed PIN is on excludes list
SMException

verifyPVV

public boolean verifyPVV(EncryptedPIN pinUnderKd1,
                         SecureDESKey kd1,
                         SecureDESKey pvkA,
                         SecureDESKey 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
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,
                                    SecureDESKey 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
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,
                                    SecureDESKey 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
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:
WeakPINException - if passed PIN is on excludes list
SMException

calculateIBMPINOffset

public String calculateIBMPINOffset(EncryptedPIN pinUnderKd1,
                                    SecureDESKey kd1,
                                    SecureDESKey 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
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,
                                    SecureDESKey kd1,
                                    SecureDESKey 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
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:
WeakPINException - if passed PIN is on excludes list
SMException

verifyIBMPINOffset

public boolean verifyIBMPINOffset(EncryptedPIN pinUnderKd1,
                                  SecureDESKey kd1,
                                  SecureDESKey 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
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,
                                 SecureDESKey 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
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,
                           SecureDESKey cvkA,
                           SecureDESKey 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
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

verifyCVV

public boolean verifyCVV(String accountNo,
                         SecureDESKey cvkA,
                         SecureDESKey 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
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 falid or false if not
Throws:
SMException

verifydCVV

public boolean verifydCVV(String accountNo,
                          SecureDESKey imkac,
                          String dcvv,
                          Date expDate,
                          String serviceCode,
                          byte[] atc,
                          MKDMethod mkdm)
                   throws SMException
Description copied from interface: SMAdapter
Verify a Dynamic Card Verification Value (CVV) 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
    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 MKDMethod.OPTION_A
    Returns:
    Throws:
    SMException

    • verifyCVC3

    public boolean verifyCVC3(SecureDESKey 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:

    Specified by:
    verifyCVC3 in interface SMAdapter
    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 MKDMethod.OPTION_A
    cvc3 - dynamic Card Verification Code 3
    Returns:
    Throws:
    SMException

    verifyARQC

    public boolean verifyARQC(MKDMethod mkdm,
                          SKDMethod skdm,
                          SecureDESKey imkac,
                          String accoutNo,
                          String acctSeqNo,
                          byte[] arqc,
                          byte[] atc,
                          byte[] upn,
                          byte[] transData)
                   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
    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.
    transData - transaction data (without padding). Transaction data elements and them order is dependend to proper cryptogram version
    Returns:
    true if ARQC/TC/AAC is passed or false if not
    Throws:
    SMException

    • generateARPC

    public byte[] generateARPC(MKDMethod mkdm,
                           SKDMethod skdm,
                           SecureDESKey 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
    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,
                                     SecureDESKey imkac,
                                     String accoutNo,
                                     String acctSeqNo,
                                     byte[] arqc,
                                     byte[] atc,
                                     byte[] upn,
                                     byte[] transData,
                                     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
    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.
    transData - transaction data (without padding). Transaction data elements and them order is dependend to proper cryptogram version
    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,
                             SecureDESKey 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
    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,
                                                                           SecureDESKey imksmi,
                                                                           String accountNo,
                                                                           String acctSeqNo,
                                                                           byte[] atc,
                                                                           byte[] arqc,
                                                                           byte[] data,
                                                                           EncryptedPIN currentPIN,
                                                                           EncryptedPIN newPIN,
                                                                           SecureDESKey kd1,
                                                                           SecureDESKey imksmc,
                                                                           SecureDESKey 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
    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 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

    • generateCBC_MAC

    public byte[] generateCBC_MAC(byte[] data,
                              SecureDESKey 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
    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,
                              SecureDESKey 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
    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
    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

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

    generateKeyCheckValueImpl

    protected byte[] generateKeyCheckValueImpl(SecureDESKey kd)
                                    throws SMException
    Your SMAdapter should override this method if it has this functionality

    Parameters:
    kd -
    Returns:
    generated Key Check Value
    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 -
    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

    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

    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,
                                     SecureDESKey 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,
                                        SecureDESKey kd1,
                                        SecureDESKey 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

    protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderDuk,
                                     KeySerialNumber ksn,
                                     SecureDESKey bdk)
                              throws SMException
    Your SMAdapter should override this method if it has this functionality

    Parameters:
    pinUnderDuk -
    ksn -
    bdk -
    Returns:
    imported pin
    Throws:
    SMException

    translatePINImpl

    protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderDuk,
                                        KeySerialNumber ksn,
                                        SecureDESKey bdk,
                                        SecureDESKey kd2,
                                        byte destinationPINBlockFormat)
                                 throws SMException
    Your SMAdapter should override this method if it has this functionality

    Parameters:
    pinUnderDuk -
    ksn -
    bdk -
    kd2 -
    destinationPINBlockFormat -
    Returns:
    translated pin
    Throws:
    SMException

    exportPINImpl

    protected EncryptedPIN exportPINImpl(EncryptedPIN pinUnderLmk,
                                     SecureDESKey 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

    calculatePVVImpl

    protected String calculatePVVImpl(EncryptedPIN pinUnderLMK,
                                  SecureDESKey pvkA,
                                  SecureDESKey pvkB,
                                  int pvkIdx,
                                  List<String> excludes)
                           throws SMException
    Your SMAdapter should override this method if it has this functionality

    Parameters:
    pinUnderLMK -
    pvkA -
    pvkB -
    pvkIdx -
    Returns:
    PVV (VISA PIN Verification Value)
    Throws:
    SMException

    calculatePVVImpl

    protected String calculatePVVImpl(EncryptedPIN pinUnderKd1,
                                  SecureDESKey kd1,
                                  SecureDESKey pvkA,
                                  SecureDESKey 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 -
    Returns:
    PVV (VISA PIN Verification Value)
    Throws:
    SMException

    verifyPVVImpl

    protected boolean verifyPVVImpl(EncryptedPIN pinUnderKd,
                                SecureDESKey kd,
                                SecureDESKey pvkA,
                                SecureDESKey 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:
    Throws:
    SMException

    calculateIBMPINOffsetImpl

    protected String calculateIBMPINOffsetImpl(EncryptedPIN pinUnderLmk,
                                           SecureDESKey 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,
                                           SecureDESKey kd1,
                                           SecureDESKey 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,
                                         SecureDESKey kd,
                                         SecureDESKey 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:
    Throws:
    SMException

    deriveIBMPINImpl

    protected EncryptedPIN deriveIBMPINImpl(String accountNo,
                                        SecureDESKey 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,
                                  SecureDESKey cvkA,
                                  SecureDESKey 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

    verifyCVVImpl

    protected boolean verifyCVVImpl(String accountNo,
                                SecureDESKey cvkA,
                                SecureDESKey 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

    verifydCVVImpl

    protected boolean verifydCVVImpl(String accountNo,
                                 SecureDESKey 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:
    Throws:
    SMException

    verifyCVC3Impl

    protected boolean verifyCVC3Impl(SecureDESKey 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:
    Throws:
    SMException

    verifyARQCImpl

    protected boolean verifyARQCImpl(MKDMethod mkdm,
                                 SKDMethod skdm,
                                 SecureDESKey imkac,
                                 String accountNo,
                                 String acctSeqNo,
                                 byte[] arqc,
                                 byte[] atc,
                                 byte[] upn,
                                 byte[] transData)
                          throws SMException
    Your SMAdapter should override this method if it has this functionality

    Parameters:
    mkdm -
    skdm -
    imkac -
    accountNo -
    acctSeqNo -
    arqc -
    atc -
    upn -
    transData -
    Returns:
    true if ARQC/TC/AAC is falid or false if not
    Throws:
    SMException

    generateARPCImpl

    protected byte[] generateARPCImpl(MKDMethod mkdm,
                                  SKDMethod skdm,
                                  SecureDESKey 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,
                                            SecureDESKey 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 -
    arpcMethod -
    arc -
    propAuthData -
    Returns:
    calculated ARPC
    Throws:
    SMException

    generateSM_MACImpl

    protected byte[] generateSM_MACImpl(MKDMethod mkdm,
                                    SKDMethod skdm,
                                    SecureDESKey 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,
                                                                                  SecureDESKey imksmi,
                                                                                  String accountNo,
                                                                                  String acctSeqNo,
                                                                                  byte[] atc,
                                                                                  byte[] arqc,
                                                                                  byte[] data,
                                                                                  EncryptedPIN currentPIN,
                                                                                  EncryptedPIN newPIN,
                                                                                  SecureDESKey kd1,
                                                                                  SecureDESKey imksmc,
                                                                                  SecureDESKey imkac,
                                                                                  byte destinationPINBlockFormat)
                                                                           throws SMException
    Your SMAdapter should override this method if it has this functionality

    Parameters:
    mkdm -
    skdm -
    imksmi -
    accountNo -
    acctSeqNo -
    atc -
    arqc -
    data -
    currentPIN -
    newPIN -
    kd1 -
    imksmc -
    imkac -
    destinationPINBlockFormat -
    Returns:
    Pair of values, encrypted PIN and 8 bytes MAC
    Throws:
    SMException

    generateCBC_MACImpl

    protected byte[] generateCBC_MACImpl(byte[] data,
                                     SecureDESKey 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,
                                     SecureDESKey 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

    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
    Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
     PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
    SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
    Copyright © 1998-2012 jPOS.org. All Rights Reserved.