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)
-
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
Version
1.0
Date
6 Nov 2017
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
Version
1.0
Date
6 Nov 2017
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()
orCard.openLogicalChannel()
.See also
See also
See also
Version
1.0
Date
6 Nov 2017
Declaration
Swift
public protocol CardChannel : AnyObject
-
Errors that occur during communication with the Smart Card stack or the card itself.
Version
1.0Date
6 Nov 2017Declaration
Swift
public enum CardError : Error
extension CardError: LocalizedError
-
Enumeration of attributes of a CardTerminal. It is used as a parameter to the
See moreCardTerminals.list()
method.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()
orCardTerminals.terminal(name:)
.Note that physical card readers with slots for multiple cards are represented by one
CardTerminal
object per such slot.See also
See also
Version
1.0
Date
6 Nov 2017
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
See also
Version
1.0
Date
6 Nov 2017
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
See also
Version
1.0
Date
6 Nov 2017
Declaration
Swift
public final class CommandAPDU
-
This class represents a “provider” for the Smart Card I/O API.
Version
1.0Date
16 Aug 2018Declaration
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
See also
Version
1.0
Date
6 Nov 2017
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 theterminals()
method.Each TerminalFactory has a
type
indicating how it was implemented. It must be specified when the implementation is obtained using ashared(type:params:provider:)
method and can be retrieved via thetype
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
See also
Version
1.0
Date
8 Dec 2017
Declaration
Swift
public final class TerminalFactory
-
The
TerminalFactorySpi
class defines the service provider interface. Applications do not access this class directly, instead seeTerminalFactory
.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 aProvider
. The engine type isTerminalFactory
. Service providers also need to implement subclasses of the protocol classesCardTerminals
,CardTerminal
,Card
, andCardChannel
.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
See also
Version
1.0
Date
8 Dec 2017
Declaration
Swift
public protocol TerminalFactorySpi : AnyObject