de.cardcontact.opencard.security
Class IsoSecureChannel

java.lang.Object
  extended by de.cardcontact.opencard.security.IsoSecureChannel
All Implemented Interfaces:
SecureChannel

public class IsoSecureChannel
extends java.lang.Object
implements SecureChannel

Class that implements secure messaging according to ISO7816-4 and specifically the profile from CWA 14890 (eSign-K), eGK and Extended Access Control 2.0.

The class has support for MAC protection of command and response APDU as well as encryption of command and response APDUs.

It supports send sequence counter for encryption and for MAC which can be incremented individually or in a synchronized way.

The class implements the SecureChannel interface and is as such a suitable APDU wrapper for the IsoCardService and TransparentCardService class.

Author:
Andreas Schwier (info@cardcontact.de)

Nested Class Summary
static class IsoSecureChannel.SSCPolicyEnum
           
 
Field Summary
protected  int blocklen
           
protected  java.lang.String cipheralgorithm
           
protected  byte[] crt
           
protected  byte[] encssc
           
protected  byte[] iv
           
protected  java.security.Key kenc
           
protected  java.security.Key kmac
           
protected  java.lang.String macalgorithm
           
protected  int maclen
           
protected  byte[] macssc
           
protected  java.lang.String provider
           
protected  IsoSecureChannel.SSCPolicyEnum sscpolicy
           
 
Fields inherited from interface de.cardcontact.opencard.security.SecureChannel
ALL, CENC, CPRO, RENC, RPRO
 
Constructor Summary
IsoSecureChannel()
          Create uninitialised secure channel object The crypto provider is preset with "BC"
IsoSecureChannel(java.lang.String provider)
          Create uninitialised secure channel object
 
Method Summary
protected  byte[] calculateMAC(byte cla, byte ins, byte p1, byte p2, byte[] do81or87, byte[] doLe)
          Calculates the MAC
protected  byte[] encodeBodyEvenINS(byte[] body, boolean isEncrypted, boolean isProtected)
          Encode the body into a TLV encoded secure messaging body for even INS bytes
protected  byte[] encodeBodyOddINS(byte[] body, boolean isEncrypted, boolean isProtected)
          Encode the body into a TLV encoded secure messaging body
 byte[] getEncryptionSendSequenceCounter()
          Return current value of send sequence counter for encryption
protected  byte[] getIV(javax.crypto.Cipher cipher)
          Determine the initialisation vector for encryption
 byte[] getMACSendSequenceCounter()
          Return current value of send sequence counter for message authentication code
 byte[] getSendSequenceCounter()
          Deprecated. Use getMACSendSequenceCounter instead
protected  void incrementENCSSC()
          Increment send sequence counter for encryption by one
protected  void incrementMACSSC()
          Increment send sequence counter for MAC by one
protected static byte[] incrementSSC(byte[] ssc)
          Increments a send sequence counte
 void setCipherAlgorithm(java.lang.String algo)
          Sets the JCE algorithm name used for mac operations.
 void setCRT(byte[] crt)
          Set the cryptographic reference template to be included in the command.
 void setEncKey(java.security.Key key)
          Set key for encryption / decryption For DESede keys the default MAC algorithm is set to DESede/CBC/NoPadding.
 void setEncryptionSendSequenceCounter(byte[] ssc)
          Initialise send sequence counter
 void setIV(byte[] iv)
          Set initialisation vector for CBC
 void setMacAlgorithm(java.lang.String algo)
          Sets the JCE algorithm name used for mac operations.
 void setMacKey(java.security.Key key)
          Set key from MAC calculation / verification For DESede keys the default MAC algorithm is set to ISO9797ALG3Mac (Retail-MAC).
 void setMacLength(int maclen)
          Set length of mac as number of rightmost bytes
 void setMACSendSequenceCounter(byte[] ssc)
          Initialise send sequence counter
 void setSendSequenceCounter(byte[] ssc)
          Deprecated. Use setMACSendSequenceCounter instead.
 void setSendSequenceCounterPolicy(IsoSecureChannel.SSCPolicyEnum policy)
          Set policy for handling send sequence counters.
 ResponseAPDU unwrap(ResponseAPDU apduToUnwrap, int usageQualifier)
          Unwrap response APDU received with secure messaging
 CommandAPDU wrap(CommandAPDU apduToWrap, int usageQualifier)
          Wrap command APDU into a secure messaging command APDU using algorithm defined in eSign-K (CWA 14890)
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

provider

protected java.lang.String provider

macalgorithm

protected java.lang.String macalgorithm

cipheralgorithm

protected java.lang.String cipheralgorithm

kenc

protected java.security.Key kenc

kmac

protected java.security.Key kmac

encssc

protected byte[] encssc

macssc

protected byte[] macssc

iv

protected byte[] iv

crt

protected byte[] crt

maclen

protected int maclen

blocklen

protected int blocklen

sscpolicy

protected IsoSecureChannel.SSCPolicyEnum sscpolicy
Constructor Detail

IsoSecureChannel

public IsoSecureChannel()
Create uninitialised secure channel object The crypto provider is preset with "BC"


IsoSecureChannel

public IsoSecureChannel(java.lang.String provider)
Create uninitialised secure channel object

Parameters:
provider - Cryptographic service provider for JCE
Method Detail

incrementSSC

protected static byte[] incrementSSC(byte[] ssc)
Increments a send sequence counte

Parameters:
ssc - the send sequence counter
Returns:
the ssc incremented by one

incrementMACSSC

protected void incrementMACSSC()
Increment send sequence counter for MAC by one


incrementENCSSC

protected void incrementENCSSC()
Increment send sequence counter for encryption by one


getIV

protected byte[] getIV(javax.crypto.Cipher cipher)
                throws java.security.GeneralSecurityException
