Package opencard.core.terminal

Class APDU

  • Direct Known Subclasses:
    CommandAPDU, ResponseAPDU
    public abstract class APDU
extends java.lang.Object
    An APDU represents a Application Protocol Data Unit which is the basic unit of communication with a smart card.
    Author:
    Dirk Husemann (hud@zurich.ibm.com), Reto Hermann (rhe@zurich.ibm.com), Mike Wendler (mwendler@de.ibm.com), Stephan Breideneich (sbreiden@de.ibm.com)
    See Also:
    CommandAPDU, ResponseAPDU

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected byte[] apdu_buffer
      A buffer to hold the re-usable command APDU.
      protected int apdu_length
      The length of the command APDU currently in the buffer.

    • Constructor Summary

      Constructors 
      Constructor Description
      APDU​(byte[] buffer)
      Creates a new APDU and initializes it with the given buffer.
      APDU​(byte[] buffer, int length)
      Creates a new APDU and initializes it with the given buffer.
      APDU​(int size)
      Creates a new re-usable APDU with a given buffer size.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void append​(byte b)
      Appends the given byte to the internally buffered APDU.
      void append​(byte[] bytes)
      Appends the given byte array to the internally buffered APDU.
      void clear()
      Clear sensitive information from APDU buffer
      protected void finalize()
      Try to ensure that sensitive information is cleared out during finalization
      byte[] getBuffer()
      Returns the internal APDU buffer.
      int getByte​(int index)
      Gets the byte at the specified position in the buffer.
      byte[] getBytes()
      Returns a byte array holding the buffered APDU.
      int getLength()
      Returns the length of the buffered APDU.
      void setByte​(int index, int value)
      Sets the byte at the specified position in the buffer.
      void setLength​(int length)
      Sets the length of valid range within the APDU buffer.
      java.lang.String toString()
      Returns a human-readable string representation of this APDU.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • apdu_buffer

        protected byte[] apdu_buffer
        A buffer to hold the re-usable command APDU.

      • apdu_length

        protected int apdu_length
        The length of the command APDU currently in the buffer.

    • Constructor Detail

      • APDU

        public APDU​(byte[] buffer,
            int length)
        Creates a new APDU and initializes it with the given buffer. The buffer is assumed to hold an APDU. The length of the internally buffered APDU is set to length. The APDU buffer is explicitly cleared during garbage collection to prevent leakage of sensitive data. An APDU can not be used multiple times.
        Parameters:
        buffer - the byte array to be used for holding the APDU
        length - the length of the APDU currently in the buffer
        Throws:
        java.lang.IndexOutOfBoundsException - length exceeds the size of the array bytes.
        See Also:
        getLength()

      • APDU

        public APDU​(byte[] buffer)
        Creates a new APDU and initializes it with the given buffer. The internal buffer's length is set to the length of the buffer passed. The APDU buffer is explicitly cleared during garbage collection to prevent leakage of sensitive data. An APDU can not be used multiple times.
        Parameters:
        buffer - the byte array to be used for holding the APDU
        See Also:
        getLength()

      • APDU

        public APDU​(int size)
        Creates a new re-usable APDU with a given buffer size. A new buffer with the given size is allocated. The length of the internally buffered APDU is set to 0. The APDU buffer is explicitly cleared during garbage collection to prevent leakage of sensitive data. An APDU can not be used multiple times.
        Parameters:
        size - the size of the buffer to create
        See Also:
        getLength()

    • Method Detail

      • append

        public void append​(byte[] bytes)
            throws java.lang.IndexOutOfBoundsException
        Appends the given byte array to the internally buffered APDU.
        Parameters:
        bytes - the byte array to be appended
        Throws:
        java.lang.IndexOutOfBoundsException - The buffer size is exceeded.

      • append

        public void append​(byte b)
            throws java.lang.IndexOutOfBoundsException
        Appends the given byte to the internally buffered APDU.
        Parameters:
        b - the byte to be appended
        Throws:
        java.lang.IndexOutOfBoundsException - The buffer size is exceeded.

      • getBuffer

        public final byte[] getBuffer()
        Returns the internal APDU buffer. This method allows complex manipulations of the buffered APDU, for example MAC calculation. If the length of the APDU is changed by such an operation, setLength has to be used to store the new length.
        Returns:
        the buffer that holds the current APDU
        See Also:
        setLength(int)

      • getByte

        public final int getByte​(int index)
        Gets the byte at the specified position in the buffer. The byte is converted to a positive integer in the range 0..255. This method can only be used to access the APDU currently stored. It is not possible to read beyond the end of the APDU.
        Parameters:
        index - the position in the buffer
        Returns:
        the value at the given position, or -1 if the position is invalid
        See Also:
        setByte(int, int), getLength()

      • getBytes

        public final byte[] getBytes()
        Returns a byte array holding the buffered APDU. The byte array returned gets allocated with the exact size of the buffered APDU. To get direct access to the internal buffer, use getBuffer.
        Returns:
        the buffered APDU, copied into a new array
        See Also:
        getBuffer()

      • getLength

        public final int getLength()
        Returns the length of the buffered APDU.
        Returns:
        the length of the APDU currently stored

      • setByte

        public final void setByte​(int index,
                          int value)
        Sets the byte at the specified position in the buffer. The byte is passed as an integer, for consistence with getByte. This method can only be used to modify an APDU already stored. It is not possible to set bytes beyond the end of the current APDU. The method will behave as a no-op if this happens. Use append(byte) to extend the APDU.
        Parameters:
        index - the position in the buffer
        value - the byte to store there
        See Also:
        getByte(int), append(byte)

      • setLength

        public final void setLength​(int length)
                     throws java.lang.IndexOutOfBoundsException
        Sets the length of valid range within the APDU buffer. This method can be used to cut off the end of the APDU. It can also be used to increase the size of the APDU. In this case, it is the caller's responsibility to fill the additional bytes with useful information.
        Parameters:
        length - new length of the valid range
        Throws:
        java.lang.IndexOutOfBoundsException - thrown when the buffer size is exceeded

      • clear

        public void clear()
        Clear sensitive information from APDU buffer

      • finalize

        protected void finalize()
                 throws java.lang.Throwable
        Try to ensure that sensitive information is cleared out during finalization
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable

      • toString

        public java.lang.String toString()
        Returns a human-readable string representation of this APDU. This method does not use caching but creates the string from scratch on each invocation.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a hex dump of the APDU currently stored