SmartCardIO

This specification describes the Java Smart Card I/O API defined by JSR 268.

It defines a Java API for communication with Smart Cards using ISO/IEC 7816-4 APDUs. It thereby allows Java applications to interact with applications running on the Smart Card, to store and retrieve data on the card, etc.

The API is defined by classes in the module SmartCardIO. They can be classified as follows:

Classes describing the corresponding Smart Card structures
ATR, CommandAPDU, ResponseAPDU

Factory to obtain implementations
TerminalFactory

Main classes for card and terminal functions
CardTerminals, CardTerminal, Card, CardChannel

Enumerations for error handling
CardError

Service provider interface, not accessed directly by applications
TerminalFactorySpi

API Example

A simple example of using the API is:

// show the list of available terminals
let factory = try TerminalFactory.shared(type: "MyType",
                                         params: params,
                                         provider: provider)
let terminals = try factory.terminals().list()
print("Terminals: " + terminals)

// get the first terminal
let terminal = terminals[0]

// establish a connection with the card
let card = try terminal.connect(protocolString: "T=0")
print("card: " + card)
let channel = try card.basicChannel()
let r = try channel.transmit(CommandAPDU(apdu: c1))
print("response: " + toString(buffer: r.bytes))

// disconnect
try card.disconnect(reset: false)
  • ATR

    A Smart Card’s answer-to-reset bytes. A Card’s ATR object can be obtained by calling Card.atr. This class does not attempt to verify that the ATR encodes a semantically valid structure.

    Instances of this class are immutable. Where data is passed in or out via byte arrays, defensive cloning is performed.

    See also

    Card.atr

    Author

    Andreas Sterbenz

    Author

    JSR 268 Expert Group

    Author

    Godfrey Chung

    Version

    1.0

    Date

    6 Nov 2017

    See more

    Declaration

    Swift

    public final class ATR
  • A Smart Card with which a connection has been established. Card objects are obtained by calling CardTerminal.connect(protocolString:).

    See also

    CardTerminal

    Author

    Andreas Sterbenz

    Author

    JSR 268 Expert Group

    Author

    Godfrey Chung

    Version

    1.0

    Date

    6 Nov 2017

    See more

    Declaration

    Swift

    public protocol Card : AnyObject
  • 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.basicChannel() or Card.openLogicalChannel().

    See also

    Card

    See also

    CommandAPDU

    See also

    ResponseAPDU

    Author

    Andreas Sterbenz

    Author

    JSR 268 Expert Group

    Author

    Godfrey Chung

    Version

    1.0

    Date

    6 Nov 2017

    See more

    Declaration

    Swift

    public protocol CardChannel : AnyObject
  • Errors that occur during communication with the Smart Card stack or the card itself.

    Author

    Andreas Sterbenz

    Author

    JSR 268 Expert Group

    Author

    Godfrey Chung

    Version

    1.0

    Date

    6 Nov 2017
    See more

    Declaration

    Swift

    public enum CardError : Error
    extension CardError: LocalizedError
  • Enumeration of attributes of a CardTerminal. It is used as a parameter to the CardTerminals.list() method.

    See more

    Declaration

    Swift

    public enum CardState
  • A Smart Card terminal, sometimes referred to as a Smart Card Reader. A CardTerminal object can be obtained by calling CardTerminals.list() or CardTerminals.terminal(name:).

    Note that physical card readers with slots for multiple cards are represented by one CardTerminal object per such slot.

    See also

    CardTerminals

    See also

    TerminalFactory

    Author

    Andreas Sterbenz

    Author

    JSR 268 Expert Group

    Author

    Godfrey Chung

    Version

    1.0

    Date

    6 Nov 2017

    See more

    Declaration

    Swift

    public protocol CardTerminal : AnyObject
  • The set of terminals supported by a TerminalFactory. This class allows applications to enumerate the available CardTerminals, obtain a specific CardTerminal, or wait for the insertion or removal of cards.

    This class is multi-threading safe and can be used by multiple threads concurrently. However, this object keeps track of the card presence state of each of its terminals. Multiple objects should be used if independent calls to waitForChange() are required.

    Applications can obtain instances of this class by calling TerminalFactory.terminals().

    See also

    TerminalFactory

    See also

    CardTerminal

    Author

    Andreas Sterbenz

    Author

    JSR 268 Expert Group

    Author

    Godfrey Chung

    Version

    1.0

    Date

    6 Nov 2017

    See more

    Declaration

    Swift

    public protocol CardTerminals : AnyObject
  • A command APDU following the structure defined in ISO/IEC 7816-4. It consists of a four byte header and a conditional body of variable length. This class does not attempt to verify that the APDU encodes a semantically valid command.

    Note that when the expected length of the response APDU is specified in the constructors, the actual length (Ne) must be specified, not its encoded form (Le). Similarly, ne returns the actual value Ne. In other words, a value of 0 means “no data in the response APDU” rather than “maximum length”.

    This class supports both the short and extended forms of length encoding for Ne and Nc. However, note that not all terminals and Smart Cards are capable of accepting APDUs that use the extended form.

    Instances of this class are immutable. Where data is passed in or out via byte arrays, defensive cloning is performed.

    See also

    ResponseAPDU

    Author

    Andreas Sterbenz

    Author

    JSR 268 Expert Group

    Author

    Godfrey Chung

    Version

    1.0

    Date

    6 Nov 2017

    See more

    Declaration

    Swift

    public final class CommandAPDU
  • This class represents a “provider” for the Smart Card I/O API.

    Author

    Benjamin Renaud

    Author

    Andreas Sterbenz

    Author

    Godfrey Chung

    Version

    1.0

    Date

    16 Aug 2018
    See more

    Declaration

    Swift

    open class Provider
    extension Provider: CustomStringConvertible
  • A response APDU as defined in ISO/IEC 7816-4. It consists of a conditional body and a two byte trailer. This class does not attempt to verify that the APDU encodes a semantically valid response.

    Instances of this class are immutable. Where data is passed in or out via byte arrays, defensive cloning is performed.

    See also

    CommandAPDU

    Author

    Andreas Sterbenz

    Author

    JSR 268 Expert Group

    Author

    Godfrey Chung

    Version

    1.0

    Date

    6 Nov 2017

    See more

    Declaration

    Swift

    public final class ResponseAPDU
  • A factory for CardTerminal objects.

    It allows an application to obtain a TerminalFactory by calling shared(type:params:provider:) method and use this TerminalFactory object to access the CardTerminals by calling the terminals() method.

    Each TerminalFactory has a type indicating how it was implemented. It must be specified when the implementation is obtained using a shared(type:params:provider:) method and can be retrieved via the type property.

    TerminalFactory utilizes an extensible service provider framework. Service providers that wish to add a new implementation should see the TerminalFactorySpi class for more information.

    See also

    CardTerminals

    See also

    Provider

    Author

    Andreas Sterbenz

    Author

    JSR 268 Expert Group

    Author

    Godfrey Chung

    Version

    1.0

    Date

    8 Dec 2017

    See more

    Declaration

    Swift

    public final class TerminalFactory
  • The TerminalFactorySpi class defines the service provider interface. Applications do not access this class directly, instead see TerminalFactory.

    Service providers that want to write a new implementation should define a concrete subclass of TerminalFactorySpi with a constructor that takes an Any as parameter. That class needs to be registered in a Provider. The engine type is TerminalFactory. Service providers also need to implement subclasses of the protocol classes CardTerminals, CardTerminal, Card, and CardChannel.

    For example:

    module MyModule

    file MyProvider.swift:

    import SmartCardIO
    
    public class MyProvider: Provider {
        public init() {
            super.init(name: "MyProvider",
                       version: 1.0,
                       info: "Smart Card Example")
            put(key: "TerminalFactory.MyType",
                value: "MyModule.MySpi")
        }
    }
    

    file MySpi.swift:

    import SmartCardIO
    
    public class MySpi: TerminalFactoySpi {
        public required init(parameter: Any) throws {
            // initialize as appropriate
        }
        public func engineTerminals() -> CardTerminals {
            // add implementation code here
        }
    }
    

    See also

    TerminalFactory

    See also

    Provider

    Author

    Andreas Sterbenz

    Author

    JSR 268 Expert Group

    Author

    Godfrey Chung

    Version

    1.0

    Date

    8 Dec 2017

    See more

    Declaration

    Swift

    public protocol TerminalFactorySpi : AnyObject