Interface SMAdapter<T>

All Known Implementing Classes:
BaseSMAdapter, JCESecurityModule
public interface SMAdapter<T>
A class that implements the SMAdapter interface would act as an adapter to the real security module device (by communicating with it using its proprietary protocol). But application programmers will be communicating with the security module using this simple interface. TODO: support for EMV card/issuer RSA generation API's

  • Field Details

    • LENGTH_DES

      static final short LENGTH_DES
      DES Key Length LENGTH_DES = 64.
      See Also:

    • LENGTH_DES3_2KEY

      static final short LENGTH_DES3_2KEY
      Triple DES (2 keys) LENGTH_DES3_2KEY = 128.
      See Also:

    • LENGTH_DES3_3KEY

      static final short LENGTH_DES3_3KEY
      Triple DES (3 keys) LENGTH_DES3_3KEY = 192.
      See Also:

    • TYPE_ZMK

      static final String TYPE_ZMK
      ZMK: Zone Master Key is a DES (or Triple-DES) key-encryption key which is distributed manually in order that further keys can be exchanged automatically.
      See Also:

    • TYPE_ZPK

      static final String TYPE_ZPK
      ZPK: Zone PIN Key. is a DES (or Triple-DES) data-encrypting key which is distributed automatically and is used to encrypt PINs for transfer between communicating parties (e.g. between acquirers and issuers).
      See Also:

    • TYPE_TMK

      static final String TYPE_TMK
      TMK: Terminal Master Key. is a DES (or Triple-DES) key-encrypting key which is distributed manually, or automatically under a previously installed TMK. It is used to distribute data-encrypting keys, whithin a local network, to an ATM or POS terminal or similar.
      See Also:

    • TYPE_TPK

      static final String TYPE_TPK
      TPK: Terminal PIN Key. is a DES (or Triple-DES) data-encrypting key which is used to encrypt PINs for transmission, within a local network, between the terminal and the terminal data acquirer.
      See Also:

    • TYPE_TAK

      static final String TYPE_TAK
      TAK: Terminal Authentication Key. is a DES (or Triple-DES) data-encrypting key which is used to generate and verify a Message Authentication Code (MAC) when data is transmitted, within a local network, between the terminal and the terminal data acquirer.
      See Also:

    • TYPE_PVK

      static final String TYPE_PVK
      PVK: PIN Verification Key. is a DES (or Triple-DES) data-encrypting key which is used to generate and verify PIN verification data and thus verify the authenticity of a PIN.
      See Also:

    • TYPE_CVK

      static final String TYPE_CVK
      CVK: Card Verification Key. is similar for PVK but for card information instead of PIN
      See Also:

    • TYPE_BDK

      static final String TYPE_BDK
      BDK: Base Derivation Key. is a Triple-DES key-encryption key used to derive transaction keys in DUKPT (see ANSI X9.24)
      See Also:

    • TYPE_ZAK

      static final String TYPE_ZAK
      ZAK: Zone Authentication Key. a DES (or Triple-DES) data-encrypting key that is distributed automatically, and is used to generate and verify a Message Authentication Code (MAC) when data is transmitted between communicating parties (e.g. between acquirers and issuers)
      See Also:

    • TYPE_MK_AC

      static final String TYPE_MK_AC
      MK-AC: Issuer Master Key for generating and verifying Application Cryptograms.
      See Also:

    • TYPE_MK_SMI

      static final String TYPE_MK_SMI
      MK-SMI: Issuer Master Key for Secure Messaging Integrity. is a Triple-DES key which is used to generating Message Authrntication Codes (MAC) for scripts send to EMV chip cards.
      See Also:

    • TYPE_MK_SMC

      static final String TYPE_MK_SMC
      MK-SMC: Issuer Master Key for Secure Messaging Confidentiality. is a Triple-DES data-encrypting key which is used to encrypt data (e.g. PIN block) in scripts send to EMV chip cards.
      See Also:

    • TYPE_MK_CVC3

      static final String TYPE_MK_CVC3
      MK-CVC3: Issuer Master Key for generating and verifying Card Verification Code 3 (CVC3).
      See Also:

    • TYPE_MK_DAC

      static final String TYPE_MK_DAC
      MK-DAC Issuer Master Key for generating and verifying Data Authentication Codes.
      See Also:

    • TYPE_MK_DN

      static final String TYPE_MK_DN
      MK-DN: Issuer Master Key for generating and verifying Dynamic Numbers.
      See Also:

    • TYPE_ZEK

      static final String TYPE_ZEK
      ZEK: Zone Encryption Key.
      See Also:

    • TYPE_DEK

      static final String TYPE_DEK
      DEK: Data Encryption Key.
      See Also:

    • TYPE_RSA_SK

      static final String TYPE_RSA_SK
      RSA: Private Key.
      See Also:

    • TYPE_HMAC

      static final String TYPE_HMAC
      HMAC: Hash Message Authentication Code (with key usage).
      See Also:

    • TYPE_RSA_PK

      static final String TYPE_RSA_PK
      RSA: Public Key.
      See Also:

    • FORMAT01

      static final byte FORMAT01
      PIN Block Format adopted by ANSI (ANSI X9.8) and is one of two formats supported by the ISO (ISO 95641 - format 0).
      See Also:

    • FORMAT02

      static final byte FORMAT02
      PIN Block Format 02 supports Douctel ATMs.
      See Also:

    • FORMAT03

      static final byte FORMAT03
      PIN Block Format 03 is the Diabold Pin Block format.
      See Also:

    • FORMAT04

      static final byte FORMAT04
      PIN Block Format 04 is the PIN block format adopted by the PLUS network.
      See Also:

    • FORMAT05

      static final byte FORMAT05
      PIN Block Format 05 is the ISO 9564-1 Format 1 PIN Block.
      See Also:

    • FORMAT34

      static final byte FORMAT34
      PIN Block Format 34 is the standard EMV PIN block format. Is only avaliable as output of EMV PIN change commands.
      See Also:

    • FORMAT35

      static final byte FORMAT35
      PIN Block Format 35 is the required by Europay/MasterCard for their Pay Now invalid input: '&' Pay Later products.
      See Also:

    • FORMAT41

      static final byte FORMAT41
      PIN Block Format 41 is the Visa format for PIN change without using the current PIN.
      See Also:

    • FORMAT42

      static final byte FORMAT42
      PIN Block Format 42 is the Visa format for PIN change using the current (old) PIN.
      See Also:

    • FORMAT00

      static final byte FORMAT00
      Proprietary PIN Block format.

      Most Security Modules use a proprietary PIN Block format when encrypting the PIN under the LMK of the Security Module hence this format (FORMAT00).

      This is not a standard format, every Security Module would interpret FORMAT00 differently. So, no interchange would accept PIN Blocks from other interchanges using this format. It is useful only when working with PIN's inside your own interchange.

      See Also:

  • Method Details

    • generateKey

      SecureDESKey generateKey(short keyLength, String keyType) throws SMException
      Generates a random DES Key.
      Parameters:
      keyLength - bit length of the key to be generated (LENGTH_DES, LENGTH_DES3_2KEY...)
      keyType - type of the key to be generated (TYPE_ZMK, TYPE_TMK...etc)
      Returns:
      the random key secured by the security module
      Throws:
      SMException

    • generateKey

      SecureKey generateKey(SecureKeySpec keySpec) throws SMException
      Generates a random Key.
      Parameters:
      keySpec - the specification of the key to be generated (length, type, usage, algorithm, etc)
      Returns:
      the random key secured by the security module
      Throws:
      SMException
      See Also:

    • generateKeyCheckValue

      byte[] generateKeyCheckValue(T kd) throws SMException
      Generates key check value.
      Parameters:
      kd - the key with untrusted or fake Key Check Value
      Returns:
      key check value bytes
      Throws:
      SMException

    • translateKeyScheme

      SecureDESKey translateKeyScheme(SecureDESKey key, KeyScheme keyScheme) throws SMException
      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.

      Parameters:
      key - key to be translated to destKeyScheme scheme
      keyScheme - destination key scheme
      Returns:
      translated key with destKeyScheme scheme
      Throws:
      SMException

    • importKey

      SecureDESKey importKey(short keyLength, String keyType, byte[] encryptedKey, SecureDESKey kek, boolean checkParity) throws SMException
      Imports a key from encryption under a KEK (Key-Encrypting Key) to protection under the security module.
      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

      SecureKey importKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec, boolean checkParity) throws SMException
      Imports a key from encryption under a KEK (Key-Encrypting Key) to protection under the security module.
      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

      byte[] exportKey(SecureDESKey key, SecureDESKey kek) throws SMException
      Exports secure key to encryption under a KEK (Key-Encrypting Key).
      Parameters:
      key - the secure key to be exported
      kek - the key-encrypting key
      Returns:
      the exported key (key encrypted under kek)
      Throws:
      SMException

    • exportKey

      SecureKey exportKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec) throws SMException
      Exports secure key to encryption under a KEK (Key-Encrypting Key).
      Parameters:
      kek - the key-encrypting key
      key - the secure key to be exported
      keySpec - the specification of the key to be exported. It allows passing or change key block attributes.
      Returns:
      the exported key (key encrypted under kek)
      Throws:
      SMException

    • encryptPIN

      EncryptedPIN encryptPIN(String pin, String accountNumber) throws SMException
      Encrypts a clear pin under LMK.

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

      Parameters:
      pin - clear pin as entered by card holder
      accountNumber - account number, including BIN and the check digit
      Returns:
      PIN under LMK
      Throws:
      SMException

    • encryptPIN

      EncryptedPIN encryptPIN(String pin, String accountNumber, boolean extract) throws SMException
      Encrypts a clear pin under LMK.

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

      Parameters:
      pin - clear pin as entered by cardholder
      accountNumber - if extract is false then account number, including BIN and the check digit or if parameter extract is true then 12 right-most digits of the account number, excluding the check digit
      extract - true to extract 12 right-most digits off the account number
      Returns:
      PIN under LMK
      Throws:
      SMException

    • encryptPIN

      EncryptedPIN encryptPIN(String pin, String accountNumber, T pek) throws SMException
      Encrypts a clear PIN under PEK.

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

      Parameters:
      pin - Clear PIN as entered by cardholder.
      accountNumber - account number, including BIN and the check digit.
      pek - PIN encryption key.
      Returns:
      Return PIN under PEK.
      Throws:
      SMException

    • decryptPIN

      String decryptPIN(EncryptedPIN pinUnderLmk) throws SMException
      Decrypts an Encrypted PIN (under LMK).

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

      Parameters:
      pinUnderLmk -
      Returns:
      clear pin as entered by card holder
      Throws:
      SMException

    • importPIN

      EncryptedPIN importPIN(EncryptedPIN pinUnderKd1, T kd1) throws SMException
      Imports a PIN from encryption under KD (Data Key) to encryption under LMK.
      Parameters:
      pinUnderKd1 - the encrypted PIN
      kd1 - Data Key under which the pin is encrypted
      Returns:
      pin encrypted under LMK
      Throws:
      SMException

    • translatePIN

      EncryptedPIN translatePIN(EncryptedPIN pinUnderKd1, T kd1, T kd2, byte destinationPINBlockFormat) throws SMException
      Translates a PIN from encrytion under KD1 to encryption under KD2.
      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

      @Deprecated EncryptedPIN importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk) throws SMException
      Deprecated.
      Use signature that specifies tdes flag.
      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.

      Parameters:
      pinUnderDuk - pin encrypted under a transaction key
      ksn - Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction key
      bdk - Base Derivation Key, used to derive the transaction key underwhich the pin is encrypted
      Returns:
      pin encrypted under LMK
      Throws:
      SMException

    • importPIN

      EncryptedPIN importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, boolean tdes) throws SMException
      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.

      Parameters:
      pinUnderDuk - pin encrypted under a transaction key
      ksn - Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction key
      bdk - Base Derivation Key, used to derive the transaction key underwhich the pin is encrypted
      tdes - Use Triple DES to calculate derived transaction key.
      Returns:
      pin encrypted under LMK
      Throws:
      SMException

    • translatePIN

      @Deprecated EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat) throws SMException
      Deprecated.
      Use signature that specifies tdes flag.
      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.

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

    • translatePIN

      EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat, boolean tdes) throws SMException
      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.

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

    • exportPIN

      EncryptedPIN exportPIN(EncryptedPIN pinUnderLmk, T kd2, byte destinationPINBlockFormat) throws SMException
      Exports a PIN from encryption under LMK to encryption under a KD (Data Key).
      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

      EncryptedPIN generatePIN(String accountNumber, int pinLen) throws SMException
      Generate random pin under LMK
      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

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

    • printPIN

      void printPIN(String accountNo, EncryptedPIN pinUnderKd1, T kd1, String template, Map<String,String> fields) throws SMException
      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.

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

    • calculatePVV

      String calculatePVV(EncryptedPIN pinUnderLmk, T pvkA, T pvkB, int pvkIdx) throws SMException
      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

      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

      String calculatePVV(EncryptedPIN pinUnderLmk, T pvkA, T pvkB, int pvkIdx, List<String> excludes) throws SMException
      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

      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

      String calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx) throws SMException
      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

      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

      String calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx, List<String> excludes) throws SMException
      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

      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

      boolean verifyPVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvki, String pvv) throws SMException
      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

      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

      String calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, String decTab, String pinValData, int minPinLen) throws SMException
      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

      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

      String calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, String decTab, String pinValData, int minPinLen, List<String> excludes) throws SMException
      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

      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

      String calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, String decTab, String pinValData, int minPinLen) throws SMException
      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

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

    • calculateIBMPINOffset

      String calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, String decTab, String pinValData, int minPinLen, List<String> excludes) throws SMException
      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

      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:
      WeakPINException - if passed PIN is on excludes list
      SMException

    • verifyIBMPINOffset

      boolean verifyIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, String offset, String decTab, String pinValData, int minPinLen) throws SMException
      Verify an PIN Offset using the IBM 3624 method
      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

      EncryptedPIN deriveIBMPIN(String accountNo, T pvk, String decTab, String pinValData, int minPinLen, String offset) throws SMException
      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

      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

      @Deprecated String calculateCVV(String accountNo, T cvkA, T cvkB, Date expDate, String serviceCode) throws SMException
      Deprecated.
      Issuers do not always follow the recommended 'yyMM' format. Using the java.util.Date prevents from format manipulating to solve problem. Use calculateCVD(String, T, T, String, String) with string version of expDate
      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

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

    • calculateCVD

      String calculateCVD(String accountNo, T cvkA, T cvkB, String expDate, String serviceCode) throws SMException
      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

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

    • calculateCAVV

      String calculateCAVV(String accountNo, T cvk, String upn, String authrc, String sfarc) throws SMException
      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.

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

    • verifyCVV

      @Deprecated boolean verifyCVV(String accountNo, T cvkA, T cvkB, String cvv, Date expDate, String serviceCode) throws SMException
      Deprecated.
      Issuers do not always follow the recommended 'yyMM' format. Using the java.util.Date prevents from format manipulating to solve problem. Use verifyCVD(String, T, T, String, String, String) with string version of expDate
      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

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

    • verifyCVD

      boolean verifyCVD(String accountNo, T cvkA, T cvkB, String cvv, String expDate, String serviceCode) throws SMException
      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

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

    • verifyCAVV

      boolean verifyCAVV(String accountNo, T cvk, String cavv, String upn, String authrc, String sfarc) throws SMException
      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.

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

    • verifydCVV

      @Deprecated boolean verifydCVV(String accountNo, T imkac, String dcvv, Date expDate, String serviceCode, byte[] atc, MKDMethod mkdm) throws SMException
      Deprecated.
      Issuers do not always follow the recommended 'yyMM' format. Using the java.util.Date prevents from format manipulating to solve problem. Use verifydCVV(String, T, String, Date, String, byte[], MKDMethod) with string version of expDate
      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
      • Parameters:
      accountNo - The account number including BIN and the check digit
      imkac - the issuer master key for generating and verifying Application Cryptograms
      dcvv - dynamic Card Verification Value
      expDate - the card expiration date
      serviceCode - the card service code
      atc - application transactin counter. This is used for ICC Master Key derivation. A 2 byte value must be supplied.
      mkdm - ICC Master Key Derivation Method. If null specified is assumed.
      Returns:
      true if dcvv is valid, or false if not
      Throws:
      SMException

    • verifydCVV

      boolean verifydCVV(String accountNo, T imkac, String dcvv, String expDate, String serviceCode, byte[] atc, MKDMethod mkdm) throws SMException
      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
      Parameters:
      accountNo - The account number including BIN and the check digit
      imkac - the issuer master key for generating and verifying Application Cryptograms
      dcvv - dynamic Card Verification Value
      expDate - the card expiration date
      serviceCode - the card service code
      atc - application transactin counter. This is used for ICC Master Key derivation. A 2 byte value must be supplied.
      mkdm - ICC Master Key Derivation Method. If null specified is assumed.
      Returns:
      true if dcvv is valid, or false if not
      Throws:
      SMException

    • verifyCVC3

      boolean verifyCVC3(T imkcvc3, String accountNo, String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm, String cvc3) throws SMException
      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
      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 CVC3 calculation. A 2 byte value must be supplied.
      upn - unpredictable number. This is used for CVC3 calculation A 4 byte value must be supplied.
      data - Static Track Data or when this data length is less or equal 2 IVCVC3
      • Static Track 1 or 2 Data. From the the issuer is dependent on how to obtain it from the EMV "Track 2 Equivalent Data", provided in the authorisation message and originating from the contactless smart card. Usually variable part of Discreditionary Data are replased by some static value.
      • precomputed Initial Vector for CVC3 calculation (IVCVC3) which is a MAC calculated over the static part of Track1 or Track2 data using the key derived from MK-CVC3.
      mkdm - ICC Master Key Derivation Method. If null specified is assumed.
      cvc3 - dynamic Card Verification Code 3. Should contain 5 decimal digits. Max value is "65535" (decimal representation of 2 byte value). Is possible to pass shorter cvc3 value e.g. "789" matches with calcuated CVC3 "04789"
      Returns:
      true if cvc3 is valid false if not
      Throws:
      SMException

    • verifyARQC

      boolean verifyARQC(MKDMethod mkdm, SKDMethod skdm, T imkac, String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] txnData) throws SMException
      Verify Application Cryptogram (ARQC or TC/AAC)
      • Authorization Request Cryptogram (ARQC) - Online authorization
      • Transaction certificate (TC) - Offline approval
      • Application Authentication Cryptogram (AAC) - Offline decline
      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
      accountNo - account number including BIN and check digit
      acctSeqNo - account sequence number, 2 decimal digits
      arqc - ARQC/TC/AAC. A 8 byte value must be supplied.
      atc - application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.
      upn - unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.
      txnData - transaction data. Transaction data elements and them order is dependend to proper cryptogram version. If the data supplied is a multiple of 8 bytes, no extra padding is added. If it is not a multiple of 8 bytes, additional zero padding is added. If alternative padding methods are required, it have to be applied before.
      Returns:
      true if ARQC/TC/AAC is passed or false if not
      Throws:
      SMException

    • generateARPC

      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
      Genarate Authorisation Response Cryptogram (ARPC)
      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

      byte[] verifyARQCGenerateARPC(MKDMethod mkdm, SKDMethod skdm, T imkac, String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] txnData, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData) throws SMException
      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
      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
      accountNo - account number including BIN and check digit
      acctSeqNo - account sequence number, 2 decimal digits
      arqc - ARQC/TC/AAC. A 8 byte value must be supplied.
      atc - application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.
      upn - unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied. For skdm equals SKDMethod.VSDC is not used.
      txnData - transaction data. Transaction data elements and them order is dependend to proper cryptogram version. If the data supplied is a multiple of 8 bytes, no extra padding is added. If it is not a multiple of 8 bytes, additional zero padding is added. If alternative padding methods are required, it have to be applied before.
      arpcMethod - ARPC calculating method. For skdm equals SKDMethod.VSDC, SKDMethod.MCHIP, SKDMethod.AEPIS_V40 only ARPCMethod.METHOD_1 is valid
      arc - the Authorisation Response Code. A 2 byte value must be supplied. For arpcMethod equals ARPCMethod.METHOD_2 it is csu - Card Status Update. Then a 4 byte value must be supplied.
      propAuthData - Proprietary Authentication Data. Up to 8 bytes. Contains optional issuer data for transmission to the card in the Issuer Authentication Data of an online transaction. It may by used only for arpcMethod equals ARPCMethod.METHOD_2 in other case is ignored.
      Returns:
      if ARQC/TC/AAC verification passed then calculated 8 bytes ARPC or for arpcMethod equals ARPCMethod.METHOD_2 4 bytes ARPC, null in other case
      Throws:
      SMException

    • generateSM_MAC

      byte[] generateSM_MAC(MKDMethod mkdm, SKDMethod skdm, T imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data) throws SMException
      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

      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

      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
      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
      Parameters:
      mkdm - ICC Master Key Derivation Method. For skdm equals SKDMethod.VSDC and SKDMethod.MCHIP this parameter is ignored and MKDMethod.OPTION_A is always used.
      skdm - Session Key Derivation Method
      padm - padding method. If null padm is derived as follow:
      skdm 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 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 FORMAT41 or FORMAT42 in other cases is ignored
      destinationPINBlockFormat - the PIN Block Format of the translated encrypted PIN
      Allowed values:
      FORMAT34 Standard EMV PIN Block
      FORMAT35 Europay/Mastercard
      FORMAT41 Visa/Amex format without using Current PIN
      FORMAT42 Visa/Amex format using Current PIN
      Returns:
      Pair of values, encrypted PIN and 8 bytes MAC
      Throws:
      SMException

    • encryptData

      byte[] encryptData(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv) throws SMException
      Encrypt Data Block.
      Parameters:
      cipherMode - block cipher mode.
      kd - DEK or ZEK key used to encrypt data.
      data - data to be encrypted. If the data is not a multiple of 8 bytes, padding have to be applied before.
      iv - initial vector. Its length must be equal to the length of cipher block (8 bytes for DES, 3DES ciphers). After operation will contain new iv value. Not used for CipherMode.ECB.
      Returns:
      encrypted data. In iv array refference new value of initial vector value will be placed.
      Throws:
      SMException

    • decryptData

      byte[] decryptData(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv) throws SMException
      Decrypt Data Block.
      Parameters:
      cipherMode - block cipher mode.
      kd - DEK or ZEK key used to decrypt data.
      data - data to be decrypted.
      iv - initial vector. Its length must be equal to the length of cipher block (8 bytes for DES, 3DES ciphers). After operation will contain new iv value. Not used for CipherMode.ECB.
      Returns:
      decrypted data. In iv array refference new value of initial vector value will be placed.
      Throws:
      SMException

    • generateCBC_MAC

      byte[] generateCBC_MAC(byte[] data, T kd) throws SMException
      Generates CBC-MAC (Cipher Block Chaining Message Authentication Code) for some data.
      Parameters:
      data - the data to be MACed
      kd - the key used for MACing
      Returns:
      the MAC
      Throws:
      SMException

    • generateEDE_MAC

      byte[] generateEDE_MAC(byte[] data, T kd) throws SMException
      Generates EDE-MAC (Encrypt Decrypt Encrypt Message Message Authentication Code) for some data.
      Parameters:
      data - the data to be MACed
      kd - the key used for MACing
      Returns:
      the MAC
      Throws:
      SMException

    • translateKeyFromOldLMK

      SecureDESKey translateKeyFromOldLMK(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

    • translateKeyFromOldLMK

      SecureKey translateKeyFromOldLMK(SecureKey key, SecureKeySpec keySpec) throws SMException
      Translate key from encryption under the LMK held in key change storage to encryption under a new LMK.
      Parameters:
      key - the key encrypted under old LMK
      keySpec - the specification of the key to be translated. It allows passing new key block attributes.
      Returns:
      key encrypted under the new LMK
      Throws:
      SMException

    • generateKeyPair

      org.javatuples.Pair<PublicKey, SecurePrivateKey> generateKeyPair(AlgorithmParameterSpec spec) throws SMException
      Generate a public/private key pair.
      Parameters:
      spec - algorithm specific parameters, e.g. algorithm, key size, public key exponent.
      Returns:
      key pair generated according to passed parameters
      Throws:
      SMException

    • generateKeyPair

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

    • calculateSignature

      byte[] calculateSignature(MessageDigest hash, SecureKey privateKey, byte[] data) throws SMException
      Calculate signature of Data Block.
      Parameters:
      hash - identifier of the hash algorithm used to hash passed data.
      privateKey - private key used to compute data signature.
      data - data to be signed.
      Returns:
      signature of passed data.
      Throws:
      SMException

    • encryptData

      byte[] encryptData(SecureKey encKey, byte[] data, AlgorithmParameterSpec algspec, byte[] iv) throws SMException
      Encrypts clear Data Block with specified cipher.

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

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

    • decryptData

      byte[] decryptData(SecureKey decKey, byte[] data, AlgorithmParameterSpec algspec, byte[] iv) throws SMException
      Decrypts encrypted Data Block with specified cipher.

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

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

    • eraseOldLMK

      void eraseOldLMK() throws SMException
      Erase the key change storage area of memory It is recommended that this command is used after keys stored by the Host have been translated from old to new LMKs.
      Throws:
      SMException

    • dataEncrypt

      byte[] dataEncrypt(T bdk, byte[] clearText) throws SMException
      Encrypt Data
      Parameters:
      bdk - base derivation key
      clearText - clear Text
      Returns:
      cyphertext
      Throws:
      SMException

    • dataDecrypt

      byte[] dataDecrypt(T bdk, byte[] cypherText) throws SMException
      Decrypt Data
      Parameters:
      bdk - base derivation key
      cypherText - clear Text
      Returns:
      cleartext
      Throws:
      SMException

    • formKEYfromClearComponents

      SecureDESKey formKEYfromClearComponents(short keyLength, String keyType, String... clearComponent) throws SMException
      Forms a key from 3 clear components and returns it encrypted under its corresponding LMK The corresponding LMK is determined from the keyType
      Parameters:
      keyLength - e.g. LENGTH_DES, LENGTH_DES3_2, LENGTH_DES3_3, ..
      keyType - possible values are those defined in the SecurityModule inteface. e.g., ZMK, TMK,...
      clearComponent - up to three HexStrings containing key components
      Returns:
      forms an SecureDESKey from two clear components
      Throws:
      SMException

    • generateClearKeyComponent

      default String generateClearKeyComponent(short keyLength) throws SMException
      Generates a random clear key component.
      Parameters:
      keyLength -
      Returns:
      clear key componenet
      Throws:
      SMException