org.jpos.security.jceadapter
Class JCESecurityModule

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

All Implemented Interfaces:

Configurable, SMAdapter, LogSource

public class JCESecurityModule
extends BaseSMAdapter

JCESecurityModule is an implementation of a security module in software. It doesn't require any hardware device to work.
JCESecurityModule also implements the SMAdapter, so you can view it: either as a self contained security module adapter that doesn't need a security module or a security module that plugs directly to jpos, so doesn't need a separate adapter.
It relies on Java(tm) Cryptography Extension (JCE), hence its name.
JCESecurityModule relies on the JCEHandler class to do the low level JCE work.

WARNING: This version of JCESecurityModule is meant for testing purposes and NOT for life operation, since the Local Master Keys are stored in CLEAR on the system's disk. Comming versions of JCESecurity Module will rely on java.security.KeyStore for a better protection of the Local Master Keys.

Version:

$Revision$ $Date$

Author:

Hani Samuel Kirollos

Field Summary

Fields inherited from class org.jpos.security.BaseSMAdapter

cfg, logger, realm

Fields inherited from interface org.jpos.security.SMAdapter

FORMAT00, FORMAT01, FORMAT02, FORMAT03, FORMAT04, FORMAT05, FORMAT34, FORMAT35, FORMAT41, FORMAT42, LENGTH_DES, LENGTH_DES3_2KEY, LENGTH_DES3_3KEY, TYPE_BDK, TYPE_CVK, TYPE_MK_AC, TYPE_MK_CVC3, TYPE_MK_SMC, TYPE_MK_SMI, TYPE_PVK, TYPE_TAK, TYPE_TMK, TYPE_TPK, TYPE_ZAK, TYPE_ZMK, TYPE_ZPK

Constructor Summary

JCESecurityModule()
Creates an uninitialized JCE Security Module, you need to setConfiguration to initialize it

JCESecurityModule(Configuration cfg, Logger logger, String realm)

JCESecurityModule(String lmkFile)

JCESecurityModule(String lmkFile, String jceProviderClassName)

Method Summary

protected String	calculateCVVImpl(String accountNo, SecureDESKey cvkA, SecureDESKey cvkB, Date expDate, String serviceCode) Your SMAdapter should override this method if it has this functionality
protected String	calculatePVVImpl(EncryptedPIN pinUnderLmk, SecureDESKey pvkA, SecureDESKey pvkB, int pvkIdx, List<String> excludes) Your SMAdapter should override this method if it has this functionality
String	decryptPINImpl(EncryptedPIN pinUnderLmk) Your SMAdapter should override this method if it has this functionality
EncryptedPIN	encryptPINImpl(String pin, String accountNumber) Your SMAdapter should override this method if it has this functionality
byte[]	exportKeyImpl(SecureDESKey key, SecureDESKey kek) Your SMAdapter should override this method if it has this functionality
EncryptedPIN	exportPINImpl(EncryptedPIN pinUnderLmk, SecureDESKey kd2, byte destinationPINBlockFormat) Your SMAdapter should override this method if it has this functionality
protected byte[]	generateCBC_MACImpl(byte[] data, SecureDESKey kd) Generates CBC-MAC (Cipher Block Chaining Message Authentication Code) for some data.
protected byte[]	generateEDE_MACImpl(byte[] data, SecureDESKey kd) Generates EDE-MAC (Encrypt Decrypt Encrypt Message Authentication Code) for some data.
protected byte[]	generateKeyCheckValueImpl(SecureDESKey secureDESKey) Generates key check value.
SecureDESKey	generateKeyImpl(short keyLength, String keyType) Your SMAdapter should override this method if it has this functionality
EncryptedPIN	generatePINImpl(String accountNumber, int pinLen, List<String> excludes) Your SMAdapter should override this method if it has this functionality
SecureDESKey	importKeyImpl(short keyLength, String keyType, byte[] encryptedKey, SecureDESKey kek, boolean checkParity) Your SMAdapter should override this method if it has this functionality
EncryptedPIN	importPINImpl(EncryptedPIN pinUnderKd1, SecureDESKey kd1) Your SMAdapter should override this method if it has this functionality
void	setConfiguration(Configuration cfg) Configures a JCESecurityModule
EncryptedPIN	translatePINImpl(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey kd2, byte destinationPINBlockFormat) Your SMAdapter should override this method if it has this functionality
protected boolean	verifyCVC3Impl(SecureDESKey imkcvc3, String accountNo, String acctSeqNo, byte[] atc, byte[] upn, byte[] data, MKDMethod mkdm, String cvc3) Your SMAdapter should override this method if it has this functionality
protected boolean	verifyCVVImpl(String accountNo, SecureDESKey cvkA, SecureDESKey cvkB, String cvv, Date expDate, String serviceCode) Your SMAdapter should override this method if it has this functionality
protected boolean	verifydCVVImpl(String accountNo, SecureDESKey imkac, String dcvv, Date expDate, String serviceCode, byte[] atc, MKDMethod mkdm) Your SMAdapter should override this method if it has this functionality
boolean	verifyPVVImpl(EncryptedPIN pinUnderKd1, SecureDESKey kd1, SecureDESKey pvkA, SecureDESKey pvkB, int pvki, String pvv) Your SMAdapter should override this method if it has this functionality

