Class BaseSMAdapter<T>

java.lang.Object
org.jpos.security.BaseSMAdapter<T>
Type Parameters:
T - the SecureKey implementation type
All Implemented Interfaces:
Configurable, SMAdapter<T>, LogSource
Direct Known Subclasses:
JCESecurityModule
public class BaseSMAdapter<T> extends Object implements SMAdapter<T>, Configurable, LogSource

Provides base functionality for the actual Security Module Adapter.

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

  • Field Details

    • logger

      protected Logger logger
      Logger for this security module adapter.

    • realm

      protected String realm
      Log realm for this security module adapter.

    • cfg

      protected Configuration cfg
      Configuration for this adapter.

  • Constructor Details

  • Method Details

    • setConfiguration

      public void setConfiguration(Configuration cfg) throws ConfigurationException
      Description copied from interface: Configurable
      Configures this object with the supplied Configuration.
      Specified by:
      setConfiguration in interface Configurable
      Parameters:
      cfg - Configuration object
      Throws:
      ConfigurationException - if the configuration is invalid

    • setLogger

      public void setLogger(Logger logger, String realm)
      Description copied from interface: LogSource
      Attaches a Logger and realm to this log source.
      Specified by:
      setLogger in interface LogSource
      Parameters:
      logger - the logger to use
      realm - the log realm (diagnostic label)

    • getLogger

      public Logger getLogger()
      Description copied from interface: LogSource
      Returns the Logger associated with this source.
      Specified by:
      getLogger in interface LogSource
      Returns:
      the Logger

    • getRealm

      public String getRealm()
      Description copied from interface: LogSource
      Returns the log realm associated with this source.
      Specified by:
      getRealm in interface LogSource
      Returns:
      log realm

    • setName

      public void setName(String name)
      associates this SMAdapter with a name using NameRegistrar
      Parameters:
      name - name to register
      See Also:

    • getName

      public String getName()
      Returns the registered name of this SMAdapter.
      Returns:
      this SMAdapter's name ("" if no name was set)

    • getSMAdapter

      public static SMAdapter getSMAdapter(String name) throws NameRegistrar.NotFoundException
      Looks up a registered SMAdapter by name from the NameRegistrar.
      Parameters:
      name - the registered adapter name
      Returns:
      SMAdapter instance with given name.
      Throws:
      NameRegistrar.NotFoundException - if name is not found in the registry
      See Also:

    • generateKey

      public SecureDESKey generateKey(short keyLength, String keyType) throws SMException
      Description copied from interface: SMAdapter
      Generates a random DES Key.
      Specified by:
      generateKey in interface SMAdapter<T>
      Parameters:
      keyLength - bit length of the key to be generated (LENGTH_DES, LENGTH_DES3_2KEY...)
      keyType - type of the key to be generated (TYPE_ZMK, TYPE_TMK...etc)
      Returns:
      the random key secured by the security module
      Throws:
      SMException - on security module error

    • generateKey

      public SecureKey generateKey(SecureKeySpec keySpec) throws SMException
      Description copied from interface: SMAdapter
      Generates a random Key.
      Specified by:
      generateKey in interface SMAdapter<T>
      Parameters:
      keySpec - the specification of the key to be generated (length, type, usage, algorithm, etc)
      Returns:
      the random key secured by the security module
      Throws:
      SMException - on security module error
      See Also:

    • generateKeyCheckValue

      public byte[] generateKeyCheckValue(T kd) throws SMException
      Description copied from interface: SMAdapter
      Generates key check value.
      Specified by:
      generateKeyCheckValue in interface SMAdapter<T>
      Parameters:
      kd - the key with untrusted or fake Key Check Value
      Returns:
      key check value bytes
      Throws:
      SMException - on security module error

    • translateKeyScheme

      public SecureDESKey translateKeyScheme(SecureDESKey key, KeyScheme destKeyScheme) throws SMException
      Description copied from interface: SMAdapter
      Translate Key Scheme to more secure encription.

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

      Specified by:
      translateKeyScheme in interface SMAdapter<T>
      Parameters:
      key - key to be translated to destKeyScheme scheme
      destKeyScheme - destination key scheme
      Returns:
      translated key with destKeyScheme scheme
      Throws:
      SMException - on security module error

    • importKey

      public SecureDESKey importKey(short keyLength, String keyType, byte[] encryptedKey, SecureDESKey kek, boolean checkParity) throws SMException
      Description copied from interface: SMAdapter
      Imports a key from encryption under a KEK (Key-Encrypting Key) to protection under the security module.
      Specified by:
      importKey in interface SMAdapter<T>
      Parameters:
      keyLength - bit length of the key to be imported (LENGTH_DES, LENGTH_DES3_2KEY...etc)
      keyType - type of the key to be imported (TYPE_ZMK, TYPE_TMK...etc)
      encryptedKey - key to be imported encrypted under KEK
      kek - the key-encrypting key
      checkParity - if true, the key is not imported unless it has adjusted parity
      Returns:
      imported key secured by the security module
      Throws:
      SMException - if the parity of the imported key is not adjusted AND checkParity = true

    • importKey

      public SecureKey importKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec, boolean checkParity) throws SMException
      Description copied from interface: SMAdapter
      Imports a key from encryption under a KEK (Key-Encrypting Key) to protection under the security module.
      Specified by:
      importKey in interface SMAdapter<T>
      Parameters:
      kek - the key-encrypting key
      key - key to be imported and encrypted under KEK
      keySpec - the specification of the key to be imported. It allows passing or change key block attributes.
      checkParity - if true, the key is not imported unless it has adjusted parity
      Returns:
      imported key secured by the security module
      Throws:
      SMException - e.g: if the parity of the imported key is not adjusted and checkParity is true

    • exportKey

      public byte[] exportKey(SecureDESKey key, SecureDESKey kek) throws SMException
      Description copied from interface: SMAdapter
      Exports secure key to encryption under a KEK (Key-Encrypting Key).
      Specified by:
      exportKey in interface SMAdapter<T>
      Parameters:
      key - the secure key to be exported
      kek - the key-encrypting key
      Returns:
      the exported key (key encrypted under kek)
      Throws:
      SMException - on security module error

    • exportKey

      public SecureKey exportKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec) throws SMException
      Description copied from interface: SMAdapter
      Exports secure key to encryption under a KEK (Key-Encrypting Key).
      Specified by:
      exportKey in interface SMAdapter<T>
      Parameters:
      kek - the key-encrypting key
      key - the secure key to be exported
      keySpec - the specification of the key to be exported. It allows passing or change key block attributes.
      Returns:
      the exported key (key encrypted under kek)
      Throws:
      SMException - on security module error

    • encryptPIN

      public EncryptedPIN encryptPIN(String pin, String accountNumber, boolean extract) throws SMException
      Description copied from interface: SMAdapter
      Encrypts a clear pin under LMK.

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

      Specified by:
      encryptPIN in interface SMAdapter<T>
      Parameters:
      pin - clear pin as entered by cardholder
      accountNumber - if extract is false then account number, including BIN and the check digit or if parameter extract is true then 12 right-most digits of the account number, excluding the check digit
      extract - true to extract 12 right-most digits off the account number
      Returns:
      PIN under LMK
      Throws:
      SMException - on security module error

    • encryptPIN

      public EncryptedPIN encryptPIN(String pin, String accountNumber) throws SMException
      Description copied from interface: SMAdapter
      Encrypts a clear pin under LMK.

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

      Specified by:
      encryptPIN in interface SMAdapter<T>
      Parameters:
      pin - clear pin as entered by card holder
      accountNumber - account number, including BIN and the check digit
      Returns:
      PIN under LMK
      Throws:
      SMException - on security module error

    • encryptPIN

      public EncryptedPIN encryptPIN(String pin, String accountNumber, T pek) throws SMException
      Description copied from interface: SMAdapter
      Encrypts a clear PIN under PEK.

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

      Specified by:
      encryptPIN in interface SMAdapter<T>
      Parameters:
      pin - Clear PIN as entered by cardholder.
      accountNumber - account number, including BIN and the check digit.
      pek - PIN encryption key.
      Returns:
      Return PIN under PEK.
      Throws:
      SMException - on security module error

    • decryptPIN

      public String decryptPIN(EncryptedPIN pinUnderLmk) throws SMException
      Description copied from interface: SMAdapter
      Decrypts an Encrypted PIN (under LMK).

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

      Specified by:
      decryptPIN in interface SMAdapter<T>
      Parameters:
      pinUnderLmk - the encrypted PIN under LMK
      Returns:
      clear pin as entered by card holder
      Throws:
      SMException - on security module error

    • importPIN

      public EncryptedPIN importPIN(EncryptedPIN pinUnderKd1, T kd1) throws SMException
      Description copied from interface: SMAdapter
      Imports a PIN from encryption under KD (Data Key) to encryption under LMK.
      Specified by:
      importPIN in interface SMAdapter<T>
      Parameters:
      pinUnderKd1 - the encrypted PIN
      kd1 - Data Key under which the pin is encrypted
      Returns:
      pin encrypted under LMK
      Throws:
      SMException - on security module error

    • translatePIN

      public EncryptedPIN translatePIN(EncryptedPIN pinUnderKd1, T kd1, T kd2, byte destinationPINBlockFormat) throws SMException
      Description copied from interface: SMAdapter
      Translates a PIN from encrytion under KD1 to encryption under KD2.
      Specified by:
      translatePIN in interface SMAdapter<T>
      Parameters:
      pinUnderKd1 - pin encrypted under KD1
      kd1 - Data Key (also called session key) under which the pin is encrypted
      kd2 - the destination Data Key 2 under which the pin will be encrypted
      destinationPINBlockFormat - the PIN Block Format of the exported encrypted PIN
      Returns:
      pin encrypted under KD2
      Throws:
      SMException - on security module error

    • importPIN

      public EncryptedPIN importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk) throws SMException
      Description copied from interface: SMAdapter
      Imports a PIN from encryption under a transaction key to encryption under LMK.

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

      Specified by:
      importPIN in interface SMAdapter<T>
      Parameters:
      pinUnderDuk - pin encrypted under a transaction key
      ksn - Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction key
      bdk - Base Derivation Key, used to derive the transaction key underwhich the pin is encrypted
      Returns:
      pin encrypted under LMK
      Throws:
      SMException - on security module error

    • importPIN

      public EncryptedPIN importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, boolean tdes) throws SMException
      Description copied from interface: SMAdapter
      Imports a PIN from encryption under a transaction key to encryption under LMK.

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

      Specified by:
      importPIN in interface SMAdapter<T>
      Parameters:
      pinUnderDuk - pin encrypted under a transaction key
      ksn - Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction key
      bdk - Base Derivation Key, used to derive the transaction key underwhich the pin is encrypted
      tdes - Use Triple DES to calculate derived transaction key.
      Returns:
      pin encrypted under LMK
      Throws:
      SMException - on security module error

    • translatePIN

      public EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat) throws SMException
      Description copied from interface: SMAdapter
      Translates a PIN from encryption under a transaction key to encryption under a KD (Data Key).

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

      Specified by:
      translatePIN in interface SMAdapter<T>
      Parameters:
      pinUnderDuk - pin encrypted under a DUKPT transaction key
      ksn - Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction key
      bdk - Base Derivation Key, used to derive the transaction key underwhich the pin is encrypted
      kd2 - the destination Data Key (also called session key) under which the pin will be encrypted
      destinationPINBlockFormat - the PIN Block Format of the translated encrypted PIN
      Returns:
      pin encrypted under kd2
      Throws:
      SMException - on security module error

    • translatePIN

      public EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat, boolean tdes) throws SMException
      Description copied from interface: SMAdapter
      Translates a PIN from encryption under a transaction key to encryption under a KD (Data Key).

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

      Specified by:
      translatePIN in interface SMAdapter<T>
      Parameters:
      pinUnderDuk - pin encrypted under a DUKPT transaction key
      ksn - Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction key
      bdk - Base Derivation Key, used to derive the transaction key underwhich the pin is encrypted
      kd2 - the destination Data Key (also called session key) under which the pin will be encrypted
      destinationPINBlockFormat - the PIN Block Format of the translated encrypted PIN
      tdes - Use Triple DES to calculate derived transaction key.
      Returns:
      pin encrypted under kd2
      Throws:
      SMException - on security module error

    • exportPIN

      public EncryptedPIN exportPIN(EncryptedPIN pinUnderLmk, T kd2, byte destinationPINBlockFormat) throws SMException
      Description copied from interface: SMAdapter
      Exports a PIN from encryption under LMK to encryption under a KD (Data Key).
      Specified by:
      exportPIN in interface SMAdapter<T>
      Parameters:
      pinUnderLmk - pin encrypted under LMK
      kd2 - the destination data key (also called session key) under which the pin will be encrypted
      destinationPINBlockFormat - the PIN Block Format of the exported encrypted PIN
      Returns:
      pin encrypted under kd2
      Throws:
      SMException - on security module error

    • generatePIN

      public EncryptedPIN generatePIN(String accountNumber, int pinLen) throws SMException
      Description copied from interface: SMAdapter
      Generate random pin under LMK
      Specified by:
      generatePIN in interface SMAdapter<T>
      Parameters:
      accountNumber - The 12 right-most digits of the account number excluding the check digit
      pinLen - length of the pin, usually in range 4-12. Value 0 means that default length is assumed by HSM (usually 4)
      Returns:
      generated PIN under LMK
      Throws:
      SMException - on security module error

    • generatePIN

      public EncryptedPIN generatePIN(String accountNumber, int pinLen, List<String> excludes) throws SMException
      Description copied from interface: SMAdapter
      Generate random pin under LMK with exclude list
      Specified by:
      generatePIN in interface SMAdapter<T>
      Parameters:
      accountNumber - The 12 right-most digits of the account number excluding the check digit
      pinLen - length of the pin, usually in range 4-12. Value 0 means that default length is assumed by HSM (usually 4)
      excludes - list of pins which won't be generated. Each pin has to be pinLen length
      Returns:
      generated PIN under LMK
      Throws:
      SMException - on security module error

    • printPIN

      public void printPIN(String accountNo, EncryptedPIN pinUnderKd1, T kd1, String template, Map<String,String> fields) throws SMException
      Description copied from interface: SMAdapter
      Print PIN or PIN and solicitation data to the HSM configured printer.

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

      Specified by:
      printPIN in interface SMAdapter<T>
      Parameters:
      accountNo - The 12 right-most digits of the account number excluding the check digit.
      pinUnderKd1 - pin block under Key Data 1
      kd1 - Data Key 1 ZPK, TPK may be null if pinUnderKd1 contains PIN under LMK
      template - template text (PCL, PostScript or other) for PIN Mailer printer. Its format depends on used HSM. This template should includes placeholders tags (e.g. in format ${tag}) indicationg place where coresponding value or PIN should be inserted. Tags values are passed in fields map argument except PIN which is passed in argument pinUnderKd1.
      fields - map of tags values representing solicitation data to include in template. null if no solicitation data are passed
      Throws:
      SMException - on security module error

    • calculatePVV

      public String calculatePVV(EncryptedPIN pinUnderLMK, T pvkA, T pvkB, int pvkIdx) throws SMException
      Description copied from interface: SMAdapter
      Calculate PVV (VISA PIN Verification Value of PIN under LMK) with exclude list

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

      Specified by:
      calculatePVV in interface SMAdapter<T>
      Parameters:
      pinUnderLMK - PIN under LMK
      pvkA - first key PVK in PVK pair
      pvkB - second key PVK in PVK pair
      pvkIdx - index of the PVK, in range 0-6, if not present 0 is assumed
      Returns:
      PVV (VISA PIN Verification Value)
      Throws:
      SMException - if PIN is on exclude list WeakPINException is thrown

    • calculatePVV

      public String calculatePVV(EncryptedPIN pinUnderLMK, T pvkA, T pvkB, int pvkIdx, List<String> excludes) throws SMException
      Description copied from interface: SMAdapter
      Calculate PVV (VISA PIN Verification Value of PIN under LMK)

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

      Specified by:
      calculatePVV in interface SMAdapter<T>
      Parameters:
      pinUnderLMK - PIN under LMK
      pvkA - first key PVK in PVK pair
      pvkB - second key PVK in PVK pair
      pvkIdx - index of the PVK, in range 0-6, if not present 0 is assumed
      excludes - list of pins which won't be generated. Each pin has to be pinLen length
      Returns:
      PVV (VISA PIN Verification Value)
      Throws:
      SMException - on security module error

    • calculatePVV

      public String calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx) throws SMException
      Description copied from interface: SMAdapter
      Calculate PVV (VISA PIN Verification Value of customer selected PIN)

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

      Specified by:
      calculatePVV in interface SMAdapter<T>
      Parameters:
      pinUnderKd1 - the encrypted PIN
      kd1 - Data Key under which the pin is encrypted
      pvkA - first key PVK in PVK pair
      pvkB - second key PVK in PVK pair
      pvkIdx - index of the PVK, in range 0-6, if not present 0 is assumed
      Returns:
      PVV (VISA PIN Verification Value)
      Throws:
      SMException - on security module error

    • calculatePVV

      public String calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx, List<String> excludes) throws SMException
      Description copied from interface: SMAdapter
      Calculate PVV (VISA PIN Verification Value of customer selected PIN)

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

      Specified by:
      calculatePVV in interface SMAdapter<T>
      Parameters:
      pinUnderKd1 - the encrypted PIN
      kd1 - Data Key under which the pin is encrypted
      pvkA - first key PVK in PVK pair
      pvkB - second key PVK in PVK pair
      pvkIdx - index of the PVK, in range 0-6, if not present 0 is assumed
      excludes - list of pins which won't be generated. Each pin has to be pinLen length
      Returns:
      PVV (VISA PIN Verification Value)
      Throws:
      SMException - on security module error

    • verifyPVV

      public boolean verifyPVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvki, String pvv) throws SMException
      Description copied from interface: SMAdapter
      Verify PVV (VISA PIN Verification Value of an LMK encrypted PIN)

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

      Specified by:
      verifyPVV in interface SMAdapter<T>
      Parameters:
      pinUnderKd1 - pin block under kd1
      kd1 - Data Key (also called session key) under which the pin is encrypted (ZPK or TPK)
      pvkA - first PVK in PVK pair
      pvkB - second PVK in PVK pair
      pvki - index of the PVK, in range 0-6, if not present 0 is assumed
      pvv - (VISA PIN Verification Value)
      Returns:
      true if pin is valid false if not
      Throws:
      SMException - on security module error

    • calculateIBMPINOffset

      public String calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, String decTab, String pinValData, int minPinLen) throws SMException
      Description copied from interface: SMAdapter
      Calculate an PIN Offset using the IBM 3624 method

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

      Specified by:
      calculateIBMPINOffset in interface SMAdapter<T>
      Parameters:
      pinUnderLmk - PIN under LMK
      pvk - accepts single, double, triple size key length. Single key length is recomendated
      decTab - decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configuration
      pinValData - pin validation data. User-defined data consisting of hexadecimal characters and the character N, which indicates to the HSM where to insert the last 5 digits of the account number. Usualy it consists the first digits of the card number
      minPinLen - pin minimal length
      Returns:
      IBM PIN Offset
      Throws:
      SMException - on security module error

    • calculateIBMPINOffset

      public String calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, String decTab, String pinValData, int minPinLen, List<String> excludes) throws SMException
      Description copied from interface: SMAdapter
      Calculate an PIN Offset using the IBM 3624 method

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

      Specified by:
      calculateIBMPINOffset in interface SMAdapter<T>
      Parameters:
      pinUnderLmk - PIN under LMK
      pvk - accepts single, double, triple size key length. Single key length is recomendated
      decTab - decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configuration
      pinValData - pin validation data. User-defined data consisting of hexadecimal characters and the character N, which indicates to the HSM where to insert the last 5 digits of the account number. Usualy it consists the first digits of the card number
      minPinLen - pin minimal length
      excludes - list of pins which won't be generated. Each pin has to be pinLen length
      Returns:
      IBM PIN Offset
      Throws:
      SMException - on security module error

    • calculateIBMPINOffset

      public String calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, String decTab, String pinValData, int minPinLen) throws SMException
      Description copied from interface: SMAdapter
      Calculate an PIN Offset using the IBM 3624 method of customer selected PIN

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

      Specified by:
      calculateIBMPINOffset in interface SMAdapter<T>
      Parameters:
      pinUnderKd1 - the encrypted PIN
      kd1 - Data Key under which the pin is encrypted
      pvk - accepts single, double, triple size key length. Single key length is recomendated
      decTab - decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configuration
      pinValData - pin validation data. User-defined data consisting of hexadecimal characters and the character N, which indicates to the HSM where to insert the last 5 digits of the account number. Usualy it consists the first digits of the card number
      minPinLen - pin minimal length
      Returns:
      IBM PIN Offset
      Throws:
      SMException - on security module error

    • calculateIBMPINOffset

      public String calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, String decTab, String pinValData, int minPinLen, List<String> excludes) throws SMException
      Description copied from interface: SMAdapter
      Calculate an PIN Offset using the IBM 3624 method of customer selected PIN

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

      Specified by:
      calculateIBMPINOffset in interface SMAdapter<T>
      Parameters:
      pinUnderKd1 - the encrypted PIN
      kd1 - Data Key under which the pin is encrypted
      pvk - accepts single, double, triple size key length. Single key length is recomendated
      decTab - decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configuration
      pinValData - pin validation data. User-defined data consisting of hexadecimal characters and the character N, which indicates to the HSM where to insert the last 5 digits of the account number. Usualy it consists the first digits of the card number
      minPinLen - pin minimal length
      excludes - list of pins which won't be generated. Each pin has to be pinLen length
      Returns:
      IBM PIN Offset
      Throws:
      SMException - on security module error

    • verifyIBMPINOffset

      public boolean verifyIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, String offset, String decTab, String pinValData, int minPinLen) throws SMException
      Description copied from interface: SMAdapter
      Verify an PIN Offset using the IBM 3624 method
      Specified by:
      verifyIBMPINOffset in interface SMAdapter<T>
      Parameters:
      pinUnderKd1 - pin block under kd1
      kd1 - Data Key (also called session key) under which the pin is encrypted (ZPK or TPK)
      pvk - accepts single, double, triple size key length. Single key length is recomendated
      offset - IBM PIN Offset
      decTab - decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configuration
      pinValData - pin validation data. User-defined data consisting of hexadecimal characters and the character N, which indicates to the HSM where to insert the last 5 digits of the account number. Usualy it consists the first digits of the card number
      minPinLen - min pin length
      Returns:
      true if pin offset is valid false if not
      Throws:
      SMException - on security module error

    • deriveIBMPIN

      public EncryptedPIN deriveIBMPIN(String accountNo, T pvk, String decTab, String pinValData, int minPinLen, String offset) throws SMException
      Description copied from interface: SMAdapter
      Derive a PIN Using the IBM 3624 method

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

      Specified by:
      deriveIBMPIN in interface SMAdapter<T>
      Parameters:
      accountNo - the 12 right-most digits of the account number excluding the check digit
      pvk - accepts single, double, triple size key length. Single key length is recomendated
      decTab - decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configuration
      pinValData - pin validation data. User-defined data consisting of hexadecimal characters and the character N, which indicates to the HSM where to insert the last 5 digits of the account number. Usualy it consists the first digits of the card number
      minPinLen - min pin length
      offset - IBM PIN Offset
      Returns:
      PIN under LMK
      Throws:
      SMException - on security module error

    • calculateCVV

      public String calculateCVV(String accountNo, T cvkA, T cvkB, Date expDate, String serviceCode) throws SMException
      Description copied from interface: SMAdapter
      Calaculate a Card Verification Code/Value.

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

      Specified by:
      calculateCVV in interface SMAdapter<T>
      Parameters:
      accountNo - The account number including BIN and the check digit
      cvkA - the first CVK in CVK pair
      cvkB - the second CVK in CVK pair
      expDate - the card expiration date
      serviceCode - the card service code Service code should be:
      • the value which will be placed onto card's magnetic stripe for encoding CVV1/CVC1
      • "000" for printing CVV2/CVC2 on card's signature stripe
      • "999" for inclusion iCVV/Chip CVC on EMV chip card
      Returns:
      Card Verification Code/Value
      Throws:
      SMException - on security module error

    • calculateCVD

      public String calculateCVD(String accountNo, T cvkA, T cvkB, String expDate, String serviceCode) throws SMException
      Description copied from interface: SMAdapter
      Calaculate a Card Verification Digit (Code/Value).

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

      Specified by:
      calculateCVD in interface SMAdapter<T>
      Parameters:
      accountNo - The account number including BIN and the check digit
      cvkA - the first CVK in CVK pair
      cvkB - the second CVK in CVK pair
      expDate - the card expiration date
      serviceCode - the card service code Service code should be:
      • the value which will be placed onto card's magnetic stripe for encoding CVV1/CVC1
      • "000" for printing CVV2/CVC2 on card's signature stripe
      • "999" for inclusion iCVV/Chip CVC on EMV chip card
      Returns:
      Card Verification Digit (Code/Value)
      Throws:
      SMException - on security module error

    • calculateCAVV

      public String calculateCAVV(String accountNo, T cvk, String upn, String authrc, String sfarc) throws SMException
      Description copied from interface: SMAdapter
      Calaculate a 3-D Secure CAVV/AAV.
      • Visa uses CAVV (Cardholder Authentication Verification Value)
      • MasterCard uses AAV (Accountholder Authentication Value)

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

      Specified by:
      calculateCAVV in interface SMAdapter<T>
      Parameters:
      accountNo - the account number including BIN and the check digit.
      cvk - the key used to CVV/CVC generation
      upn - the unpredictable number. Calculated value based on Transaction Identifier (xid) from PAReq. A 4 decimal digits value must be supplied.
      authrc - the Authentication Results Code. A value based on the Transaction Status (status) that will be used in PARes. A 1 decimal digit value must be supplied.
      sfarc - the Second Factor Authentication Results Code. A value based on the result of second factor authentication. A 2 decimal digits value must be suppiled.
      Returns:
      Cardholder Authentication Verification Value/Accountholder Authentication Value
      Throws:
      SMException - on security module error

    • verifyCVV

      public boolean verifyCVV(String accountNo, T cvkA, T cvkB, String cvv, Date expDate, String serviceCode) throws SMException
      Description copied from interface: SMAdapter
      Verify a Card Verification Code/Value.

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

      Specified by:
      verifyCVV in interface SMAdapter<T>
      Parameters:
      accountNo - The account number including BIN and the check digit
      cvkA - the first CVK in CVK pair
      cvkB - the second CVK in CVK pair
      cvv - Card Verification Code/Value
      expDate - the card expiration date
      serviceCode - the card service code Service code should be:
      • taken from card's magnetic stripe for verifing CVV1/CVC1
      • "000" for verifing CVV2/CVC2 printed on card's signature stripe
      • "999" for verifing iCVV/Chip CVC included on EMV chip card
      Returns:
      true if CVV/CVC is valid or false if not
      Throws:
      SMException - on security module error

    • verifyCVD

      public boolean verifyCVD(String accountNo, T cvkA, T cvkB, String cvv, String expDate, String serviceCode) throws SMException
      Description copied from interface: SMAdapter
      Verify a Card Verification Digit (Code/Value).

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

      Specified by:
      verifyCVD in interface SMAdapter<T>
      Parameters:
      accountNo - The account number including BIN and the check digit
      cvkA - the first CVK in CVK pair
      cvkB - the second CVK in CVK pair
      cvv - Card Verification Code/Value
      expDate - the card expiration date
      serviceCode - the card service code Service code should be:
      • taken from card's magnetic stripe for verifing CVV1/CVC1
      • "000" for verifing CVV2/CVC2 printed on card's signature stripe
      • "999" for verifing iCVV/Chip CVC included on EMV chip card
      Returns:
      true if CVV/CVC is valid or false otherwise
      Throws:
      SMException - on security module error

    • verifyCAVV

      public boolean verifyCAVV(String accountNo, T cvk, String cavv, String upn, String authrc, String sfarc) throws SMException
      Description copied from interface: SMAdapter
      Verify a 3-D Secure CAVV/AAV.
      • Visa uses CAVV (Cardholder Authentication Verification Value)
      • MasterCard uses AAV (Accountholder Authentication Value)

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

      Specified by:
      verifyCAVV in interface SMAdapter<T>
      Parameters:
      accountNo - the account number including BIN and the check digit.
      cvk - the key used to CVV/CVC generation
      cavv - the Cardholder Authentication Verification Value or Accountholder Authentication Value.
      upn - the unpredictable number. Calculated value based on Transaction Identifier (xid) from PAReq. A 4 decimal digits value must be supplied.
      authrc - the Authentication Results Code. A value based on the Transaction Status (status) that will be used in PARes. A 1 decimal digit value must be supplied.
      sfarc - the Second Factor Authentication Results Code. A value based on the result of second factor authentication. A 2 decimal digits value must be suppiled.
      Returns:
      true if CAVV/AAV is valid or false if not
      Throws:
      SMException - on security module error

    • verifydCVV

      public boolean verifydCVV(String accountNo, T imkac, String dcvv, Date expDate, String serviceCode, byte[] atc, MKDMethod mkdm) throws SMException
      Description copied from interface: SMAdapter
      Verify a Dynamic Card Verification Value (dCVV).

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

      • accountNo
      • expDate
      • serviceCode
      • atc
      • dCVV
      Specified by:
      verifydCVV in interface SMAdapter<T>
      Parameters:
      accountNo - The account number including BIN and the check digit
      imkac - the issuer master key for generating and verifying Application Cryptograms
      dcvv - dynamic Card Verification Value
      expDate - the card expiration date
      serviceCode - the card service code
      atc - application transactin counter. This is used for ICC Master Key derivation. A 2 byte value must be supplied.
      mkdm - ICC Master Key Derivation Method. If null specified is assumed.
      Returns:
      true if dcvv is valid, or false if not
      Throws:
      SMException - on security module error

    • verifydCVV

      public boolean verifydCVV(String accountNo, T imkac, String dcvv, String expDate, String serviceCode, byte[] atc, MKDMethod mkdm) throws SMException
      Description copied from interface: SMAdapter
      Verify a Dynamic Card Verification Value (dCVV).

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

      • accountNo
      • expDate
      • serviceCode
      • atc
      • dCVV
      Specified by:
      verifydCVV in interface SMAdapter<T>
      Parameters:
      accountNo - The account number including BIN and the check digit
      imkac - the issuer master key for generating and verifying Application Cryptograms
      dcvv - dynamic Card Verification Value
      expDate - the card expiration date
      serviceCode - the card service code
      atc - application transactin counter. This is used for ICC Master Key derivation. A 2 byte value must be supplied.
      mkdm - ICC Master Key Derivation Method. If null specified is assumed.
      Returns:
      true if dcvv is valid, or false if not
      Throws:
      SMException - on security module error

    • verifyCVC3

      public boolean verifyCVC3(T imkcvc3, String accountNo, String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm, String cvc3) throws SMException
      Description copied from interface: SMAdapter
      Verify a Dynamic Card Verification Code 3 (CVC3)

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

      • accountNo
      • expDate
      • serviceCode
      • atc
      • unpredictable number
      • cvc3
      Specified by:
      verifyCVC3 in interface SMAdapter<T>
      Parameters:
      imkcvc3 - the issuer master key for generating and verifying CVC3
      accountNo - The account number including BIN and the check digit
      acctSeqNo - account sequence number, 2 decimal digits
      atc - application transactin counter. This is used for ICC Master Key derivation. A 2 byte value must be supplied.
      upn - unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied.
      data - track data
      mkdm - ICC Master Key Derivation Method. If null specified is assumed.
      cvc3 - dynamic Card Verification Code 3
      Returns:
      true if cvc3 is valid false if not
      Throws:
      SMException - on security module error

    • verifyARQC

      public boolean verifyARQC(MKDMethod mkdm, SKDMethod skdm, T imkac, String accoutNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] txnData) throws SMException
      Description copied from interface: SMAdapter
      Verify Application Cryptogram (ARQC or TC/AAC)
      • Authorization Request Cryptogram (ARQC) - Online authorization
      • Transaction certificate (TC) - Offline approval
      • Application Authentication Cryptogram (AAC) - Offline decline
      Specified by:
      verifyARQC in interface SMAdapter<T>
      Parameters:
      mkdm - ICC Master Key Derivation Method. For skdm equals SKDMethod.VSDC and SKDMethod.MCHIP this parameter is ignored and MKDMethod.OPTION_A is always used.
      skdm - Session Key Derivation Method
      imkac - the issuer master key for generating and verifying Application Cryptograms
      accoutNo - account number including BIN and check digit
      acctSeqNo - account sequence number, 2 decimal digits
      arqc - ARQC/TC/AAC. A 8 byte value must be supplied.
      atc - application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.
      upn - unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.
      txnData - transaction data. Transaction data elements and them order is dependend to proper cryptogram version. If the data supplied is a multiple of 8 bytes, no extra padding is added. If it is not a multiple of 8 bytes, additional zero padding is added. If alternative padding methods are required, it have to be applied before.
      Returns:
      true if ARQC/TC/AAC is passed or false if not
      Throws:
      SMException - on security module error

    • generateARPC

      public byte[] generateARPC(MKDMethod mkdm, SKDMethod skdm, T imkac, String accoutNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData) throws SMException
      Description copied from interface: SMAdapter
      Genarate Authorisation Response Cryptogram (ARPC)
      Specified by:
      generateARPC in interface SMAdapter<T>
      Parameters:
      mkdm - ICC Master Key Derivation Method. For skdm equals SKDMethod.VSDC and SKDMethod.MCHIP this parameter is ignored and MKDMethod.OPTION_A is always used.
      skdm - Session Key Derivation Method
      imkac - the issuer master key for generating and verifying Application Cryptograms
      accoutNo - account number including BIN and check digit
      acctSeqNo - account sequence number, 2 decimal digits
      arqc - ARQC/TC/AAC. A 8 byte value must be supplied.
      atc - application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.
      upn - unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.
      arpcMethod - ARPC calculating method. For skdm equals SKDMethod.VSDC, SKDMethod.MCHIP, SKDMethod.AEPIS_V40 only ARPCMethod.METHOD_1 is valid
      arc - the Authorisation Response Code. A 2 byte value must be supplied. For arpcMethod equals ARPCMethod.METHOD_2 it is csu - Card Status Update. Then a 4 byte value must be supplied.
      propAuthData - Proprietary Authentication Data. Up to 8 bytes. Contains optional issuer data for transmission to the card in the Issuer Authentication Data of an online transaction. It may by used only for arpcMethod equals ARPCMethod.METHOD_2 in other case is ignored.
      Returns:
      calculated 8 bytes ARPC or if arpcMethod equals ARPCMethod.METHOD_2 4 bytes ARPC
      Throws:
      SMException - on security module error

    • verifyARQCGenerateARPC

      public byte[] verifyARQCGenerateARPC(MKDMethod mkdm, SKDMethod skdm, T imkac, String accoutNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] txnData, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData) throws SMException
      Description copied from interface: SMAdapter
      Verify Application Cryptogram (ARQC or TC/AAC) and Genarate Authorisation Response Cryptogram (ARPC)
      • Authorization Request Cryptogram (ARQC) - Online authorization
      • Transaction certificate (TC) - Offline approval
      • Application Authentication Cryptogram (AAC) - Offline decline
      Specified by:
      verifyARQCGenerateARPC in interface SMAdapter<T>
      Parameters:
      mkdm - ICC Master Key Derivation Method. For skdm equals SKDMethod.VSDC and SKDMethod.MCHIP this parameter is ignored and MKDMethod.OPTION_A is always used.
      skdm - Session Key Derivation Method
      imkac - the issuer master key for generating and verifying Application Cryptograms
      accoutNo - account number including BIN and check digit
      acctSeqNo - account sequence number, 2 decimal digits
      arqc - ARQC/TC/AAC. A 8 byte value must be supplied.
      atc - application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.
      upn - unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.
      txnData - transaction data. Transaction data elements and them order is dependend to proper cryptogram version. If the data supplied is a multiple of 8 bytes, no extra padding is added. If it is not a multiple of 8 bytes, additional zero padding is added. If alternative padding methods are required, it have to be applied before.
      arpcMethod - ARPC calculating method. For skdm equals SKDMethod.VSDC, SKDMethod.MCHIP, SKDMethod.AEPIS_V40 only ARPCMethod.METHOD_1 is valid
      arc - the Authorisation Response Code. A 2 byte value must be supplied. For arpcMethod equals ARPCMethod.METHOD_2 it is csu - Card Status Update. Then a 4 byte value must be supplied.
      propAuthData - Proprietary Authentication Data. Up to 8 bytes. Contains optional issuer data for transmission to the card in the Issuer Authentication Data of an online transaction. It may by used only for arpcMethod equals ARPCMethod.METHOD_2 in other case is ignored.
      Returns:
      if ARQC/TC/AAC verification passed then calculated 8 bytes ARPC or for arpcMethod equals ARPCMethod.METHOD_2 4 bytes ARPC, null in other case
      Throws:
      SMException - on security module error

    • generateSM_MAC

      public byte[] generateSM_MAC(MKDMethod mkdm, SKDMethod skdm, T imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data) throws SMException
      Description copied from interface: SMAdapter
      Generate Secure Message MAC over suppiled message data

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

      Specified by:
      generateSM_MAC in interface SMAdapter<T>
      Parameters:
      mkdm - ICC Master Key Derivation Method. For skdm equals SKDMethod.VSDC and SKDMethod.MCHIP this parameter is ignored and MKDMethod.OPTION_A is always used.
      skdm - Session Key Derivation Method
      imksmi - the issuer master key for Secure Messaging Integrity
      accountNo - account number including BIN and check digit
      acctSeqNo - account sequence number, 2 decimal digits
      atc - application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used. Second usage is as part of data which will be macked
      arqc - ARQC/TC/AAC. A 8 byte value must be supplied. For skdm equals SKDMethod.MCHIP RAND should be suppiled. RAND is ARQC incremeted by 1 (with overflow) after each script command for that same ATC value
      data - for which MAC will be generated. Should contain APDU command e.g. PIN Unblock, Application block/unblock with some additional application dependent data
      Returns:
      generated 8 bytes MAC
      Throws:
      SMException - on security module error

    • translatePINGenerateSM_MAC

      public org.javatuples.Pair<EncryptedPIN, byte[]> translatePINGenerateSM_MAC(MKDMethod mkdm, SKDMethod skdm, PaddingMethod padm, T imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data, EncryptedPIN currentPIN, EncryptedPIN newPIN, T kd1, T imksmc, T imkac, byte destinationPINBlockFormat) throws SMException
      Description copied from interface: SMAdapter
      Translate PIN and generate MAC over suppiled message data

      This method is used by issuer to:

      • translate standard ATM PIN block format encrypted under zone or terminal key kd1 to an application specific PIN block format, encrypted under a confidentiality session key, derived from imksmc
      • generate MAC over suppiled message data and translated PIN block
      Specified by:
      translatePINGenerateSM_MAC in interface SMAdapter<T>
      Parameters:
      mkdm - ICC Master Key Derivation Method. For skdm equals SKDMethod.VSDC and SKDMethod.MCHIP this parameter is ignored and MKDMethod.OPTION_A is always used.
      skdm - Session Key Derivation Method
      padm - padding method. If null padm is derived as follow:
      padm derivation rules
      skdm valuederived padm value
      SKDMethod.VSDCPaddingMethod.VSDC
      SKDMethod.MCHIPPaddingMethod.MCHIP
      SKDMethod.EMV_CSKDPaddingMethod.CCD
      Other variations require to explicite pass padm value
      imksmi - the issuer master key for Secure Messaging Integrity
      accountNo - account number including BIN and check digit
      acctSeqNo - account sequence number, 2 decimal digits
      atc - application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used. Second usage is as part of data which will be macked
      arqc - ARQC/TC/AAC. A 8 byte value must be supplied. For skdm equals SKDMethod.MCHIP RAND should be suppiled. RAND is ARQC incremeted by 1 (with overflow) after each script command for that same ATC value
      data - for which MAC will be generated. Should contain APDU command PIN Change with some additional application dependent data
      currentPIN - encrypted under kd1 current PIN. Used when destinationPINBlockFormat equals SMAdapter.FORMAT42
      newPIN - encrypted under kd1 new PIN.
      kd1 - Data Key (also called transport key) under which the source pin is encrypted
      imksmc - the issuer master key for Secure Messaging Confidentiality
      imkac - the issuer master key for generating and verifying Application Cryptograms. Used when destinationPINBlockFormat equals SMAdapter.FORMAT41 or SMAdapter.FORMAT42 in other cases is ignored
      destinationPINBlockFormat - the PIN Block Format of the translated encrypted PIN
      Allowed values:
      SMAdapter.FORMAT34 Standard EMV PIN Block
      SMAdapter.FORMAT35 Europay/Mastercard
      SMAdapter.FORMAT41 Visa/Amex format without using Current PIN
      SMAdapter.FORMAT42 Visa/Amex format using Current PIN
      Returns:
      Pair of values, encrypted PIN and 8 bytes MAC
      Throws:
      SMException - on security module error

    • encryptData

      public byte[] encryptData(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv) throws SMException
      Encrypt Data Block.
      Specified by:
      encryptData in interface SMAdapter<T>
      Parameters:
      cipherMode - block cipher mode
      kd - DEK or ZEK key used to encrypt data
      data - data to be encrypted
      iv - initial vector
      Returns:
      encrypted data
      Throws:
      SMException - on security module error

    • decryptData

      public byte[] decryptData(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv) throws SMException
      Decrypt Data Block.
      Specified by:
      decryptData in interface SMAdapter<T>
      Parameters:
      cipherMode - block cipher mode
      kd - DEK or ZEK key used to decrypt data
      data - data to be decrypted
      iv - initial vector
      Returns:
      decrypted data
      Throws:
      SMException - on security module error

    • generateCBC_MAC

      public byte[] generateCBC_MAC(byte[] data, T kd) throws SMException
      Description copied from interface: SMAdapter
      Generates CBC-MAC (Cipher Block Chaining Message Authentication Code) for some data.
      Specified by:
      generateCBC_MAC in interface SMAdapter<T>
      Parameters:
      data - the data to be MACed
      kd - the key used for MACing
      Returns:
      the MAC
      Throws:
      SMException - on security module error

    • generateEDE_MAC

      public byte[] generateEDE_MAC(byte[] data, T kd) throws SMException
      Description copied from interface: SMAdapter
      Generates EDE-MAC (Encrypt Decrypt Encrypt Message Message Authentication Code) for some data.
      Specified by:
      generateEDE_MAC in interface SMAdapter<T>
      Parameters:
      data - the data to be MACed
      kd - the key used for MACing
      Returns:
      the MAC
      Throws:
      SMException - on security module error

    • translateKeyFromOldLMK

      public SecureDESKey translateKeyFromOldLMK(SecureDESKey kd) throws SMException
      Description copied from interface: SMAdapter
      Translate key from encryption under the LMK held in key change storage to encryption under a new LMK.
      Specified by:
      translateKeyFromOldLMK in interface SMAdapter<T>
      Parameters:
      kd - the key encrypted under old LMK
      Returns:
      key encrypted under the new LMK
      Throws:
      SMException - on security module error

    • translateKeyFromOldLMK

      public SecureKey translateKeyFromOldLMK(SecureKey key, SecureKeySpec keySpec) throws SMException
      Description copied from interface: SMAdapter
      Translate key from encryption under the LMK held in key change storage to encryption under a new LMK.
      Specified by:
      translateKeyFromOldLMK in interface SMAdapter<T>
      Parameters:
      key - the key encrypted under old LMK
      keySpec - the specification of the key to be translated. It allows passing new key block attributes.
      Returns:
      key encrypted under the new LMK
      Throws:
      SMException - on security module error

    • generateKeyPair

      public org.javatuples.Pair<PublicKey, SecurePrivateKey> generateKeyPair(AlgorithmParameterSpec spec) throws SMException
      Description copied from interface: SMAdapter
      Generate a public/private key pair.
      Specified by:
      generateKeyPair in interface SMAdapter<T>
      Parameters:
      spec - algorithm specific parameters, e.g. algorithm, key size, public key exponent.
      Returns:
      key pair generated according to passed parameters
      Throws:
      SMException - on security module error

    • generateKeyPair

      public org.javatuples.Pair<PublicKey, SecureKey> generateKeyPair(SecureKeySpec keySpec) throws SMException
      Description copied from interface: SMAdapter
      Generate a public/private key pair.
      Specified by:
      generateKeyPair in interface SMAdapter<T>
      Parameters:
      keySpec - the specification of the key to be generated. It allows passing key algorithm type, size and key block attributes. NOTE: For pass an extra key usage of the RSA key, possible is use e.g. keySpec.setVariant() or keySpec.setReserved()
      Returns:
      key pair generated according to passed parameters
      Throws:
      SMException - on security module error

    • calculateSignature

      public byte[] calculateSignature(MessageDigest hash, SecureKey privateKey, byte[] data) throws SMException
      Description copied from interface: SMAdapter
      Calculate signature of Data Block.
      Specified by:
      calculateSignature in interface SMAdapter<T>
      Parameters:
      hash - identifier of the hash algorithm used to hash passed data.
      privateKey - private key used to compute data signature.
      data - data to be signed.
      Returns:
      signature of passed data.
      Throws:
      SMException - on security module error

    • encryptData

      public byte[] encryptData(SecureKey encKey, byte[] data, AlgorithmParameterSpec algspec, byte[] iv) throws SMException
      Description copied from interface: SMAdapter
      Encrypts clear Data Block with specified cipher.

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

      Specified by:
      encryptData in interface SMAdapter<T>
      Parameters:
      encKey - the data encryption key e.g:
      • when RSA public key encapsulated in SecurePrivateKey
      • when DES/TDES DEK SecureDESKey
      data - clear data block to encrypt
      algspec - algorithm specification or null if not required. Used to pass additional algorithm parameters e.g: OAEPParameterSpec or custom extension of AlgorithmParameterSpec to pass symetric cipher mode ECB, CBC
      iv - the inital vector or null if not used (e.g: RSA cipher or ECB mode). If used, after operation will contain new iv value.
      Returns:
      encrypted data block
      Throws:
      SMException - on security module error

    • decryptData

      public byte[] decryptData(SecureKey privKey, byte[] data, AlgorithmParameterSpec algspec, byte[] iv) throws SMException
      Description copied from interface: SMAdapter
      Decrypts encrypted Data Block with specified cipher.

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

      Specified by:
      decryptData in interface SMAdapter<T>
      Parameters:
      privKey - the data decryption key e.g:
      • when RSA private key encapsulated in SecurePrivateKey
      • when DES/TDES DEK SecureDESKey
      data - encrypted data block to decrypt
      algspec - algorithm specification or null if not required. Used to pass additional algorithm parameters e.g: OAEPParameterSpec or custom extension of AlgorithmParameterSpec to pass symetric cipher mode ECB, CBC
      iv - the inital vector or null if not used (e.g: RSA cipher or ECB mode). If used, after operation will contain new iv value.
      Returns:
      decrypted data block
      Throws:
      SMException - on security module error

    • eraseOldLMK

      public void eraseOldLMK() throws SMException
      Description copied from interface: SMAdapter
      Erase the key change storage area of memory It is recommended that this command is used after keys stored by the Host have been translated from old to new LMKs.
      Specified by:
      eraseOldLMK in interface SMAdapter<T>
      Throws:
      SMException - on security module error

    • generateKeyImpl

      protected SecureDESKey generateKeyImpl(short keyLength, String keyType) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      keyLength - requested key length
      keyType - requested key type
      Returns:
      generated key
      Throws:
      SMException - on security module error

    • generateKeyImpl

      protected SecureKey generateKeyImpl(SecureKeySpec keySpec) throws SMException
      Your SMAdapter should override this method if it has this functionality.
      Parameters:
      keySpec - key specification
      Returns:
      generated key
      Throws:
      SMException - on security module error

    • generateKeyCheckValueImpl

      protected byte[] generateKeyCheckValueImpl(T kd) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      kd - secure key
      Returns:
      generated Key Check Value
      Throws:
      SMException - on security module error

    • translateKeySchemeImpl

      protected SecureDESKey translateKeySchemeImpl(SecureDESKey key, KeyScheme destKeyScheme) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      key - secure key
      destKeyScheme - destination key scheme
      Returns:
      translated key with destKeyScheme scheme
      Throws:
      SMException - on security module error

    • 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 - requested key length
      keyType - requested key type
      encryptedKey - encrypted key bytes
      kek - key-encrypting key
      checkParity - whether to check DES key parity
      Returns:
      imported key
      Throws:
      SMException - on security module error

    • importKeyImpl

      protected SecureKey importKeyImpl(SecureKey kek, SecureKey key, SecureKeySpec keySpec, boolean checkParity) throws SMException
      Your SMAdapter should override this method if it has this functionality.
      Parameters:
      kek - key-encrypting key
      key - secure key
      keySpec - key specification
      checkParity - whether to check DES key parity
      Returns:
      imported key
      Throws:
      SMException - on security module error

    • exportKeyImpl

      protected byte[] exportKeyImpl(SecureDESKey key, SecureDESKey kek) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      key - secure key
      kek - key-encrypting key
      Returns:
      exported key
      Throws:
      SMException - on security module error

    • exportKeyImpl

      protected SecureKey exportKeyImpl(SecureKey kek, SecureKey key, SecureKeySpec keySpec) throws SMException
      Your SMAdapter should override this method if it has this functionality.
      Parameters:
      kek - key-encrypting key
      key - secure key
      keySpec - key specification
      Returns:
      exported key
      Throws:
      SMException - on security module error

    • encryptPINImpl

      protected EncryptedPIN encryptPINImpl(String pin, String accountNumber) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pin - clear PIN value
      accountNumber - account number associated with the PIN block
      Returns:
      encrypted PIN under LMK
      Throws:
      SMException - on security module error

    • encryptPINImpl

      protected EncryptedPIN encryptPINImpl(String pin, String accountNumber, T pek) throws SMException
      Your SMAdapter should override this method if it has this functionality.
      Parameters:
      pin - clear PIN value
      accountNumber - account number associated with the PIN block
      pek - PIN-encrypting key
      Returns:
      encrypted PIN under PEK.
      Throws:
      SMException - on security module error

    • decryptPINImpl

      protected String decryptPINImpl(EncryptedPIN pinUnderLmk) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderLmk - PIN block encrypted under the LMK
      Returns:
      clear pin as entered by card holder
      Throws:
      SMException - on security module error

    • importPINImpl

      protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderKd1, T kd1) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderKd1 - PIN block encrypted under the source key
      kd1 - source key
      Returns:
      imported pin
      Throws:
      SMException - on security module error

    • translatePINImpl

      protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderKd1, T kd1, T kd2, byte destinationPINBlockFormat) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderKd1 - PIN block encrypted under the source key
      kd1 - source key
      kd2 - destination key
      destinationPINBlockFormat - destination PIN block format
      Returns:
      translated pin
      Throws:
      SMException - on security module error

    • importPINImpl

      @Deprecated protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk) throws SMException
      Deprecated.
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderDuk - PIN block encrypted under a DUKPT-derived key
      ksn - key serial number
      bdk - base derivation key
      Returns:
      imported pin
      Throws:
      SMException - on security module error

    • importPINImpl

      protected EncryptedPIN importPINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, boolean tdes) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderDuk - PIN block encrypted under a DUKPT-derived key
      ksn - key serial number
      bdk - base derivation key
      tdes - whether to use triple-DES DUKPT derivation
      Returns:
      imported pin
      Throws:
      SMException - on security module error

    • translatePINImpl

      @Deprecated protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat) throws SMException
      Deprecated.
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderDuk - PIN block encrypted under a DUKPT-derived key
      ksn - key serial number
      bdk - base derivation key
      kd2 - destination key
      destinationPINBlockFormat - destination PIN block format
      Returns:
      translated pin
      Throws:
      SMException - on security module error

    • translatePINImpl

      protected EncryptedPIN translatePINImpl(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat, boolean tdes) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderDuk - PIN block encrypted under a DUKPT-derived key
      ksn - key serial number
      bdk - base derivation key
      kd2 - destination key
      destinationPINBlockFormat - destination PIN block format
      tdes - whether to use triple-DES DUKPT derivation
      Returns:
      translated pin
      Throws:
      SMException - on security module error

    • exportPINImpl

      protected EncryptedPIN exportPINImpl(EncryptedPIN pinUnderLmk, T kd2, byte destinationPINBlockFormat) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderLmk - PIN block encrypted under the LMK
      kd2 - destination key
      destinationPINBlockFormat - destination PIN block format
      Returns:
      exported pin
      Throws:
      SMException - on security module error

    • 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 - account number associated with the PIN block
      pinLen - requested PIN length
      excludes - PIN values to reject
      Returns:
      generated PIN under LMK
      Throws:
      SMException - on security module error

    • printPINImpl

      protected void printPINImpl(String accountNo, EncryptedPIN pinUnderKd1, T kd1, String template, Map<String,String> fields) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      accountNo - card account number
      pinUnderKd1 - PIN block encrypted under the source key
      kd1 - source key
      template - decimalisation table template
      fields - template fields
      Throws:
      SMException - on security module error

    • calculatePVVImpl

      protected String calculatePVVImpl(EncryptedPIN pinUnderLMK, T pvkA, T pvkB, int pvkIdx, List<String> excludes) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderLMK - PIN block encrypted under the LMK
      pvkA - first PIN verification key
      pvkB - second PIN verification key
      pvkIdx - PIN verification key index
      excludes - PIN values to reject
      Returns:
      PVV (VISA PIN Verification Value)
      Throws:
      SMException - on security module error

    • calculatePVVImpl

      protected String calculatePVVImpl(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx, List<String> excludes) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderKd1 - PIN block encrypted under the source key
      kd1 - source key
      pvkA - first PIN verification key
      pvkB - second PIN verification key
      pvkIdx - PIN verification key index
      excludes - PIN values to reject
      Returns:
      PVV (VISA PIN Verification Value)
      Throws:
      SMException - on security module error

    • verifyPVVImpl

      protected boolean verifyPVVImpl(EncryptedPIN pinUnderKd, T kd, T pvkA, T pvkB, int pvki, String pvv) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderKd - PIN block encrypted under the key
      kd - secure key
      pvkA - first PIN verification key
      pvkB - second PIN verification key
      pvki - PIN verification key index
      pvv - PIN verification value
      Returns:
      true if pin is valid false if not
      Throws:
      SMException - on security module error

    • calculateIBMPINOffsetImpl

      protected String calculateIBMPINOffsetImpl(EncryptedPIN pinUnderLmk, T pvk, String decTab, String pinValData, int minPinLen, List<String> excludes) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderLmk - PIN block encrypted under the LMK
      pvk - PIN verification key
      decTab - decimalisation table
      pinValData - PIN validation data
      minPinLen - minimum PIN length
      excludes - PIN values to reject
      Returns:
      IBM PIN Offset
      Throws:
      SMException - on security module error

    • calculateIBMPINOffsetImpl

      protected String calculateIBMPINOffsetImpl(EncryptedPIN pinUnderKd1, T kd1, T pvk, String decTab, String pinValData, int minPinLen, List<String> excludes) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderKd1 - PIN block encrypted under the source key
      kd1 - source key
      pvk - PIN verification key
      decTab - decimalisation table
      pinValData - PIN validation data
      minPinLen - minimum PIN length
      excludes - PIN values to reject
      Returns:
      IBM PIN Offset
      Throws:
      SMException - on security module error

    • verifyIBMPINOffsetImpl

      protected boolean verifyIBMPINOffsetImpl(EncryptedPIN pinUnderKd, T kd, T pvk, String offset, String decTab, String pinValData, int minPinLen) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      pinUnderKd - PIN block encrypted under the key
      kd - secure key
      pvk - PIN verification key
      offset - PIN offset
      decTab - decimalisation table
      pinValData - PIN validation data
      minPinLen - minimum PIN length
      Returns:
      true if pin is valid false if not
      Throws:
      SMException - on security module error

    • deriveIBMPINImpl

      protected EncryptedPIN deriveIBMPINImpl(String accountNo, T pvk, String decTab, String pinValData, int minPinLen, String offset) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      accountNo - card account number
      pvk - PIN verification key
      decTab - decimalisation table
      pinValData - PIN validation data
      minPinLen - minimum PIN length
      offset - PIN offset
      Returns:
      derived PIN under LMK
      Throws:
      SMException - on security module error

    • calculateCVVImpl

      protected String calculateCVVImpl(String accountNo, T cvkA, T cvkB, Date expDate, String serviceCode) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      accountNo - card account number
      cvkA - first card verification key
      cvkB - second card verification key
      expDate - card expiration date
      serviceCode - card service code
      Returns:
      Card Verification Code/Value
      Throws:
      SMException - on security module error

    • calculateCVDImpl

      protected String calculateCVDImpl(String accountNo, T cvkA, T cvkB, String expDate, String serviceCode) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      accountNo - card account number
      cvkA - first card verification key
      cvkB - second card verification key
      expDate - card expiration date
      serviceCode - card service code
      Returns:
      Card Verification Digit (Code/Value)
      Throws:
      SMException - on security module error

    • calculateCAVVImpl

      protected String calculateCAVVImpl(String accountNo, T cvk, String upn, String authrc, String sfarc) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      accountNo - card account number
      cvk - card verification key
      upn - unpredictable number
      authrc - authorization response code
      sfarc - second-factor authorization response code
      Returns:
      Cardholder Authentication Verification Value
      Throws:
      SMException - on security module error

    • verifyCVVImpl

      protected boolean verifyCVVImpl(String accountNo, T cvkA, T cvkB, String cvv, Date expDate, String serviceCode) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      accountNo - card account number
      cvkA - first card verification key
      cvkB - second card verification key
      cvv - card verification value
      expDate - card expiration date
      serviceCode - card service code
      Returns:
      true if CVV/CVC is falid or false if not
      Throws:
      SMException - on security module error

    • verifyCVVImpl

      protected boolean verifyCVVImpl(String accountNo, T cvkA, T cvkB, String cvv, String expDate, String serviceCode) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      accountNo - card account number
      cvkA - first card verification key
      cvkB - second card verification key
      cvv - card verification value
      expDate - card expiration date
      serviceCode - card service code
      Returns:
      true if CVV/CVC is valid or false otherwise
      Throws:
      SMException - on security module error

    • verifyCAVVImpl

      protected boolean verifyCAVVImpl(String accountNo, T cvk, String cavv, String upn, String authrc, String sfarc) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      accountNo - card account number
      cvk - card verification key
      cavv - cardholder authentication verification value
      upn - unpredictable number
      authrc - authorization response code
      sfarc - second-factor authorization response code
      Returns:
      Cardholder Authentication Verification Value
      Throws:
      SMException - on security module error

    • verifydCVVImpl

      protected boolean verifydCVVImpl(String accountNo, T imkac, String dcvv, Date expDate, String serviceCode, byte[] atc, MKDMethod mkdm) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      accountNo - card account number
      imkac - issuer master key for application cryptograms
      dcvv - dynamic card verification value
      expDate - card expiration date
      serviceCode - card service code
      atc - application transaction counter
      mkdm - master-key derivation method
      Returns:
      true if dcvv is valid false if not
      Throws:
      SMException - on security module error

    • verifydCVVImpl

      protected boolean verifydCVVImpl(String accountNo, T imkac, String dcvv, String expDate, String serviceCode, byte[] atc, MKDMethod mkdm) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      accountNo - card account number
      imkac - issuer master key for application cryptograms
      dcvv - dynamic card verification value
      expDate - card expiration date
      serviceCode - card service code
      atc - application transaction counter
      mkdm - master-key derivation method
      Returns:
      true if dcvv is valid false if not
      Throws:
      SMException - on security module error

    • verifyCVC3Impl

      protected boolean verifyCVC3Impl(T imkcvc3, String accountNo, String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm, String cvc3) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      imkcvc3 - issuer master key for CVC3
      accountNo - card account number
      acctSeqNo - PAN sequence number
      atc - application transaction counter
      upn - unpredictable number
      data - input data
      mkdm - master-key derivation method
      cvc3 - card validation code 3
      Returns:
      true if cvc3 is valid false if not
      Throws:
      SMException - on security module error

    • verifyARQCImpl

      protected boolean verifyARQCImpl(MKDMethod mkdm, SKDMethod skdm, T imkac, String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] txnData) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      mkdm - master-key derivation method
      skdm - session-key derivation method
      imkac - issuer master key for application cryptograms
      accountNo - card account number
      acctSeqNo - PAN sequence number
      arqc - application request cryptogram
      atc - application transaction counter
      upn - unpredictable number
      txnData - transaction data
      Returns:
      true if ARQC/TC/AAC is valid or false if not
      Throws:
      SMException - on security module error

    • generateARPCImpl

      protected byte[] generateARPCImpl(MKDMethod mkdm, SKDMethod skdm, T imkac, String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      mkdm - master-key derivation method
      skdm - session-key derivation method
      imkac - issuer master key for application cryptograms
      accountNo - card account number
      acctSeqNo - PAN sequence number
      arqc - application request cryptogram
      atc - application transaction counter
      upn - unpredictable number
      arpcMethod - ARPC generation method
      arc - authorization response code
      propAuthData - proprietary authentication data
      Returns:
      calculated ARPC
      Throws:
      SMException - on security module error

    • verifyARQCGenerateARPCImpl

      protected byte[] verifyARQCGenerateARPCImpl(MKDMethod mkdm, SKDMethod skdm, T imkac, String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] transData, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      mkdm - master-key derivation method
      skdm - session-key derivation method
      imkac - issuer master key for application cryptograms
      accountNo - card account number
      acctSeqNo - PAN sequence number
      arqc - application request cryptogram
      atc - application transaction counter
      upn - unpredictable number
      transData - transaction data
      arpcMethod - ARPC generation method
      arc - authorization response code
      propAuthData - proprietary authentication data
      Returns:
      calculated ARPC
      Throws:
      SMException - on security module error

    • generateSM_MACImpl

      protected byte[] generateSM_MACImpl(MKDMethod mkdm, SKDMethod skdm, T imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      mkdm - master-key derivation method
      skdm - session-key derivation method
      imksmi - issuer master key for secure messaging integrity
      accountNo - card account number
      acctSeqNo - PAN sequence number
      atc - application transaction counter
      arqc - application request cryptogram
      data - input data
      Returns:
      generated 8 bytes MAC
      Throws:
      SMException - on security module error

    • translatePINGenerateSM_MACImpl

      protected org.javatuples.Pair<EncryptedPIN, byte[]> translatePINGenerateSM_MACImpl(MKDMethod mkdm, SKDMethod skdm, PaddingMethod padm, T imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data, EncryptedPIN currentPIN, EncryptedPIN newPIN, T kd1, T imksmc, T imkac, byte destinationPINBlockFormat) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      mkdm - master-key derivation method
      skdm - session-key derivation method
      padm - proprietary authentication data method
      imksmi - issuer master key for secure messaging integrity
      accountNo - card account number
      acctSeqNo - PAN sequence number
      atc - application transaction counter
      arqc - application request cryptogram
      data - input data
      currentPIN - current PIN value
      newPIN - replacement PIN value
      kd1 - source key
      imksmc - issuer master key for secure messaging confidentiality
      imkac - issuer master key for application cryptograms
      destinationPINBlockFormat - destination PIN block format
      Returns:
      Pair of values, encrypted PIN and 8 bytes MAC
      Throws:
      SMException - on security module error

    • encryptDataImpl

      protected byte[] encryptDataImpl(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      cipherMode - cipher mode
      kd - secure key
      data - input data
      iv - initialization vector
      Returns:
      encrypted data
      Throws:
      SMException - on security module error

    • decryptDataImpl

      protected byte[] decryptDataImpl(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      cipherMode - cipher mode
      kd - secure key
      data - input data
      iv - initialization vector
      Returns:
      decrypted data
      Throws:
      SMException - on security module error

    • generateCBC_MACImpl

      protected byte[] generateCBC_MACImpl(byte[] data, T kd) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      data - input data
      kd - secure key
      Returns:
      generated CBC-MAC
      Throws:
      SMException - on security module error

    • generateEDE_MACImpl

      protected byte[] generateEDE_MACImpl(byte[] data, T kd) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      data - input data
      kd - secure key
      Returns:
      generated EDE-MAC
      Throws:
      SMException - on security module error

    • translateKeyFromOldLMKImpl

      protected SecureDESKey translateKeyFromOldLMKImpl(SecureDESKey kd) throws SMException
      Translate key from encryption under the LMK held in key change storage to encryption under a new LMK.
      Parameters:
      kd - the key encrypted under old LMK
      Returns:
      key encrypted under the new LMK
      Throws:
      SMException - if the parity of the imported key is not adjusted AND checkParity = true

    • translateKeyFromOldLMKImpl

      protected SecureKey translateKeyFromOldLMKImpl(SecureKey key, SecureKeySpec keySpec) throws SMException
      Your SMAdapter should override this method if it has this functionality.
      Parameters:
      key - secure key
      keySpec - key specification
      Returns:
      key encrypted under the new LMK
      Throws:
      SMException - if the parity of the imported key is not adjusted AND checkParity = true

    • generateKeyPairImpl

      protected org.javatuples.Pair<PublicKey, SecurePrivateKey> generateKeyPairImpl(AlgorithmParameterSpec spec) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      spec - algorithm specific parameters (contains e.g. key size)
      Returns:
      key pair generated according to passed parameters
      Throws:
      SMException - on security module error

    • generateKeyPairImpl

      protected org.javatuples.Pair<PublicKey, SecureKey> generateKeyPairImpl(SecureKeySpec keySpec) throws SMException
      Your SMAdapter should override this method if it has this functionality.
      Parameters:
      keySpec - key specification
      Returns:
      key pair generated according to passed parameters
      Throws:
      SMException - on security module error

    • calculateSignatureImpl

      protected byte[] calculateSignatureImpl(MessageDigest hash, SecureKey privateKey, byte[] data) throws SMException
      Your SMAdapter should override this method if it has this functionality
      Parameters:
      hash - identifier of the hash algorithm used to hash passed data.
      privateKey - private key used to compute data signature.
      data - data to be sifned.
      Returns:
      signature of passed data.
      Throws:
      SMException - on security module error

    • encryptDataImpl

      protected byte[] encryptDataImpl(SecureKey encKey, byte[] data, AlgorithmParameterSpec algspec, byte[] iv) throws SMException
      Encrypts clear Data Block with specified cipher.
      Parameters:
      encKey - the data encryption key
      data - data block to encrypt
      algspec - algorithm specification
      iv - the inital vector
      Returns:
      encrypted data block
      Throws:
      SMException - on security module error

    • decryptDataImpl

      protected byte[] decryptDataImpl(SecureKey decKey, byte[] data, AlgorithmParameterSpec algspec, byte[] iv) throws SMException
      Decrypts Data Block encrypted with assymetric cipher.
      Parameters:
      decKey - the data decryption key
      data - data block to decrypt
      algspec - algorithm specification
      iv - the inital vector
      Returns:
      decrypted data block
      Throws:
      SMException - on security module error

    • 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 - on security module error

    • dataEncrypt

      public byte[] dataEncrypt(T bdk, byte[] clearText) throws SMException
      Description copied from interface: SMAdapter
      Encrypt Data
      Specified by:
      dataEncrypt in interface SMAdapter<T>
      Parameters:
      bdk - base derivation key
      clearText - clear Text
      Returns:
      cyphertext
      Throws:
      SMException - on security module error

    • dataDecrypt

      public byte[] dataDecrypt(T bdk, byte[] clearText) throws SMException
      Description copied from interface: SMAdapter
      Decrypt Data
      Specified by:
      dataDecrypt in interface SMAdapter<T>
      Parameters:
      bdk - base derivation key
      clearText - clear Text
      Returns:
      cleartext
      Throws:
      SMException - on security module error

    • formKEYfromClearComponents

      public SecureDESKey formKEYfromClearComponents(short keyLength, String keyType, String... clearComponents) throws SMException
      Description copied from interface: SMAdapter
      Forms a key from 3 clear components and returns it encrypted under its corresponding LMK The corresponding LMK is determined from the keyType
      Specified by:
      formKEYfromClearComponents in interface SMAdapter<T>
      Parameters:
      keyLength - e.g. LENGTH_DES, LENGTH_DES3_2, LENGTH_DES3_3, ..
      keyType - possible values are those defined in the SecurityModule inteface. e.g., ZMK, TMK,...
      clearComponents - up to three HexStrings containing key components
      Returns:
      forms an SecureDESKey from two clear components
      Throws:
      SMException - on security module error