org.jpos.security
Interface SMAdapter

All Known Implementing Classes:

BaseSMAdapter, JCESecurityModule

public interface SMAdapter

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.

Version:

$Revision$ $Date$

Author:

Hani S. Kirollos, Robert Demski

Field Summary

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 Length LENGTH_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 String	TYPE_BDK BDK: Base Derivation Key.
static String	TYPE_CVK CVK: Card Verification Key.
static String	TYPE_MK_AC MK-AC: Issuer Master Key for generating and verifying Application Cryptograms.
static String	TYPE_MK_CVC3 MK-CVC3: Issuer Master Key for generating and verifying Card Verification Code 3 (CVC3).
static String	TYPE_MK_SMC MK-SMC: Issuer Master Key for Secure Messaging Confidentiality.
static String	TYPE_MK_SMI MK-SMI: Issuer Master Key for Secure Messaging Integrity.
static String	TYPE_PVK PVK: PIN Verification Key.
static String	TYPE_TAK TAK: Terminal Authentication Key.
static String	TYPE_TMK TMK: Terminal Master Key.
static String	TYPE_TPK TPK: Terminal PIN Key.
static String	TYPE_ZAK ZAK: Zone Authentication Key.
static 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 String	TYPE_ZPK ZPK: Zone PIN Key.

Method Summary