Methods inherited from class org.jpos.security.BaseSMAdapter

calculateCVV, calculateIBMPINOffset, calculateIBMPINOffset, calculateIBMPINOffset, calculateIBMPINOffset, calculateIBMPINOffsetImpl, calculateIBMPINOffsetImpl, calculatePVV, calculatePVV, calculatePVV, calculatePVV, calculatePVVImpl, decryptPIN, deriveIBMPIN, deriveIBMPINImpl, encryptPIN, encryptPIN, eraseOldLMK, eraseOldLMKImpl, exportKey, exportPIN, generateARPC, generateARPCImpl, generateCBC_MAC, generateEDE_MAC, generateKey, generateKeyCheckValue, generatePIN, generatePIN, generateSM_MAC, generateSM_MACImpl, getLogger, getName, getRealm, getSMAdapter, importKey, importPIN, importPIN, importPINImpl, setLogger, setName, translateKeyFromOldLMK, translateKeyFromOldLMKImpl, translatePIN, translatePIN, translatePINGenerateSM_MAC, translatePINGenerateSM_MACImpl, translatePINImpl, verifyARQC, verifyARQCGenerateARPC, verifyARQCGenerateARPCImpl, verifyARQCImpl, verifyCVC3, verifyCVV, verifydCVV, verifyIBMPINOffset, verifyIBMPINOffsetImpl, verifyPVV

Methods inherited from class java.lang.Object

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

Constructor Detail

JCESecurityModule

public JCESecurityModule()

Creates an uninitialized JCE Security Module, you need to setConfiguration to initialize it

JCESecurityModule

public JCESecurityModule(String lmkFile)
                  throws SMException

Parameters:

lmkFile - Local Master Keys filename of the JCE Security Module

Throws:

SMException

JCESecurityModule

public JCESecurityModule(String lmkFile,
                         String jceProviderClassName)
                  throws SMException

Throws:

SMException

JCESecurityModule

public JCESecurityModule(Configuration cfg,
                         Logger logger,
                         String realm)
                  throws ConfigurationException

Throws:

ConfigurationException

Method Detail

setConfiguration

public void setConfiguration(Configuration cfg)
                      throws ConfigurationException

Configures a JCESecurityModule

Specified by:

setConfiguration in interface Configurable

Overrides:

setConfiguration in class BaseSMAdapter

Parameters:

cfg - The following properties are read:
lmk: Local Master Keys file (The only required parameter)
jce: JCE Provider Class Name, if not provided, it defaults to: com.sun.crypto.provider.SunJCE
rebuildlmk: (true/false), rebuilds the Local Master Keys file with new keys (WARNING: old keys will be erased)
cbc-mac: Cipher Block Chaining MAC algorithm name for given JCE Provider.
Default is ISO9797ALG3MACWITHISO7816-4PADDING from BouncyCastle provider (known as Retail-MAC)
that is suitable for most of interfaces with double length MAC key
ANSI X9.19 aka ISO/IEC 9797-1 MAC algorithm 3 padding method 2 - ISO7816
ede-mac: Encrypt Decrypt Encrypt MAC algorithm name for given JCE Provider.
Default is DESEDEMAC from BouncyCastle provider
that is suitable for BASE24 with double length MAC key
ANSI X9.19

Throws:

ConfigurationException

generateKeyImpl

public SecureDESKey generateKeyImpl(short keyLength,
                                    String keyType)
                             throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

generateKeyImpl in class BaseSMAdapter

Returns:

generated key

Throws:

SMException

