org.jpos.security
Class BaseSMAdapter

java.lang.Object
  org.jpos.security.BaseSMAdapter

All Implemented Interfaces:

Configurable, ReConfigurable, SMAdapter, LogSource

Direct Known Subclasses:

JCESecurityModule

public class BaseSMAdapter
extends java.lang.Object
implements SMAdapter, ReConfigurable, LogSource

Provides base functionality for the actual Security Module Adapter.

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

Version:

$Revision: 2594 $ $Date: 2008-01-22 08:41:31 -0800 (Tue, 22 Jan 2008) $

Author:

Hani S. Kirollos

Field Summary

Fields inherited from interface org.jpos.security.SMAdapter

FORMAT00, FORMAT01, FORMAT02, FORMAT03, FORMAT04, FORMAT05, LENGTH_DES, LENGTH_DES3_2KEY, LENGTH_DES3_3KEY, TYPE_BDK, TYPE_CVK, TYPE_PVK, TYPE_TAK, TYPE_TMK, TYPE_TPK, TYPE_ZAK, TYPE_ZMK, TYPE_ZPK

Constructor Summary

BaseSMAdapter()

BaseSMAdapter(Configuration cfg, Logger logger, java.lang.String realm)

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.
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.
SecureDESKey	generateKey(short keyLength, java.lang.String keyType) Generates a random DES Key.
Logger	getLogger()
java.lang.String	getName()
java.lang.String	getRealm()
static SMAdapter	getSMAdapter(java.lang.String name)
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.
void	setConfiguration(Configuration cfg)
void	setLogger(Logger logger, java.lang.String realm)
void	setName(java.lang.String name) associates this SMAdapter with a name using NameRegistrar
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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BaseSMAdapter

public BaseSMAdapter()

BaseSMAdapter

public BaseSMAdapter(Configuration cfg,
                     Logger logger,
                     java.lang.String realm)
              throws ConfigurationException

Throws:

ConfigurationException

Method Detail

setConfiguration

public void setConfiguration(Configuration cfg)
                      throws ConfigurationException

Specified by:

setConfiguration in interface Configurable

Parameters:

cfg - Configuration object

Throws:

ConfigurationException

setLogger

public void setLogger(Logger logger,
                      java.lang.String realm)

Specified by:

setLogger in interface LogSource

getLogger

public Logger getLogger()

Specified by:

getLogger in interface LogSource

getRealm

public java.lang.String getRealm()

Specified by:

getRealm in interface LogSource

setName

public void setName(java.lang.String name)

associates this SMAdapter with a name using NameRegistrar

Parameters:

name - name to register

See Also:

NameRegistrar

getName

public java.lang.String getName()

Returns:

this SMAdapter's name ("" if no name was set)

getSMAdapter

public static SMAdapter getSMAdapter(java.lang.String name)
                              throws NameRegistrar.NotFoundException

Parameters:

name -

Returns:

SMAdapter instance with given name.

Throws:

NameRegistrar.NotFoundException

See Also:

NameRegistrar

generateKey

public SecureDESKey generateKey(short keyLength,
                                java.lang.String keyType)
                         throws SMException

Description copied from interface: SMAdapter

Generates a random DES Key.

Specified by:

generateKey in interface SMAdapter

Parameters:

keyLength - bit length of the key to be generated (LENGTH_DES, LENGTH_DES3_2KEY...)

keyType - type of the key to be generated (TYPE_ZMK, TYPE_TMK...etc)

Returns:

the random key secured by the security module

Throws:

SMException

importKey

public SecureDESKey importKey(short keyLength,
                              java.lang.String keyType,
                              byte[] encryptedKey,
                              SecureDESKey kek,
                              boolean checkParity)
                       throws SMException

Description copied from interface: SMAdapter

Imports a key from encryption under a KEK (Key-Encrypting Key) to protection under the security module.

Specified by:

importKey in interface SMAdapter

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

public byte[] exportKey(SecureDESKey key,
                        SecureDESKey kek)
                 throws SMException

Description copied from interface: SMAdapter

Exports secure key to encryption under a KEK (Key-Encrypting Key).

Specified by:

exportKey in interface SMAdapter

Parameters:

key - the secure key to be exported

kek - the key-encrypting key

Returns:

the exported key (key encrypted under kek)

Throws:

SMException

encryptPIN

public EncryptedPIN encryptPIN(java.lang.String pin,
                               java.lang.String accountNumber)
                        throws SMException

Description copied from interface: SMAdapter

Encrypts a clear pin under LMK. CAUTION: The use of clear pin presents a significant security risk

Specified by:

encryptPIN in interface SMAdapter

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

public java.lang.String decryptPIN(EncryptedPIN pinUnderLmk)
                            throws SMException

Description copied from interface: SMAdapter

Decrypts an Encrypted PIN (under LMK). CAUTION: The use of clear pin presents a significant security risk

Specified by:

decryptPIN in interface SMAdapter

Returns:

clear pin as entered by card holder

Throws:

SMException

importPIN

public EncryptedPIN importPIN(EncryptedPIN pinUnderKd1,
                              SecureDESKey kd1)
                       throws SMException

Description copied from interface: SMAdapter

Imports a PIN from encryption under KD (Data Key) to encryption under LMK.

Specified by:

importPIN in interface SMAdapter

Parameters:

pinUnderKd1 - the encrypted PIN

kd1 - Data Key under which the pin is encrypted

Returns:

pin encrypted under LMK

Throws:

SMException

translatePIN

public EncryptedPIN translatePIN(EncryptedPIN pinUnderKd1,
                                 SecureDESKey kd1,
                                 SecureDESKey kd2,
                                 byte destinationPINBlockFormat)
                          throws SMException

Description copied from interface: SMAdapter

Translates a PIN from encrytion under KD1 to encryption under KD2.

Specified by:

translatePIN in interface SMAdapter

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

public EncryptedPIN importPIN(EncryptedPIN pinUnderDuk,
                              KeySerialNumber ksn,
                              SecureDESKey bdk)
                       throws SMException

Description copied from interface: SMAdapter

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

Specified by:

importPIN in interface SMAdapter

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

public EncryptedPIN translatePIN(EncryptedPIN pinUnderDuk,
                                 KeySerialNumber ksn,
                                 SecureDESKey bdk,
                                 SecureDESKey kd2,
                                 byte destinationPINBlockFormat)
                          throws SMException

Description copied from interface: SMAdapter

Translates a PIN from encryption under a transaction key to encryption under a KD (Data Key). The transaction key is derived from the Key Serial Number and the Base Derivation Key using DUKPT (Derived Unique Key per Transaction). See ANSI X9.24 for more information.

Specified by:

translatePIN in interface SMAdapter

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

public EncryptedPIN exportPIN(EncryptedPIN pinUnderLmk,
                              SecureDESKey kd2,
                              byte destinationPINBlockFormat)
                       throws SMException

Description copied from interface: SMAdapter

Exports a PIN from encryption under LMK to encryption under a KD (Data Key).

Specified by:

exportPIN in interface SMAdapter

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

public byte[] generateCBC_MAC(byte[] data,
                              SecureDESKey kd)
                       throws SMException

Description copied from interface: SMAdapter

Generates CBC-MAC (Cipher Block Chaining Message Authentication Code) for some data.

Specified by:

generateCBC_MAC in interface SMAdapter

Parameters:

data - the data to be MACed

kd - the key used for MACing

Returns:

the MAC

Throws:

SMException