String	calculateCVV(String accountNo, SecureDESKey cvkA, SecureDESKey cvkB, Date expDate, String serviceCode) Calaculate a Card Verification Code/Value NOTE: cvkA and cvkB should be single length keys but at least one of them may be double length key
String	calculateIBMPINOffset(EncryptedPIN pinUnderkd1, SecureDESKey kd1, SecureDESKey pvk, String decTab, String pinValData, int minPinLen) Calculate an PIN Offset using the IBM 3624 method of customer selected PIN Using that method is not recomendated.
String	calculateIBMPINOffset(EncryptedPIN pinUnderkd1, SecureDESKey kd1, SecureDESKey pvk, String decTab, String pinValData, int minPinLen, List<String> excludes) Calculate an PIN Offset using the IBM 3624 method of customer selected PIN Using that method is not recomendated.
String	calculateIBMPINOffset(EncryptedPIN pinUnderLmk, SecureDESKey pvk, String decTab, String pinValData, int minPinLen) Calculate an PIN Offset using the IBM 3624 method Using that method is not recomendated.
String	calculateIBMPINOffset(EncryptedPIN pinUnderLmk, SecureDESKey pvk, String decTab, String pinValData, int minPinLen, List<String> excludes) Calculate an PIN Offset using the IBM 3624 method Using that method is not recomendated.
String	calculatePVV(EncryptedPIN pinUnderLmk, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx) Calculate PVV (VISA PIN Verification Value of PIN under LMK) with exclude list NOTE: pvkA and pvkB should be single length keys but at least one of them may be double length key
String	calculatePVV(EncryptedPIN pinUnderLmk, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx, List<String> excludes) Calculate PVV (VISA PIN Verification Value of PIN under LMK) NOTE: pvkA and pvkB should be single length keys but at least one of them may be double length key
String	calculatePVV(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx) Calculate PVV (VISA PIN Verification Value of customer selected PIN) NOTE: pvkA and pvkB should be single length keys but at least one of them may be double length key
String	calculatePVV(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx, List<String> excludes) Calculate PVV (VISA PIN Verification Value of customer selected PIN) NOTE: pvkA and pvkB should be single length keys but at least one of them may be double length key
String	decryptPIN(EncryptedPIN pinUnderLmk) Decrypts an Encrypted PIN (under LMK).
EncryptedPIN	deriveIBMPIN(String accountNo, SecureDESKey pvk, String decTab, String pinValData, int minPinLen, String offset) Derive a PIN Using the IBM 3624 method That method derive pin from pin offset (not exacly that same but working).
EncryptedPIN	encryptPIN(String pin, String accountNumber) Encrypts a clear pin under LMK.
EncryptedPIN	encryptPIN(String pin, String accountNumber, boolean extract) Encrypts a clear pin under LMK.
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).
EncryptedPIN	exportPIN(EncryptedPIN pinUnderLmk, SecureDESKey kd2, byte destinationPINBlockFormat) Exports a PIN from encryption under LMK to encryption under a KD (Data Key).
byte[]	generateARPC(MKDMethod mkdm, SKDMethod skdm, SecureDESKey imkac, String accoutNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData) Genarate Authorisation Response Cryptogram (ARPC)
byte[]	generateCBC_MAC(byte[] data, SecureDESKey kd) Generates CBC-MAC (Cipher Block Chaining Message Authentication Code) for some data.
byte[]	generateEDE_MAC(byte[] data, SecureDESKey kd) Generates EDE-MAC (Encrypt Decrypt Encrypt Message Message Authentication Code) for some data.
SecureDESKey	generateKey(short keyLength, String keyType) Generates a random DES Key.
byte[]	generateKeyCheckValue(SecureDESKey kd) Generates key check value.
EncryptedPIN	generatePIN(String accountNumber, int pinLen) Generate random pin under LMK
EncryptedPIN	generatePIN(String accountNumber, int pinLen, List<String> excludes) Generate random pin under LMK with exclude list
byte[]	generateSM_MAC(MKDMethod mkdm, SKDMethod skdm, SecureDESKey imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data) Generate Secure Message MAC over suppiled message data This method is used by issuer to generate MAC over message data send from the issuer back to the card
SecureDESKey	importKey(short keyLength, String keyType, byte[] encryptedKey, SecureDESKey kek, boolean checkParity) Imports a key from encryption under a KEK (Key-Encrypting Key) to protection under the security module.
EncryptedPIN	importPIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, SecureDESKey bdk) Imports a PIN from encryption under a transaction key to encryption under LMK.
EncryptedPIN	importPIN(EncryptedPIN pinUnderKd1, SecureDESKey kd1) Imports a PIN from encryption under KD (Data Key) to encryption under LMK.
SecureDESKey	translateKeyFromOldLMK(SecureDESKey kd) Translate key from encryption under the LMK held in “key change storage” to encryption under a new LMK.
EncryptedPIN	translatePIN(EncryptedPIN pinUnderDuk, KeySerialNumber ksn, SecureDESKey bdk, SecureDESKey kd2, byte destinationPINBlockFormat) Translates a PIN from encryption under a transaction key to encryption under a KD (Data Key).
EncryptedPIN	translatePIN(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey kd2, byte destinationPINBlockFormat) Translates a PIN from encrytion under KD1 to encryption under KD2.
org.javatuples.Pair<EncryptedPIN,byte[]>	translatePINGenerateSM_MAC(MKDMethod mkdm, SKDMethod skdm, SecureDESKey imksmi, String accountNo, String acctSeqNo, byte[] atc, byte[] arqc, byte[] data, EncryptedPIN currentPIN, EncryptedPIN newPIN, SecureDESKey kd1, SecureDESKey imksmc, SecureDESKey imkac, byte destinationPINBlockFormat) Translate PIN and generate MAC over suppiled message data This method is used by issuer to: translate standard ATM PIN block format encrypted under zone or terminal key kd1 to an application specific PIN block format, encrypted under a confidentiality session key, derived from imksmc generate MAC over suppiled message data and translated PIN block
boolean	verifyARQC(MKDMethod mkdm, SKDMethod skdm, SecureDESKey imkac, String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] transData) Verify Application Cryptogram (ARQC or TC/AAC) Authorization Request Cryptogram (ARQC) - Online authorization Transaction certificate (TC) - Offline approval Application Authentication Cryptogram (AAC) - Offline decline
byte[]	verifyARQCGenerateARPC(MKDMethod mkdm, SKDMethod skdm, SecureDESKey imkac, String accountNo, String acctSeqNo, byte[] arqc, byte[] atc, byte[] upn, byte[] transData, ARPCMethod arpcMethod, byte[] arc, byte[] propAuthData) Verify Application Cryptogram (ARQC or TC/AAC) and Genarate Authorisation Response Cryptogram (ARPC) Authorization Request Cryptogram (ARQC) - Online authorization Transaction certificate (TC) - Offline approval Application Authentication Cryptogram (AAC) - Offline decline
boolean	verifyCVC3(SecureDESKey imkcvc3, String accountNo, String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm, String cvc3) Verify a Dynamic Card Verification Code 3 (CVC3)
boolean	verifyCVV(String accountNo, SecureDESKey cvkA, SecureDESKey cvkB, String cvv, Date expDate, String serviceCode) Verify a Card Verification Code/Value NOTE: cvkA and cvkB should be single length keys but at least one of them may be double length key
boolean	verifydCVV(String accountNo, SecureDESKey imkac, String dcvv, Date expDate, String serviceCode, byte[] atc, MKDMethod mkdm) Verify a Dynamic Card Verification Value (CVV) The EMV "Track 2 Equivalent Data", provided in the authorisation message and originating from the contactless smart card, is the source for the following data elements used in this function: accountNo expDate serviceCode atc dCVV
boolean	verifyIBMPINOffset(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvk, String offset, String decTab, String pinValData, int minPinLen) Verify an PIN Offset using the IBM 3624 method
boolean	verifyPVV(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvkA, SecureDESKey pvkB, int pvki, String pvv) Verify PVV (VISA PIN Verification Value of an LMK encrypted PIN) NOTE: pvkA and pvkB should be single length keys but at least one of them may be double length key

