Package de.cardcontact.opencard.security

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

    • Constructor Summary

      Constructors 
      Constructor Description
      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

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      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
      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
      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

    • 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

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

        @Deprecated
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.