org.jpos.security
Interface SMAdapter

All Known Implementing Classes:

BaseSMAdapter, JCESecurityModule

public interface SMAdapter

A class that implements the SecurityModuleAdapter 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: 2854 $ $Date: 2010-01-02 02:34:31 -0800 (Sat, 02 Jan 2010) $

Author:

Hani S. Kirollos

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 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 java.lang.String	TYPE_BDK BDK: Base Derivation Key.
static java.lang.String	TYPE_CVK CVK: Card Verification Key.
static java.lang.String	TYPE_PVK PVK: PIN Verification 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_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

java.lang.String	decryptPIN(EncryptedPIN pinUnderLmk) Decrypts an Encrypted PIN (under LMK).
EncryptedPIN	encryptPIN(java.lang.String pin, java.lang.String accountNumber) 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[]	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, java.lang.String keyType) Generates a random DES Key.
byte[]	generateKeyCheckValue(SecureDESKey kd) Generates key check value.
SecureDESKey	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.
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.

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

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

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

generateKeyCheckValue

byte[] generateKeyCheckValue(SecureDESKey kd)
                             throws SMException

Generates key check value.

Parameters:

key - SecureDESKey with untrusted or fake Key Check Value

Returns:

key check value bytes

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

accountNumber - The 12 right-most digits of the account number excluding the check digit. Should also function correctly if the complete account number, including the check digit is passed.

Returns:

PIN under LMK

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

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