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 Summary
Fields Modifier and Type Field Description static byte
FORMAT00
Proprietary PIN Block format.static 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).static byte
FORMAT02
PIN Block Format 02 supports Douctel ATMs.static byte
FORMAT03
PIN Block Format 03 is the Diabold Pin Block format.static byte
FORMAT04
PIN Block Format 04 is the PIN block format adopted by the PLUS network.static byte
FORMAT05
PIN Block Format 05 is the ISO 9564-1 Format 1 PIN Block.static byte
FORMAT34
PIN Block Format 34 is the standard EMV PIN block format.static byte
FORMAT35
PIN Block Format 35 is the required by Europay/MasterCard for their Pay Now & Pay Later products.static byte
FORMAT41
PIN Block Format 41 is the Visa format for PIN change without using the current PIN.static byte
FORMAT42
PIN Block Format 42 is the Visa format for PIN change using the current (old) PIN.static short
LENGTH_DES
DES Key LengthLENGTH_DES
= 64.static short
LENGTH_DES3_2KEY
Triple DES (2 keys)LENGTH_DES3_2KEY
= 128.static short
LENGTH_DES3_3KEY
Triple DES (3 keys)LENGTH_DES3_3KEY
= 192.static java.lang.String
TYPE_BDK
BDK: Base Derivation Key.static java.lang.String
TYPE_CVK
CVK: Card Verification Key.static java.lang.String
TYPE_DEK
DEK: Data Encryption Key.static java.lang.String
TYPE_HMAC
HMAC: Hash Message Authentication Code (with key usage).static java.lang.String
TYPE_MK_AC
MK-AC: Issuer Master Key for generating and verifying Application Cryptograms.static java.lang.String
TYPE_MK_CVC3
MK-CVC3: Issuer Master Key for generating and verifying Card Verification Code 3 (CVC3).static java.lang.String
TYPE_MK_DAC
MK-DAC Issuer Master Key for generating and verifying Data Authentication Codes.static java.lang.String
TYPE_MK_DN
MK-DN: Issuer Master Key for generating and verifying Dynamic Numbers.static java.lang.String
TYPE_MK_SMC
MK-SMC: Issuer Master Key for Secure Messaging Confidentiality.static java.lang.String
TYPE_MK_SMI
MK-SMI: Issuer Master Key for Secure Messaging Integrity.static java.lang.String
TYPE_PVK
PVK: PIN Verification Key.static java.lang.String
TYPE_RSA_PK
RSA: Public Key.static java.lang.String
TYPE_RSA_SK
RSA: Private Key.static java.lang.String
TYPE_TAK
TAK: Terminal Authentication Key.static java.lang.String
TYPE_TMK
TMK: Terminal Master Key.static java.lang.String
TYPE_TPK
TPK: Terminal PIN Key.static java.lang.String
TYPE_ZAK
ZAK: Zone Authentication Key.static java.lang.String
TYPE_ZEK
ZEK: Zone Encryption Key.static java.lang.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.static java.lang.String
TYPE_ZPK
ZPK: Zone PIN Key.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description java.lang.String
calculateCAVV(java.lang.String accountNo, T cvk, java.lang.String upn, java.lang.String authrc, java.lang.String sfarc)
Calaculate a 3-D Secure CAVV/AAV.java.lang.String
calculateCVD(java.lang.String accountNo, T cvkA, T cvkB, java.lang.String expDate, java.lang.String serviceCode)
Calaculate a Card Verification Digit (Code/Value).java.lang.String
calculateCVV(java.lang.String accountNo, T cvkA, T cvkB, java.util.Date expDate, java.lang.String serviceCode)
Deprecated.Issuers do not always follow the recommended 'yyMM' format.java.lang.String
calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, java.lang.String decTab, java.lang.String pinValData, int minPinLen)
Calculate an PIN Offset using the IBM 3624 methodjava.lang.String
calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, java.lang.String decTab, java.lang.String pinValData, int minPinLen, java.util.List<java.lang.String> excludes)
Calculate an PIN Offset using the IBM 3624 methodjava.lang.String
calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, java.lang.String decTab, java.lang.String pinValData, int minPinLen)
Calculate an PIN Offset using the IBM 3624 method of customer selected PINjava.lang.String
calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, java.lang.String decTab, java.lang.String pinValData, int minPinLen, java.util.List<java.lang.String> excludes)
Calculate an PIN Offset using the IBM 3624 method of customer selected PINjava.lang.String
calculatePVV(EncryptedPIN pinUnderLmk, T pvkA, T pvkB, int pvkIdx)
Calculate PVV (VISA PIN Verification Value of PIN under LMK) with exclude listjava.lang.String
calculatePVV(EncryptedPIN pinUnderLmk, T pvkA, T pvkB, int pvkIdx, java.util.List<java.lang.String> excludes)
Calculate PVV (VISA PIN Verification Value of PIN under LMK)java.lang.String
calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx)
Calculate PVV (VISA PIN Verification Value of customer selected PIN)java.lang.String
calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx, java.util.List<java.lang.String> excludes)
Calculate PVV (VISA PIN Verification Value of customer selected PIN)byte[]
calculateSignature(java.security.MessageDigest hash, SecureKey privateKey, byte[] data)
Calculate signature of Data Block.byte[]
dataDecrypt(T bdk, byte[] cypherText)
Decrypt Databyte[]
dataEncrypt(T bdk, byte[] clearText)
Encrypt Databyte[]
decryptData(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv)
Decrypt Data Block.byte[]
decryptData(SecureKey decKey, byte[] data, java.security.spec.AlgorithmParameterSpec algspec, byte[] iv)
Decrypts encrypted Data Block with specified cipher.java.lang.String
decryptPIN(EncryptedPIN pinUnderLmk)
Decrypts an Encrypted PIN (under LMK).EncryptedPIN
deriveIBMPIN(java.lang.String accountNo, T pvk, java.lang.String decTab, java.lang.String pinValData, int minPinLen, java.lang.String offset)
Derive a PIN Using the IBM 3624 methodbyte[]
encryptData(CipherMode cipherMode, SecureDESKey kd, byte[] data, byte[] iv)
Encrypt Data Block.byte[]
encryptData(SecureKey encKey, byte[] data, java.security.spec.AlgorithmParameterSpec algspec, byte[] iv)
Encrypts clear Data Block with specified cipher.EncryptedPIN
encryptPIN(java.lang.String pin, java.lang.String accountNumber)
Encrypts a clear pin under LMK.EncryptedPIN
encryptPIN(java.lang.String pin, java.lang.String accountNumber, boolean extract)
Encrypts a clear pin under LMK.EncryptedPIN
encryptPIN(java.lang.String pin, java.lang.String accountNumber, T pek)
Encrypts a clear PIN under PEK.void
eraseOldLMK()
Erase the key change storage area of memory It is recommended that this command is used after keys stored by the Host have been translated from old to new LMKs.byte[]
exportKey(SecureDESKey key, SecureDESKey kek)
Exports secure key to encryption under a KEK (Key-Encrypting Key).SecureKey
exportKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec)
Exports secure key to encryption under a KEK (Key-Encrypting Key).EncryptedPIN
exportPIN(EncryptedPIN pinUnderLmk, T kd2, byte destinationPINBlockFormat)
Exports a PIN from encryption under LMK to encryption under a KD (Data Key).SecureDESKey
formKEYfromClearComponents(short keyLength, java.lang.String keyType, java.lang.String... clearComponent)
Forms a key from 3 clear components and returns it encrypted under its corresponding LMK The corresponding LMK is determined from the keyTypebyte[]
generateARPC(MKDMethod mkdm, SKDMethod skdm, T imkac, java.lang.String accoutNo, java.lang.String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData)
Genarate Authorisation Response Cryptogram (ARPC)byte[]
generateCBC_MAC(byte[] data, T kd)
Generates CBC-MAC (Cipher Block Chaining Message Authentication Code) for some data.default java.lang.String
generateClearKeyComponent(short keyLength)
Generates a random clear key component.byte[]
generateEDE_MAC(byte[] data, T kd)
Generates EDE-MAC (Encrypt Decrypt Encrypt Message Message Authentication Code) for some data.SecureDESKey
generateKey(short keyLength, java.lang.String keyType)
Generates a random DES Key.SecureKey
generateKey(SecureKeySpec keySpec)
Generates a random Key.byte[]
generateKeyCheckValue(T kd)
Generates key check value.org.javatuples.Pair<java.security.PublicKey,SecurePrivateKey>
generateKeyPair(java.security.spec.AlgorithmParameterSpec spec)
Generate a public/private key pair.org.javatuples.Pair<java.security.PublicKey,SecureKey>
generateKeyPair(SecureKeySpec keySpec)
Generate a public/private key pair.EncryptedPIN
generatePIN(java.lang.String accountNumber, int pinLen)
Generate random pin under LMKEncryptedPIN
generatePIN(java.lang.String accountNumber, int pinLen, java.util.List<java.lang.String> excludes)
Generate random pin under LMK with exclude listbyte[]
generateSM_MAC(MKDMethod mkdm, SKDMethod skdm, T imksmi, java.lang.String accountNo, java.lang.String acctSeqNo, byte[] atc, byte[] arqc, byte[] data)
Generate Secure Message MAC over suppiled message dataSecureDESKey
importKey(short keyLength, java.lang.String keyType, byte[] encryptedKey, SecureDESKey kek, boolean checkParity)
Imports a key from encryption under a KEK (Key-Encrypting Key) to protection under the security module.SecureKey
importKey(SecureKey kek, SecureKey key, SecureKeySpec keySpec, boolean checkParity)
Imports a key from encryption under a KEK (Key-Encrypting Key) to protection under the security module.EncryptedPIN
importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk)
Deprecated.Use signature that specifies tdes flag.EncryptedPIN
importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, boolean tdes)
Imports a PIN from encryption under a transaction key to encryption under LMK.EncryptedPIN
importPIN(EncryptedPIN pinUnderKd1, T kd1)
Imports a PIN from encryption under KD (Data Key) to encryption under LMK.void
printPIN(java.lang.String accountNo, EncryptedPIN pinUnderKd1, T kd1, java.lang.String template, java.util.Map<java.lang.String,java.lang.String> fields)
Print PIN or PIN and solicitation data to the HSM configured printer.SecureDESKey
translateKeyFromOldLMK(SecureDESKey kd)
Translate key from encryption under the LMK held in key change storage to encryption under a new LMK.SecureKey
translateKeyFromOldLMK(SecureKey key, SecureKeySpec keySpec)
Translate key from encryption under the LMK held in key change storage to encryption under a new LMK.SecureDESKey
translateKeyScheme(SecureDESKey key, KeyScheme keyScheme)
Translate Key Scheme to more secure encription.EncryptedPIN
translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat)
Deprecated.Use signature that specifies tdes flag.EncryptedPIN
translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, T bdk, T kd2, byte destinationPINBlockFormat, boolean tdes)
Translates a PIN from encryption under a transaction key to encryption under a KD (Data Key).EncryptedPIN
translatePIN(EncryptedPIN pinUnderKd1, T kd1, T kd2, byte destinationPINBlockFormat)
Translates a PIN from encrytion under KD1 to encryption under KD2.org.javatuples.Pair<EncryptedPIN,byte[]>
translatePINGenerateSM_MAC(MKDMethod mkdm, SKDMethod skdm, PaddingMethod padm, T imksmi, java.lang.String accountNo, java.lang.String acctSeqNo, byte[] atc, byte[] arqc, byte[] data, EncryptedPIN currentPIN, EncryptedPIN newPIN, T kd1, T imksmc, T imkac, byte destinationPINBlockFormat)
Translate PIN and generate MAC over suppiled message databoolean
verifyARQC(MKDMethod mkdm, SKDMethod skdm, T imkac, java.lang.String accountNo, java.lang.String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] txnData)
Verify Application Cryptogram (ARQC or TC/AAC) Authorization Request Cryptogram (ARQC) - Online authorization Transaction certificate (TC) - Offline approval Application Authentication Cryptogram (AAC) - Offline declinebyte[]
verifyARQCGenerateARPC(MKDMethod mkdm, SKDMethod skdm, T imkac, java.lang.String accountNo, java.lang.String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] txnData, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData)
Verify Application Cryptogram (ARQC or TC/AAC) and Genarate Authorisation Response Cryptogram (ARPC) Authorization Request Cryptogram (ARQC) - Online authorization Transaction certificate (TC) - Offline approval Application Authentication Cryptogram (AAC) - Offline declineboolean
verifyCAVV(java.lang.String accountNo, T cvk, java.lang.String cavv, java.lang.String upn, java.lang.String authrc, java.lang.String sfarc)
Verify a 3-D Secure CAVV/AAV.boolean
verifyCVC3(T imkcvc3, java.lang.String accountNo, java.lang.String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm, java.lang.String cvc3)
Verify a Dynamic Card Verification Code 3 (CVC3)boolean
verifyCVD(java.lang.String accountNo, T cvkA, T cvkB, java.lang.String cvv, java.lang.String expDate, java.lang.String serviceCode)
Verify a Card Verification Digit (Code/Value).boolean
verifyCVV(java.lang.String accountNo, T cvkA, T cvkB, java.lang.String cvv, java.util.Date expDate, java.lang.String serviceCode)
Deprecated.Issuers do not always follow the recommended 'yyMM' format.boolean
verifydCVV(java.lang.String accountNo, T imkac, java.lang.String dcvv, java.lang.String expDate, java.lang.String serviceCode, byte[] atc, MKDMethod mkdm)
Verify a Dynamic Card Verification Value (dCVV).boolean
verifydCVV(java.lang.String accountNo, T imkac, java.lang.String dcvv, java.util.Date expDate, java.lang.String serviceCode, byte[] atc, MKDMethod mkdm)
Deprecated.Issuers do not always follow the recommended 'yyMM' format.boolean
verifyIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, java.lang.String offset, java.lang.String decTab, java.lang.String pinValData, int minPinLen)
Verify an PIN Offset using the IBM 3624 methodboolean
verifyPVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvki, java.lang.String pvv)
Verify PVV (VISA PIN Verification Value of an LMK encrypted PIN)
-
-
-
Field Detail
-
LENGTH_DES
static final short LENGTH_DES
DES Key LengthLENGTH_DES
= 64.- See Also:
- Constant Field Values
-
LENGTH_DES3_2KEY
static final short LENGTH_DES3_2KEY
Triple DES (2 keys)LENGTH_DES3_2KEY
= 128.- See Also:
- Constant Field Values
-
LENGTH_DES3_3KEY
static final short LENGTH_DES3_3KEY
Triple DES (3 keys)LENGTH_DES3_3KEY
= 192.- See Also:
- Constant Field Values
-
TYPE_ZMK
static final java.lang.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:
- Constant Field Values
-
TYPE_ZPK
static final java.lang.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:
- Constant Field Values
-
TYPE_TMK
static final java.lang.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:
- Constant Field Values
-
TYPE_TPK
static final java.lang.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:
- Constant Field Values
-
TYPE_TAK
static final java.lang.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:
- Constant Field Values
-
TYPE_PVK
static final java.lang.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:
- Constant Field Values
-
TYPE_CVK
static final java.lang.String TYPE_CVK
CVK: Card Verification Key. is similar for PVK but for card information instead of PIN- See Also:
- Constant Field Values
-
TYPE_BDK
static final java.lang.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:
- Constant Field Values
-
TYPE_ZAK
static final java.lang.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:
- Constant Field Values
-
TYPE_MK_AC
static final java.lang.String TYPE_MK_AC
MK-AC: Issuer Master Key for generating and verifying Application Cryptograms.- See Also:
- Constant Field Values
-
TYPE_MK_SMI
static final java.lang.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:
- Constant Field Values
-
TYPE_MK_SMC
static final java.lang.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:
- Constant Field Values
-
TYPE_MK_CVC3
static final java.lang.String TYPE_MK_CVC3
MK-CVC3: Issuer Master Key for generating and verifying Card Verification Code 3 (CVC3).- See Also:
- Constant Field Values
-
TYPE_MK_DAC
static final java.lang.String TYPE_MK_DAC
MK-DAC Issuer Master Key for generating and verifying Data Authentication Codes.- See Also:
- Constant Field Values
-
TYPE_MK_DN
static final java.lang.String TYPE_MK_DN
MK-DN: Issuer Master Key for generating and verifying Dynamic Numbers.- See Also:
- Constant Field Values
-
TYPE_ZEK
static final java.lang.String TYPE_ZEK
ZEK: Zone Encryption Key.- See Also:
- Constant Field Values
-
TYPE_DEK
static final java.lang.String TYPE_DEK
DEK: Data Encryption Key.- See Also:
- Constant Field Values
-
TYPE_RSA_SK
static final java.lang.String TYPE_RSA_SK
RSA: Private Key.- See Also:
- Constant Field Values
-
TYPE_HMAC
static final java.lang.String TYPE_HMAC
HMAC: Hash Message Authentication Code (with key usage).- See Also:
- Constant Field Values
-
TYPE_RSA_PK
static final java.lang.String TYPE_RSA_PK
RSA: Public Key.- See Also:
- Constant Field Values
-
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:
- Constant Field Values
-
FORMAT02
static final byte FORMAT02
PIN Block Format 02 supports Douctel ATMs.- See Also:
- Constant Field Values
-
FORMAT03
static final byte FORMAT03
PIN Block Format 03 is the Diabold Pin Block format.- See Also:
- Constant Field Values
-
FORMAT04
static final byte FORMAT04
PIN Block Format 04 is the PIN block format adopted by the PLUS network.- See Also:
- Constant Field Values
-
FORMAT05
static final byte FORMAT05
PIN Block Format 05 is the ISO 9564-1 Format 1 PIN Block.- See Also:
- Constant Field Values
-
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:
- Constant Field Values
-
FORMAT35
static final byte FORMAT35
PIN Block Format 35 is the required by Europay/MasterCard for their Pay Now & Pay Later products.- See Also:
- Constant Field Values
-
FORMAT41
static final byte FORMAT41
PIN Block Format 41 is the Visa format for PIN change without using the current PIN.- See Also:
- Constant Field Values
-
FORMAT42
static final byte FORMAT42
PIN Block Format 42 is the Visa format for PIN change using the current (old) PIN.- See Also:
- Constant Field Values
-
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:
- Constant Field Values
-
-
Method Detail
-
generateKey
SecureDESKey generateKey(short keyLength, java.lang.String keyType) throws SMException
Generates a random DES Key.- Parameters:
keyType
- type of the key to be generated (TYPE_ZMK, TYPE_TMK...etc)keyLength
- bit length of the key to be generated (LENGTH_DES, LENGTH_DES3_2KEY...)- 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:
SecureKeySpec
-
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 todestKeyScheme
schemekeyScheme
- destination key scheme- Returns:
- translated key with
destKeyScheme
scheme - Throws:
SMException
-
importKey
SecureDESKey importKey(short keyLength, java.lang.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 KEKkek
- the key-encrypting keycheckParity
- 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 keykey
- key to be imported and encrypted under KEKkeySpec
- the specification of the key to be imported. It allows passing or change key block attributes.checkParity
- iftrue
, 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 andcheckParity
istrue
-
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 exportedkek
- 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 keykey
- the secure key to be exportedkeySpec
- 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(java.lang.String pin, java.lang.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 holderaccountNumber
- account number, including BIN and the check digit- Returns:
- PIN under LMK
- Throws:
SMException
-
encryptPIN
EncryptedPIN encryptPIN(java.lang.String pin, java.lang.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 cardholderaccountNumber
- ifextract
is false then account number, including BIN and the check digit or if parameterextract
is true then 12 right-most digits of the account number, excluding the check digitextract
- true to extract 12 right-most digits off the account number- Returns:
- PIN under LMK
- Throws:
SMException
-
encryptPIN
EncryptedPIN encryptPIN(java.lang.String pin, java.lang.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
java.lang.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 PINkd1
- 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 KD1kd1
- Data Key (also called session key) under which the pin is encryptedkd2
- the destination Data Key 2 under which the pin will be encrypteddestinationPINBlockFormat
- the PIN Block Format of the exported encrypted PIN- Returns:
- pin encrypted under KD2
- Throws:
SMException
-
importPIN
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 keyksn
- Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction keybdk
- 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 keyksn
- Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction keybdk
- Base Derivation Key, used to derive the transaction key underwhich the pin is encryptedtdes
- Use Triple DES to calculate derived transaction key.- Returns:
- pin encrypted under LMK
- Throws:
SMException
-
translatePIN
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 keyksn
- Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction keybdk
- Base Derivation Key, used to derive the transaction key underwhich the pin is encryptedkd2
- the destination Data Key (also called session key) under which the pin will be encrypteddestinationPINBlockFormat
- 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 keyksn
- Key Serial Number (also called Key Name, in ANSI X9.24) needed to derive the transaction keybdk
- Base Derivation Key, used to derive the transaction key underwhich the pin is encryptedkd2
- the destination Data Key (also called session key) under which the pin will be encrypteddestinationPINBlockFormat
- the PIN Block Format of the translated encrypted PINtdes
- 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 LMKkd2
- the destination data key (also called session key) under which the pin will be encrypteddestinationPINBlockFormat
- the PIN Block Format of the exported encrypted PIN- Returns:
- pin encrypted under kd2
- Throws:
SMException
-
generatePIN
EncryptedPIN generatePIN(java.lang.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 digitpinLen
- 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(java.lang.String accountNumber, int pinLen, java.util.List<java.lang.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 digitpinLen
- 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 bepinLen
length- Returns:
- generated PIN under LMK
- Throws:
SMException
-
printPIN
void printPIN(java.lang.String accountNo, EncryptedPIN pinUnderKd1, T kd1, java.lang.String template, java.util.Map<java.lang.String,java.lang.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 1kd1
- Data Key 1 ZPK, TPK may be null ifpinUnderKd1
contains PIN under LMKtemplate
- 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 infields
map argument except PIN which is passed in argumentpinUnderKd1
.fields
- map of tags values representing solicitation data to include in template. null if no solicitation data are passed- Throws:
SMException
-
calculatePVV
java.lang.String calculatePVV(EncryptedPIN pinUnderLmk, T pvkA, T pvkB, int pvkIdx) throws SMException
Calculate PVV (VISA PIN Verification Value of PIN under LMK) with exclude listNOTE:
pvkA
andpvkB
should be single length keys but at least one of them may be double length key- Parameters:
pinUnderLmk
- PIN under LMKpvkA
- first key PVK in PVK pairpvkB
- second key PVK in PVK pairpvkIdx
- 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 listWeakPINException
is thrown
-
calculatePVV
java.lang.String calculatePVV(EncryptedPIN pinUnderLmk, T pvkA, T pvkB, int pvkIdx, java.util.List<java.lang.String> excludes) throws SMException
Calculate PVV (VISA PIN Verification Value of PIN under LMK)NOTE:
pvkA
andpvkB
should be single length keys but at least one of them may be double length key- Parameters:
pinUnderLmk
- PIN under LMKpvkA
- first key PVK in PVK pairpvkB
- second key PVK in PVK pairpvkIdx
- index of the PVK, in range 0-6, if not present 0 is assumedexcludes
- list of pins which won't be generated. Each pin has to bepinLen
length- Returns:
- PVV (VISA PIN Verification Value)
- Throws:
SMException
-
calculatePVV
java.lang.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
andpvkB
should be single length keys but at least one of them may be double length key- Parameters:
pinUnderKd1
- the encrypted PINkd1
- Data Key under which the pin is encryptedpvkA
- first key PVK in PVK pairpvkB
- second key PVK in PVK pairpvkIdx
- index of the PVK, in range 0-6, if not present 0 is assumed- Returns:
- PVV (VISA PIN Verification Value)
- Throws:
SMException
-
calculatePVV
java.lang.String calculatePVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvkIdx, java.util.List<java.lang.String> excludes) throws SMException
Calculate PVV (VISA PIN Verification Value of customer selected PIN)NOTE:
pvkA
andpvkB
should be single length keys but at least one of them may be double length key- Parameters:
pinUnderKd1
- the encrypted PINkd1
- Data Key under which the pin is encryptedpvkA
- first key PVK in PVK pairpvkB
- second key PVK in PVK pairpvkIdx
- index of the PVK, in range 0-6, if not present 0 is assumedexcludes
- list of pins which won't be generated. Each pin has to bepinLen
length- Returns:
- PVV (VISA PIN Verification Value)
- Throws:
WeakPINException
- if passed PIN is onexcludes
listSMException
-
verifyPVV
boolean verifyPVV(EncryptedPIN pinUnderKd1, T kd1, T pvkA, T pvkB, int pvki, java.lang.String pvv) throws SMException
Verify PVV (VISA PIN Verification Value of an LMK encrypted PIN)NOTE:
pvkA
andpvkB
should be single length keys but at least one of them may be double length key- Parameters:
pinUnderKd1
- pin block underkd1
kd1
- Data Key (also called session key) under which the pin is encrypted (ZPK or TPK)pvkA
- first PVK in PVK pairpvkB
- second PVK in PVK pairpvki
- index of the PVK, in range 0-6, if not present 0 is assumedpvv
- (VISA PIN Verification Value)- Returns:
- true if pin is valid false if not
- Throws:
SMException
-
calculateIBMPINOffset
java.lang.String calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, java.lang.String decTab, java.lang.String pinValData, int minPinLen) throws SMException
Calculate an PIN Offset using the IBM 3624 methodUsing that method is not recomendated. PVV method is prefrred, but it may be need in some legacy systms
- Parameters:
pinUnderLmk
- PIN under LMKpvk
- accepts single, double, triple size key length. Single key length is recomendateddecTab
- decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configurationpinValData
- 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 numberminPinLen
- pin minimal length- Returns:
- IBM PIN Offset
- Throws:
SMException
-
calculateIBMPINOffset
java.lang.String calculateIBMPINOffset(EncryptedPIN pinUnderLmk, T pvk, java.lang.String decTab, java.lang.String pinValData, int minPinLen, java.util.List<java.lang.String> excludes) throws SMException
Calculate an PIN Offset using the IBM 3624 methodUsing that method is not recomendated. PVV method is prefrred, but it may be need in some legacy systms
- Parameters:
pinUnderLmk
- PIN under LMKpvk
- accepts single, double, triple size key length. Single key length is recomendateddecTab
- decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configurationpinValData
- 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 numberminPinLen
- pin minimal lengthexcludes
- list of pins which won't be generated. Each pin has to bepinLen
length- Returns:
- IBM PIN Offset
- Throws:
WeakPINException
- if passed PIN is onexcludes
listSMException
-
calculateIBMPINOffset
java.lang.String calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, java.lang.String decTab, java.lang.String pinValData, int minPinLen) throws SMException
Calculate an PIN Offset using the IBM 3624 method of customer selected PINUsing that method is not recomendated. PVV method is prefrred, but it may be need in some legacy systms
- Parameters:
pinUnderKd1
- the encrypted PINkd1
- Data Key under which the pin is encryptedpvk
- accepts single, double, triple size key length. Single key length is recomendateddecTab
- decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configurationpinValData
- 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 numberminPinLen
- pin minimal length- Returns:
- IBM PIN Offset
- Throws:
SMException
-
calculateIBMPINOffset
java.lang.String calculateIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, java.lang.String decTab, java.lang.String pinValData, int minPinLen, java.util.List<java.lang.String> excludes) throws SMException
Calculate an PIN Offset using the IBM 3624 method of customer selected PINUsing that method is not recomendated. PVV method is prefrred, but it may be need in some legacy systms
- Parameters:
pinUnderKd1
- the encrypted PINkd1
- Data Key under which the pin is encryptedpvk
- accepts single, double, triple size key length. Single key length is recomendateddecTab
- decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configurationpinValData
- 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 numberminPinLen
- pin minimal lengthexcludes
- list of pins which won't be generated. Each pin has to bepinLen
length- Returns:
- IBM PIN Offset
- Throws:
WeakPINException
- if passed PIN is onexcludes
listSMException
-
verifyIBMPINOffset
boolean verifyIBMPINOffset(EncryptedPIN pinUnderKd1, T kd1, T pvk, java.lang.String offset, java.lang.String decTab, java.lang.String pinValData, int minPinLen) throws SMException
Verify an PIN Offset using the IBM 3624 method- Parameters:
pinUnderKd1
- pin block underkd1
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 recomendatedoffset
- IBM PIN OffsetdecTab
- decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configurationpinValData
- 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 numberminPinLen
- min pin length- Returns:
- true if pin offset is valid false if not
- Throws:
SMException
-
deriveIBMPIN
EncryptedPIN deriveIBMPIN(java.lang.String accountNo, T pvk, java.lang.String decTab, java.lang.String pinValData, int minPinLen, java.lang.String offset) throws SMException
Derive a PIN Using the IBM 3624 methodThat 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 digitpvk
- accepts single, double, triple size key length. Single key length is recomendateddecTab
- decimalisation table. Accepts plain text and encrypted decimalisation table depending to HSM configurationpinValData
- 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 numberminPinLen
- min pin lengthoffset
- IBM PIN Offset- Returns:
- PIN under LMK
- Throws:
SMException
-
calculateCVV
@Deprecated java.lang.String calculateCVV(java.lang.String accountNo, T cvkA, T cvkB, java.util.Date expDate, java.lang.String serviceCode) throws SMException
Deprecated.Issuers do not always follow the recommended 'yyMM' format. Using thejava.util.Date
prevents from format manipulating to solve problem. UsecalculateCVD(java.lang.String, T, T, java.lang.String, java.lang.String)
with string version ofexpDate
Calaculate a Card Verification Code/Value.NOTE:
cvkA
andcvkB
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 digitcvkA
- the first CVK in CVK paircvkB
- the second CVK in CVK pairexpDate
- the card expiration dateserviceCode
- 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
java.lang.String calculateCVD(java.lang.String accountNo, T cvkA, T cvkB, java.lang.String expDate, java.lang.String serviceCode) throws SMException
Calaculate a Card Verification Digit (Code/Value).NOTE:
cvkA
andcvkB
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 digitcvkA
- the first CVK in CVK paircvkB
- the second CVK in CVK pairexpDate
- the card expiration dateserviceCode
- 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
java.lang.String calculateCAVV(java.lang.String accountNo, T cvk, java.lang.String upn, java.lang.String authrc, java.lang.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
andserviceCode
.- Parameters:
accountNo
- the account number including BIN and the check digit.cvk
- the key used to CVV/CVC generationupn
- 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(java.lang.String accountNo, T cvkA, T cvkB, java.lang.String cvv, java.util.Date expDate, java.lang.String serviceCode) throws SMException
Deprecated.Issuers do not always follow the recommended 'yyMM' format. Using thejava.util.Date
prevents from format manipulating to solve problem. UseverifyCVD(java.lang.String, T, T, java.lang.String, java.lang.String, java.lang.String)
with string version ofexpDate
Verify a Card Verification Code/Value.NOTE:
cvkA
andcvkB
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 digitcvkA
- the first CVK in CVK paircvkB
- the second CVK in CVK paircvv
- Card Verification Code/ValueexpDate
- the card expiration dateserviceCode
- 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(java.lang.String accountNo, T cvkA, T cvkB, java.lang.String cvv, java.lang.String expDate, java.lang.String serviceCode) throws SMException
Verify a Card Verification Digit (Code/Value).NOTE:
cvkA
andcvkB
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 digitcvkA
- the first CVK in CVK paircvkB
- the second CVK in CVK paircvv
- Card Verification Code/ValueexpDate
- the card expiration dateserviceCode
- 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 orfalse
otherwise- Throws:
SMException
-
verifyCAVV
boolean verifyCAVV(java.lang.String accountNo, T cvk, java.lang.String cavv, java.lang.String upn, java.lang.String authrc, java.lang.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
andserviceCode
.- Parameters:
accountNo
- the account number including BIN and the check digit.cvk
- the key used to CVV/CVC generationcavv
- 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(java.lang.String accountNo, T imkac, java.lang.String dcvv, java.util.Date expDate, java.lang.String serviceCode, byte[] atc, MKDMethod mkdm) throws SMException
Deprecated.Issuers do not always follow the recommended 'yyMM' format. Using thejava.util.Date
prevents from format manipulating to solve problem. UseverifydCVV(java.lang.String, T, java.lang.String, java.util.Date, java.lang.String, byte[], org.jpos.security.MKDMethod)
with string version ofexpDate
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 digitimkac
- the issuer master key for generating and verifying Application Cryptogramsdcvv
- dynamic Card Verification ValueexpDate
- the card expiration dateserviceCode
- the card service codeatc
- application transactin counter. This is used for ICC Master Key derivation. A 2 byte value must be supplied.mkdm
- ICC Master Key Derivation Method. Ifnull
specified is assumed.- Returns:
true
ifdcvv
is valid, orfalse
if not- Throws:
SMException
-
verifydCVV
boolean verifydCVV(java.lang.String accountNo, T imkac, java.lang.String dcvv, java.lang.String expDate, java.lang.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 digitimkac
- the issuer master key for generating and verifying Application Cryptogramsdcvv
- dynamic Card Verification ValueexpDate
- the card expiration dateserviceCode
- the card service codeatc
- application transactin counter. This is used for ICC Master Key derivation. A 2 byte value must be supplied.mkdm
- ICC Master Key Derivation Method. Ifnull
specified is assumed.- Returns:
true
ifdcvv
is valid, orfalse
if not- Throws:
SMException
-
-
verifyCVC3
boolean verifyCVC3(T imkcvc3, java.lang.String accountNo, java.lang.String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm, java.lang.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 CVC3accountNo
- The account number including BIN and the check digitacctSeqNo
- account sequence number, 2 decimal digitsatc
- 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. Ifnull
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, java.lang.String accountNo, java.lang.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. Forskdm
equalsSKDMethod.VSDC
andSKDMethod.MCHIP
this parameter is ignored andMKDMethod.OPTION_A
is always used.skdm
- Session Key Derivation Methodimkac
- the issuer master key for generating and verifying Application CryptogramsaccountNo
- account number including BIN and check digitacctSeqNo
- account sequence number, 2 decimal digitsarqc
- 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. Forskdm
equalsSKDMethod.VSDC
is not used.upn
- unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied. Forskdm
equalsSKDMethod.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, java.lang.String accoutNo, java.lang.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. Forskdm
equalsSKDMethod.VSDC
andSKDMethod.MCHIP
this parameter is ignored andMKDMethod.OPTION_A
is always used.skdm
- Session Key Derivation Methodimkac
- the issuer master key for generating and verifying Application CryptogramsaccoutNo
- account number including BIN and check digitacctSeqNo
- account sequence number, 2 decimal digitsarqc
- 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. Forskdm
equalsSKDMethod.VSDC
is not used.upn
- unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied. Forskdm
equalsSKDMethod.VSDC
is not used.arpcMethod
- ARPC calculating method. Forskdm
equalsSKDMethod.VSDC
,SKDMethod.MCHIP
,SKDMethod.AEPIS_V40
onlyARPCMethod.METHOD_1
is validarc
- the Authorisation Response Code. A 2 byte value must be supplied. ForarpcMethod
equalsARPCMethod.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 forarpcMethod
equalsARPCMethod.METHOD_2
in other case is ignored.- Returns:
- calculated 8 bytes ARPC or if
arpcMethod
equalsARPCMethod.METHOD_2
4 bytes ARPC - Throws:
SMException
-
verifyARQCGenerateARPC
byte[] verifyARQCGenerateARPC(MKDMethod mkdm, SKDMethod skdm, T imkac, java.lang.String accountNo, java.lang.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. Forskdm
equalsSKDMethod.VSDC
andSKDMethod.MCHIP
this parameter is ignored andMKDMethod.OPTION_A
is always used.skdm
- Session Key Derivation Methodimkac
- the issuer master key for generating and verifying Application CryptogramsaccountNo
- account number including BIN and check digitacctSeqNo
- account sequence number, 2 decimal digitsarqc
- 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. Forskdm
equalsSKDMethod.VSDC
is not used.upn
- unpredictable number. This is used for Session Key Generation A 4 byte value must be supplied. Forskdm
equalsSKDMethod.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. Forskdm
equalsSKDMethod.VSDC
,SKDMethod.MCHIP
,SKDMethod.AEPIS_V40
onlyARPCMethod.METHOD_1
is validarc
- the Authorisation Response Code. A 2 byte value must be supplied. ForarpcMethod
equalsARPCMethod.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 forarpcMethod
equalsARPCMethod.METHOD_2
in other case is ignored.- Returns:
- if ARQC/TC/AAC verification passed then calculated 8 bytes ARPC
or for
arpcMethod
equalsARPCMethod.METHOD_2
4 bytes ARPC, null in other case - Throws:
SMException
-
generateSM_MAC
byte[] generateSM_MAC(MKDMethod mkdm, SKDMethod skdm, T imksmi, java.lang.String accountNo, java.lang.String acctSeqNo, byte[] atc, byte[] arqc, byte[] data) throws SMException
Generate Secure Message MAC over suppiled message dataThis 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. Forskdm
equalsSKDMethod.VSDC
andSKDMethod.MCHIP
this parameter is ignored andMKDMethod.OPTION_A
is always used.skdm
- Session Key Derivation Methodimksmi
- the issuer master key for Secure Messaging IntegrityaccountNo
- account number including BIN and check digitacctSeqNo
- account sequence number, 2 decimal digitsatc
- application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. Forskdm
equalsSKDMethod.VSDC
is not used. Second usage is as part of data which will be mackedarqc
- ARQC/TC/AAC. A 8 byte value must be supplied. Forskdm
equalsSKDMethod.MCHIP
RAND should be suppiled. RAND is ARQC incremeted by 1 (with overflow) after each script command for that same ATC valuedata
- 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, java.lang.String accountNo, java.lang.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 dataThis 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 fromimksmc
- generate MAC over suppiled message
data
and translated PIN block
- Parameters:
mkdm
- ICC Master Key Derivation Method. Forskdm
equalsSKDMethod.VSDC
andSKDMethod.MCHIP
this parameter is ignored andMKDMethod.OPTION_A
is always used.skdm
- Session Key Derivation Methodpadm
- padding method. If nullpadm
is derived as follow:skdm
valuederived padm
valueSKDMethod.VSDC
PaddingMethod.VSDC
SKDMethod.MCHIP
PaddingMethod.MCHIP
SKDMethod.EMV_CSKD
PaddingMethod.CCD
padm
valueimksmi
- the issuer master key for Secure Messaging IntegrityaccountNo
- account number including BIN and check digitacctSeqNo
- account sequence number, 2 decimal digitsatc
- application transactin counter. This is used for Session Key Generation. A 2 byte value must be supplied. Forskdm
equalsSKDMethod.VSDC
is not used. Second usage is as part of data which will be mackedarqc
- ARQC/TC/AAC. A 8 byte value must be supplied. Forskdm
equalsSKDMethod.MCHIP
RAND should be suppiled. RAND is ARQC incremeted by 1 (with overflow) after each script command for that same ATC valuedata
- for which MAC will be generated. Should contain APDU command PIN Change with some additional application dependent datacurrentPIN
- encrypted underkd1
current PIN. Used whendestinationPINBlockFormat
equalsFORMAT42
newPIN
- encrypted underkd1
new PIN.kd1
- Data Key (also called transport key) under which the source pin is encryptedimksmc
- the issuer master key for Secure Messaging Confidentialityimkac
- the issuer master key for generating and verifying Application Cryptograms. Used whendestinationPINBlockFormat
equalsFORMAT41
orFORMAT42
in other cases is ignoreddestinationPINBlockFormat
- the PIN Block Format of the translated encrypted PIN- Returns:
- Pair of values, encrypted PIN and 8 bytes MAC
- Throws:
SMException
- translate standard ATM PIN block format encrypted under zone
or terminal key
-
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 forCipherMode.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 forCipherMode.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 MACedkd
- 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 MACedkd
- 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 LMKkeySpec
- 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<java.security.PublicKey,SecurePrivateKey> generateKeyPair(java.security.spec.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<java.security.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()
orkeySpec.setReserved()
- Returns:
- key pair generated according to passed parameters
- Throws:
SMException
-
calculateSignature
byte[] calculateSignature(java.security.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, java.security.spec.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
- when RSA public key encapsulated in
data
- clear data block to encryptalgspec
- algorithm specification ornull
if not required. Used to pass additional algorithm parameters e.g:OAEPParameterSpec
or custom extension ofAlgorithmParameterSpec
to pass symetric cipher mode ECB, CBCiv
- the inital vector ornull
if not used (e.g: RSA cipher or ECB mode). If used, after operation will contain newiv
value.- Returns:
- encrypted data block
- Throws:
SMException
-
decryptData
byte[] decryptData(SecureKey decKey, byte[] data, java.security.spec.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
- when RSA private key encapsulated in
data
- encrypted data block to decryptalgspec
- algorithm specification ornull
if not required. Used to pass additional algorithm parameters e.g:OAEPParameterSpec
or custom extension ofAlgorithmParameterSpec
to pass symetric cipher mode ECB, CBCiv
- the inital vector ornull
if not used (e.g: RSA cipher or ECB mode). If used, after operation will contain newiv
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 keyclearText
- clear Text- Returns:
- cyphertext
- Throws:
SMException
-
dataDecrypt
byte[] dataDecrypt(T bdk, byte[] cypherText) throws SMException
Decrypt Data- Parameters:
bdk
- base derivation keycypherText
- clear Text- Returns:
- cleartext
- Throws:
SMException
-
formKEYfromClearComponents
SecureDESKey formKEYfromClearComponents(short keyLength, java.lang.String keyType, java.lang.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 java.lang.String generateClearKeyComponent(short keyLength) throws SMException
Generates a random clear key component.- Parameters:
keyLength
-- Returns:
- clear key componenet
- Throws:
SMException
-
-