importKeyImpl

public SecureDESKey importKeyImpl(short keyLength,
                                  String keyType,
                                  byte[] encryptedKey,
                                  SecureDESKey kek,
                                  boolean checkParity)
                           throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

importKeyImpl in class BaseSMAdapter

Returns:

imported key

Throws:

SMException

exportKeyImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

exportKeyImpl in class BaseSMAdapter

Returns:

exported key

Throws:

SMException

encryptPINImpl

public EncryptedPIN encryptPINImpl(String pin,
                                   String accountNumber)
                            throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

encryptPINImpl in class BaseSMAdapter

Returns:

encrypted PIN under LMK

Throws:

SMException

decryptPINImpl

public String decryptPINImpl(EncryptedPIN pinUnderLmk)
                      throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

decryptPINImpl in class BaseSMAdapter

Returns:

clear pin as entered by card holder

Throws:

SMException

importPINImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

importPINImpl in class BaseSMAdapter

Returns:

imported pin

Throws:

SMException

exportPINImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

exportPINImpl in class BaseSMAdapter

Returns:

exported pin

Throws:

SMException

generatePINImpl

public EncryptedPIN generatePINImpl(String accountNumber,
                                    int pinLen,
                                    List<String> excludes)
                             throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

generatePINImpl in class BaseSMAdapter

Returns:

generated PIN under LMK

Throws:

SMException

calculateCVVImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

calculateCVVImpl in class BaseSMAdapter

Returns:

Card Verification Code/Value

Throws:

SMException

verifyCVVImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifyCVVImpl in class BaseSMAdapter

Returns:

true if CVV/CVC is falid or false if not

Throws:

SMException

verifydCVVImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifydCVVImpl in class BaseSMAdapter

Returns:

Throws:

SMException

verifyCVC3Impl

protected boolean verifyCVC3Impl(SecureDESKey imkcvc3,
                                 String accountNo,
                                 String acctSeqNo,
                                 byte[] atc,
                                 byte[] upn,
                                 byte[] data,
                                 MKDMethod mkdm,
                                 String cvc3)
                          throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifyCVC3Impl in class BaseSMAdapter

Returns:

Throws:

SMException

calculatePVVImpl

protected String calculatePVVImpl(EncryptedPIN pinUnderLmk,
                                  SecureDESKey pvkA,
                                  SecureDESKey pvkB,
                                  int pvkIdx,
                                  List<String> excludes)
                           throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

calculatePVVImpl in class BaseSMAdapter

Returns:

PVV (VISA PIN Verification Value)

Throws:

SMException

verifyPVVImpl

public boolean verifyPVVImpl(EncryptedPIN pinUnderKd1,
                             SecureDESKey kd1,
                             SecureDESKey pvkA,
                             SecureDESKey pvkB,
                             int pvki,
                             String pvv)
                      throws SMException

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

verifyPVVImpl in class BaseSMAdapter

Returns:

Throws:

SMException

translatePINImpl

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

Description copied from class: BaseSMAdapter

Your SMAdapter should override this method if it has this functionality

Overrides:

translatePINImpl in class BaseSMAdapter

Returns:

translated pin

Throws:

SMException

generateCBC_MACImpl

protected byte[] generateCBC_MACImpl(byte[] data,
                                     SecureDESKey kd)
                              throws SMException

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

Overrides:

generateCBC_MACImpl in class BaseSMAdapter

Parameters:

data - the data to be MACed

kd - the key used for MACing

Returns:

generated CBC-MAC bytes

Throws:

SMException

generateEDE_MACImpl

protected byte[] generateEDE_MACImpl(byte[] data,
                                     SecureDESKey kd)
                              throws SMException

Generates EDE-MAC (Encrypt Decrypt Encrypt Message Authentication Code) for some data.

Overrides:

generateEDE_MACImpl in class BaseSMAdapter

Parameters:

data - the data to be MACed

kd - the key used for MACing

Returns:

generated EDE-MAC bytes

Throws:

SMException

generateKeyCheckValueImpl

protected byte[] generateKeyCheckValueImpl(SecureDESKey secureDESKey)
                                    throws SMException

Generates key check value.

Overrides:

generateKeyCheckValueImpl in class BaseSMAdapter

Parameters:

secureDESKey - SecureDESKey with untrusted or fake Key Check Value

Returns:

generated Key Check Value

Throws:

SMException