Determine the initialisation vector for encryption

Parameters:
cipher - the cipher to use
Returns:
the initialisation vector
Throws:
java.security.GeneralSecurityException

encodeBodyEvenINS

protected byte[] encodeBodyEvenINS(byte[] body,
                                   boolean isEncrypted,
                                   boolean isProtected)
Encode the body into a TLV encoded secure messaging body for even INS bytes

Parameters:
body - the unwrapped body
isEncrypted - true if the body is encrypted
isProtected - true if the body is going to be MAC protected
Returns:
the encoded body

encodeBodyOddINS

protected byte[] encodeBodyOddINS(byte[] body,
                                  boolean isEncrypted,
                                  boolean isProtected)
Encode the body into a TLV encoded secure messaging body

Parameters:
body - the unwrapped body
isEncrypted - true if the body is encrypted
isProtected - true if the body is going to be MAC protected
Returns:
the encoded body

calculateMAC

protected byte[] calculateMAC(byte cla,
                              byte ins,
                              byte p1,
                              byte p2,
                              byte[] do81or87,
                              byte[] doLe)
Calculates the MAC

Parameters:
cla - the class byte
ins - the instruction byte
p1 - the parameter p1
p2 - the parameter p2
do81or87 - the data body object
doLe - the Le object
Returns:
the cryptogram

wrap

public CommandAPDU wrap(CommandAPDU apduToWrap,
                        int usageQualifier)
Wrap command APDU into a secure messaging command APDU using algorithm defined in eSign-K (CWA 14890)

Specified by:
wrap in interface SecureChannel
Parameters:
apduToWrap - Command APDU to be wrapped by secure messaging
usageQualifier - Bitmap of SecureChannel.CPRO and SecureChannel.CENC to indicate if MAC protection and or encryption is required.
Returns:
Wrapped APDU
Throws:
CardServiceInvalidParameterException - Thrown if crypto service provider does not support algorithm

unwrap

public ResponseAPDU unwrap(ResponseAPDU apduToUnwrap,
                           int usageQualifier)
Unwrap response APDU received with secure messaging

Specified by:
unwrap in interface SecureChannel
Parameters:
apduToUnwrap - Response APDU to process
usageQualifier - Bitmap of SecureChannel.RPRO and SecureChannel.RENC to indicate if MAC protection and or encryption is requested.
Returns:
Unwrapped APDU
Throws:
CardServiceInvalidParameterException - Thrown if crypto service provider does not support algorithm or secure messaging response is invalid
CardServiceInvalidCredentialException - Thrown is MAC verification or decryption of message failed

setEncKey

public void setEncKey(java.security.Key key)
Set key for encryption / decryption

For DESede keys the default MAC algorithm is set to DESede/CBC/NoPadding.

For AES keys the default MAC algorithm is set to AES/CBC/NoPadding.

All ISO padding is performed by the code itself.

Parameters:
key - the key used for encipherment or decipherment

setMacKey

public void setMacKey(java.security.Key key)
Set key from MAC calculation / verification

For DESede keys the default MAC algorithm is set to ISO9797ALG3Mac (Retail-MAC).

For AES keys the default MAC algorithm is set to AES CMAC.

All ISO padding is performed by the code itself.

Parameters:
key - the key used for mac calculation

setMacAlgorithm

public void setMacAlgorithm(java.lang.String algo)
Sets the JCE algorithm name used for mac operations.

Setting this parameter overwrites the default setting from setMacKey()

Parameters:
algo - the JCE algorithm name

setCipherAlgorithm

public void setCipherAlgorithm(java.lang.String algo)
Sets the JCE algorithm name used for mac operations.

Setting this parameter overwrites the default setting from setMacKey()

Parameters:
algo - the JCE algorithm name

setIV

public void setIV(byte[] iv)
Set initialisation vector for CBC

Parameters:
iv -

setMacLength

public void setMacLength(int maclen)
Set length of mac as number of rightmost bytes

Parameters:
maclen -

setSendSequenceCounter

public void setSendSequenceCounter(byte[] ssc)
Deprecated. Use setMACSendSequenceCounter instead.

Initialise send sequence counter

Parameters:
ssc -

setEncryptionSendSequenceCounter

public void setEncryptionSendSequenceCounter(byte[] ssc)
Initialise send sequence counter

Parameters:
ssc -

setMACSendSequenceCounter

public void setMACSendSequenceCounter(byte[] ssc)
Initialise send sequence counter

Parameters:
ssc -

getSendSequenceCounter

public byte[] getSendSequenceCounter()
Deprecated. Use getMACSendSequenceCounter instead

Return current value of send sequence counter

Returns:
Byte array containing send sequence counter or null if none defined

getEncryptionSendSequenceCounter

public byte[] getEncryptionSendSequenceCounter()
Return current value of send sequence counter for encryption

Returns:
Byte array containing send sequence counter or null if none defined

getMACSendSequenceCounter

public byte[] getMACSendSequenceCounter()
Return current value of send sequence counter for message authentication code

Returns:
Byte array containing send sequence counter or null if none defined

setSendSequenceCounterPolicy

public void setSendSequenceCounterPolicy(IsoSecureChannel.SSCPolicyEnum policy)
Set policy for handling send sequence counters.

Set to SSCPolicyEnum.DEFAULT to use SSC for encryption and SSC for MAC individually, if defined.

Set to SSCPolicyEnum.SYNC to use SSC for MAC for encryption as well.

Set to SSCPolicyEnum.SYNC_AND_ENCRYPT to use SSC for MAC for encrypted SSC for encryption.

Parameters:
policy - the policy to use

setCRT

public void setCRT(byte[] crt)
Set the cryptographic reference template to be included in the command.

Parameters:
crt - the crt to be included. Odd tags are included in the MAC.