Field Detail

LENGTH_DES

static final short LENGTH_DES

DES Key Length LENGTH_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 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 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 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 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 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 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 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 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 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 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 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 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 String TYPE_MK_CVC3

MK-CVC3: Issuer Master Key for generating and verifying Card Verification Code 3 (CVC3).

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

generateKeyCheckValue

byte[] generateKeyCheckValue(SecureDESKey kd)
                             throws SMException

Generates key check value.

Parameters:

kd - SecureDESKey with untrusted or fake Key Check Value

Returns:

key check value bytes

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

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

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

accountNumber - if extract is false then account number, including BIN and the check digit or if parameter extract is true then 12 right-most digits of the account number, excluding the check digit

extract - true to extract 12 right-most digits off the account number

Returns:

PIN under LMK

Throws:

SMException

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

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

Returns:

pin encrypted under LMK

Throws:

SMException

translatePIN

EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk,
                          KeySerialNumber ksn,
                          SecureDESKey bdk,
                          SecureDESKey kd2,
                          byte destinationPINBlockFormat)
                          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

Returns:

pin encrypted under kd2

Throws:

SMException

exportPIN

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

calculatePVV

String calculatePVV(EncryptedPIN pinUnderLmk,
                    SecureDESKey pvkA,
                    SecureDESKey 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,
                    SecureDESKey pvkA,
                    SecureDESKey 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,
                    SecureDESKey kd1,
                    SecureDESKey pvkA,
                    SecureDESKey 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,
                    SecureDESKey kd1,
                    SecureDESKey pvkA,
                    SecureDESKey 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,
                  SecureDESKey kd1,
                  SecureDESKey pvkA,
                  SecureDESKey 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,
                             SecureDESKey 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,
                             SecureDESKey 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,
                             SecureDESKey kd1,
                             SecureDESKey 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,
                             SecureDESKey kd1,
                             SecureDESKey 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,
                           SecureDESKey kd1,
                           SecureDESKey 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,
                          SecureDESKey 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

String calculateCVV(String accountNo,
                    SecureDESKey cvkA,
                    SecureDESKey cvkB,
                    Date expDate,
                    String serviceCode)
                    throws SMException

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

verifyCVV

boolean verifyCVV(String accountNo,
                  SecureDESKey cvkA,
                  SecureDESKey cvkB,
                  String cvv,
                  Date expDate,
                  String serviceCode)
                  throws SMException

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 falid or false if not

Throws:

SMException

verifydCVV

boolean verifydCVV(String accountNo,
                   SecureDESKey imkac,
                   String dcvv,
                   Date expDate,
                   String serviceCode,
                   byte[] atc,
                   MKDMethod mkdm)
                   throws SMException

Verify a Dynamic Card Verification Value (CVV) The EMV "Track 2 Equivalent Data", provided in the authorisation message and originating from the contactless smart card, is the source for the following data elements used in this function:

accountNo

expDate

serviceCode

atc

dCVV

Parameters:

accountNo - The account number including BIN and the check digit

imkac - the issuer master key for generating and verifying Application Cryptograms

dcvv - dynamic Card Verification Value

expDate - the card expiration date

serviceCode - the card service code

atc - application transactin counter. This is used for ICC Master Key derivation. A 2 byte value must be supplied.

mkdm - ICC Master Key Derivation Method. If null specified is assumed MKDMethod.OPTION_A

Returns:

Throws:

SMException

verifyCVC3

boolean verifyCVC3(SecureDESKey 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 MKDMethod.OPTION_A

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:

Throws:

SMException

verifyARQC

boolean verifyARQC(MKDMethod mkdm,
                   SKDMethod skdm,
                   SecureDESKey imkac,
                   String accountNo,
                   String acctSeqNo,
                   byte[] arqc,
                   byte[] atc,
                   byte[] upn,
                   byte[] transData)
                   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.

transData - transaction data (without padding). Transaction data elements and them order is dependend to proper cryptogram version

Returns:

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

Throws:

SMException

generateARPC

byte[] generateARPC(MKDMethod mkdm,
                    SKDMethod skdm,
                    SecureDESKey imkac,
                    String accoutNo,
                    String acctSeqNo,
                    byte[] arqc,
                    byte[] atc,
                    byte[] upn,
                    ARPCMethod arpcMethod,
                    byte[] arc,
                    byte[] propAuthData)
                    throws SMException

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,
                              SecureDESKey imkac,
                              String accountNo,
                              String acctSeqNo,
                              byte[] arqc,
                              byte[] atc,
                              byte[] upn,
                              byte[] transData,
                              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.

transData - transaction data (without padding). Transaction data elements and them order is dependend to proper cryptogram version

arpcMethod - ARPC calculating method. For skdm equals SKDMethod.VSDC, SKDMethod.MCHIP, SKDMethod.AEPIS_V40 only ARPCMethod.METHOD_1 is valid

arc - the Authorisation Response Code. A 2 byte value must be supplied. For arpcMethod equals ARPCMethod.METHOD_2 it is csu - Card Status Update. Then a 4 byte value must be supplied.

propAuthData - Proprietary Authentication Data. Up to 8 bytes. Contains optional issuer data for transmission to the card in the Issuer Authentication Data of an online transaction. It may by used only for arpcMethod equals ARPCMethod.METHOD_2 in other case is ignored.

Returns:

if ARQC/TC/AAC verification passed then calculated 8 bytes ARPC or for arpcMethod equals ARPCMethod.METHOD_2 4 bytes ARPC, null in other case

Throws:

SMException

generateSM_MAC

byte[] generateSM_MAC(MKDMethod mkdm,
                      SKDMethod skdm,
                      SecureDESKey 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,
                                                                    SecureDESKey imksmi,
                                                                    String accountNo,
                                                                    String acctSeqNo,
                                                                    byte[] atc,
                                                                    byte[] arqc,
                                                                    byte[] data,
                                                                    EncryptedPIN currentPIN,
                                                                    EncryptedPIN newPIN,
                                                                    SecureDESKey kd1,
                                                                    SecureDESKey imksmc,
                                                                    SecureDESKey imkac,
                                                                    byte destinationPINBlockFormat)
                                                                    throws SMException

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

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

generateCBC_MAC

byte[] generateCBC_MAC(byte[] data,
                       SecureDESKey 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,
                       SecureDESKey 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 - if the parity of the imported key is not adjusted AND checkParity = true

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