Package opencard.core.service

Class CardChannel

  • public class CardChannel
extends java.lang.Object
    A communication channel to a smartcard. A channel is used to exchange APDUs with an associated smartcard. Additionally, it can be used to access some other resources related to the associated card, like the terminal into which it is inserted.
    CardChannel is the card service layer pendant to the terminal layer's SlotChannel. The slot channel is a physical channel, onto which several logical card channels can be multiplexed if the smartcard supports logical channels.
    Author:
    Dirk Husemann (hud@zurich.ibm.com), Reto Hermann (rhe@zurich.ibm.com), Mike Wendler (mwendler@de.ibm.com), Roland Weber (rolweber@de.ibm.com)
    See Also:
    SlotChannel, CardServiceScheduler

    • Constructor Detail

      • CardChannel

        protected CardChannel​(SlotChannel slotchannel)
        Instantiate a new logical card channel. The new channel has the given underlying physical slot channel which will be used to contact the smartcard.
        Parameters:
        slotchannel - the physical channel to the smartcard

    • Method Detail

      • isOpen

        public final boolean isOpen()
        Checks whether this channel is currently open. A channel can be used for communication with the associated smartcard only while it's open.
        Returns:
        true if this channel is open, false otherwise

      • getCardTerminal

        public CardTerminal getCardTerminal()
        Returns the card terminal associated with this channel. The card channel is a logical channel, which is mapped onto a physical slot channel. The slot channel is associated with the slot into which the smartcard is inserted. The slot itself is associated with a card terminal. That card terminal is queried using this method.
        Returns:
        The terminal that owns the underlying slot channel.
        See Also:
        SlotChannel, Slot

      • getSlotChannel

        public SlotChannel getSlotChannel()
        Return the slot channel associated with this channel.
        Returns:
        the slot channel

      • setState

        public final void setState​(java.lang.Object state)
        Stores a service specific object associated with this channel. The object stored can be retrieved by getState. By convention, this method is invoked only by a card service that has currently allocated this channel. The state object can, for example, be used to store the current selection. It allows card services to cooperate without knowing about each other, as long as they use the same conventions for the objects stored here. The state is associated with a channel rather than a smartcard, since a smartcard may support several logical channels with partially independent states.
        Parameters:
        state - the object to associate with this channel, or null to reset previous associations
        See Also:
        getState()

      • getState

        public final java.lang.Object getState()
        Retrieves the service specific object associated with this channel. This method returns the argument to the last invocation of setState. By convention, it is invoked only by a card service that has currently allocated this channel. The object retrieved has been stored by a service that used this channel before.
        Returns:
        the object currently associated with this channel, or null if there is no association
        See Also:
        setState(java.lang.Object)

      • sendVerifiedAPDU

        public final ResponseAPDU sendVerifiedAPDU​(CommandAPDU command,
                                           CHVControl control,
                                           CHVDialog dialog)
                                    throws InvalidCardChannelException,
                                           CardTerminalException,
                                           CardServiceInvalidCredentialException
        Sends a command including a PIN to the smart card within a given time. The APDU to send will be modified on it's way to the card by storing a PIN or password which has been entered by the card owner. This method supports GUI password dialogs as well as a card terminal's encrypting pinpad, if available. The smartcard's response to the command is received and returned if the operation completes within the specified timeout.
        The decision whether the terminal or a GUI dialog is used for querying the password is crucial to security. Currently, the GUI is used only if the terminal does not implement the interface VerifiedAPDUInterface. This behavior must not be changed in derived classes, therefore this method is final.
        Parameters:
        command - the CommandAPDU to send
        control - the verification parameters to use
        dialog - the dialog to use to query a password. Ignored if the terminal takes the reponsibility for querying the password or PIN. The default dialog is used if this argument is null.
        Returns:
        the response from the smartcard
        Throws:
        InvalidCardChannelException - This channel is currently not open.
        CardTerminalException - The terminal encountered an error.
        CardServiceInvalidCredentialException - The user cancelled password input.
        See Also:
        VerifiedAPDUInterface, CardHolderVerificationGUI

      • open

        public void open()
          throws InvalidCardChannelException
        Opens this CardChannel. This method cannot be invoked after the channel has been closed for good by an invocation of closeFinal(). The default visibility is (would be) sufficient since it gets called by the scheduler, which resides in the same package.
        Throws:
        InvalidCardChannelException - This channel is already open, or closed for good.

      • close

        public void close()
        Closes this CardChannel. It can still be opened again. While the channel is not open, invocations of the send methods will throw an exception.

      • closeFinal

        protected void closeFinal()
        Closes this CardChannel so it cannot be opened anymore.

      • finalize

        public void finalize()
        Tries to clean up.
        Overrides:
        finalize in class java.lang.Object

      • toString

        public java.lang.String toString()
        Returns a string representation of this card channel.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a human-readable representation of this channel