Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## de.cardcontact.opencard.security
Class IsoSecureChannel

    java.lang.Object
      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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD