Module de.gematik.smartcards.pcsc
Package de.gematik.smartcards.pcsc

Class IccChannel

java.lang.Object
javax.smartcardio.CardChannel
de.gematik.smartcards.pcsc.IccChannel
All Implemented Interfaces:
ApduLayer, MessageLayer
public final class IccChannel extends CardChannel implements ApduLayer
A logical channel connection to a Smart Card.

It is used to exchange APDUs with a Smart Card. A CardChannel object can be obtained by calling the method Card.getBasicChannel() or Card.openLogicalChannel().

Author:
gematik
See Also:

  • Method Details

    • send

      public byte[] send(byte[] command)
      Sends given message and returns the corresponding response.

      The CLA byte of the command APDU is automatically adjusted to match the channel number of this card channel.

      Note that this method cannot be used to transmit MANAGE CHANNEL APDUs. Logical channels should be managed by using

      1. Card.openLogicalChannel(),
      2. reset(),
      3. Icc.reset(),
      4. close().

      This method is used by the implementation of send(CommandApdu). The purpose of this method is to provide a transparent channel. E.g., if a CommandApdu is constructed from octet string '00 B0 8102 00 0003' (i.e., READ BINARY with ShortFileIdentifier=1 and offset=2 and Ne=3, ISO-case 2E (extended)), then send(CommandApdu) converts that CommandApdu to '00 B0 8102 03' (i.e., ISO-case 2S (short)).

      Specified by:
      send in interface MessageLayer
      Parameters:
      command - command APDU
      Returns:
      corresponding response APDU
      Throws:
      IllegalArgumentException - if apdu encodes a MANAGE CHANNEL command
      IllegalStateException - if
      1. this channel has been closed
      2. the corresponding Card has been disconnected
      See Also:

    • send

      public ResponseApdu send(CommandApdu apdu)
      Sends given command APDU.

      The CLA byte of the command APDU is automatically adjusted to match the channel number of this card channel.

      Note that this method cannot be used to transmit MANAGE CHANNEL APDUs. Logical channels should be managed by using

      1. Card.openLogicalChannel(),
      2. reset(),
      3. Icc.reset(),
      4. close().

      E.g. if a CommandApdu is constructed from octet string '00 B0 8102 00 0003' (i.e READ BINARY with ShortFileIdentifier=1 and offset=2 and Ne=3, ISO-case 2E (extended)), then this method converts that CommandApdu to '00 B0 8102 03' (i.e. ISO-case 2S (short)). Thus, if the intention is to send an ISO-case 2E method send(byte[]) has to be used.

      Specified by:
      send in interface ApduLayer
      Parameters:
      apdu - command APDU to be sent
      Returns:
      corresponding ResponseApdu
      Throws:
      IllegalArgumentException - if apdu encodes a MANAGE CHANNEL command
      IllegalStateException - if
      1. this channel has been closed
      2. the corresponding Card has been disconnected
      See Also:

    • transmit

      public ResponseAPDU transmit(CommandAPDU command)
      Transmits the specified command APDU to the Smart Card and returns the response APDU.

      The CLA byte of the command APDU is automatically adjusted to match the channel number of this card channel.

      Note that this method cannot be used to transmit MANAGE CHANNEL APDUs. Logical channels should be managed by using

      1. Card.openLogicalChannel(),
      2. reset(),
      3. Icc.reset(),
      4. close().

      Implementations should transparently handle artifacts of the transmission protocol. For example, when using the T=0 protocol, the following processing should occur as described in ISO/IEC 7816-4:

      • if the response APDU has an SW1 of 61, the implementation should issue a GET RESPONSE command using SW2 as the Le field. This process is repeated as long as an SW1 of 61 is received. The response body of these exchanges is concatenated to form the final response body.
      • if the response APDU is 6C XX, the implementation should reissue the command using XX as the Le field.

      The ResponseAPDU returned by this method is the result after this processing has been performed.

      Specified by:
      transmit in class CardChannel
      Parameters:
      command - the command APDU
      Returns:
      the response APDU received from the card
      Throws:
      IllegalStateException - if
      1. this channel has been closed
      2. the corresponding Card has been disconnected
      IllegalArgumentException - if the APDU encodes a MANAGE CHANNEL command
      NullPointerException - if command is null

    • transmit

      public int transmit(ByteBuffer command, ByteBuffer response)
      Transmits the command APDU stored in the command ByteBuffer and receives the response APDU in the response ByteBuffer.

      The command buffer must contain a valid command APDU data starting at command.position() and the APDU must be command.remaining() bytes long. Upon return, the command buffer's position will be equal to its limit; its limit will not have changed. The output buffer will have received the response APDU bytes. Its position will have advanced by the number of bytes received, which is also the return value of this method.

      The CLA byte of the command APDU is automatically adjusted to match the channel number of this CardChannel.

      Note that this method cannot be used to transmit MANAGE CHANNEL APDUs. Logical channels should be managed by using

      1. Card.openLogicalChannel(),
      2. reset(),
      3. Icc.reset(),
      4. close().

      See transmit(CommandAPDU) for a discussion of the handling of response APDUs in case of protocol "T=0".

      Specified by:
      transmit in class CardChannel
      Parameters:
      command - the buffer containing the command APDU
      response - the buffer that shall receive the response APDU from the card
      Returns:
      the length of the received response APDU
      Throws:
      IllegalArgumentException - if
      1. command and response are the same object
      2. response may not have sufficient space to receive the response APDU
      3. command encodes a MANAGE CHANNEL command
      IllegalStateException - if
      1. this channel has been closed
      2. the corresponding Card has been disconnected
      NullPointerException - if command or response is null
      ReadOnlyBufferException - if the response buffer is read-only

    • close

      public void close() throws CardException
      Closes this card channel.

      The logical channel is closed by issuing a MANAGE CHANNEL command that use the format [xx 70 80 00] xx is the CLA byte that encodes this logical channel. After this method returns, calling other methods in this class will raise an IllegalStateException.

      Note that the basic logical channel cannot be closed using this method. It can be closed by calling Card.disconnect(boolean).

      Specified by:
      close in class CardChannel
      Throws:
      CardException - if the card operation failed
      IllegalStateException - if this CardChannel represents a connection the basic logical channel

    • reset

      public void reset() throws CardException
      Resets this card channel.
      Throws:
      CardException - if the card operation failed
      IllegalStateException - if
      1. this channel has been closed
      2. the corresponding Card has been disconnected

    • getCard

      public Icc getCard()
      Returns the Card this channel is associated with.
      Specified by:
      getCard in class CardChannel
      Returns:
      the Card this channel is associated with

    • getChannelNumber

      public int getChannelNumber()
      Returns the channel number of this CardChannel.

      A channel number of 0 indicates the basic logical channel.

      Specified by:
      getChannelNumber in class CardChannel
      Returns:
      the channel number of this CardChannel
      Throws:
      IllegalStateException - if
      1. this channel has been closed
      2. if the corresponding Card has been disconnected

    • getTime

      public double getTime()
      Returns execution time of previous command-response pair.
      Specified by:
      getTime in interface MessageLayer
      Returns:
      execution time in seconds of previous command-response pair

    • toString

      public String toString()
      Returns String representation.
      Overrides:
      toString in class Object
      Returns:
      string representation of Icc + channelNumber