This document explains the design guidelines followed for the implementation of this driver. You may be interested in reading this document if you intend to extend, improve, fix or some other way modify the source code of this software.
The driver is composed of two distinct parts: the core driver and the interfaces. The core driver has the responsibility of handling the reader. It's code is tied to the reader hardware and interface, etc.
The interfaces are located in separate directories, and use the API provided by the core driver to implement an interface specification, on top of the core driver. Currently there are two interfaces implemented: CT-API / CT-BCS and PCSC Lite IFD Handler, but other interfaces could be written.
The driver is designed following an object oriented style. There are several classes implemented as Abstract Data Types, that interact to provide the whole functionality.
Also there exists several communication layers, each containing a set of classes.
The core driver has the following layers:
Provides Input/Output communication with the device to which the reader is attached. An IO_Serial object provides access and configuration the serial port.
Provides access to the functionality of one interface device, such as transparent transmission and reception, reading and writing of memory buffers, etc. One or more IFD's can be attached to the same IO object. The IFD_Towitoko class provides this functionality for Towitoko reader.
This layer abstracts the upper layer from the issues related to having different types of integrated circuit cards. There are two objects within this layer: ICC_Async that encapsulates the functionality to access asynchronous (processor) cards, and ICC_Sync that does the equivalent for synchronous (memory) cards. Only one ICC object can be attached to the same IFD at a time.
Implements card access via commands and responses. A different protocol implementation is needed depending on the type of ICC. Protocol_Sync class provides a command interface for synchronous cards. Protocol_T0 class provides a command interface for processor cards using T=0 protocol. Protocol_T1 class provides a command interface for processor cards using T=1 protocol. Only one Protocol object is attached to one ICC object.
The following diagram illustrates the class structure of the core driver.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+---------------+ +---------------+ +---------------+
Protocol Layer | Protocol_Sync | | Protocol_T0 | | Protocol_T1 |
+---------------+ +---------------+ +---------------+
- - - - - - - - - - - - | - - - - - - - - - | - - - - - - - - - | - - - - -
v v v
+---------------+ +-----------------------------------+
ICC Layer | ICC_Sync | | ICC_Async |
+---------------+ +-----------------------------------+
- - - - - - - - - - - - | - - - - - - - - - - - - - - | - - - - - - - - - -
v v
+-------------------------------------------------------+
IFD Layer | IFD_Towitoko |
+-------------------------------------------------------+
- - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - -
v
+-------------------------------------------------------+
IO Layer | IO_Serial |
+-------------------------------------------------------+
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
POSIX I/0 routines |
There is also a set of utility classes that represent data exchanged between layers, such as ATR and ATR_Sync that conveys the answer to reset of the smartcards, and the APDU_Cmd and APDU_Rsp classes that handle command and response messages exchanged between the application and the protocol layer. Each object contains the data and the methods for creating, accessing, and deleting it.
The CT-API interface interacts with the classes provided by the core driver to implement the function calls defined in the CT-API and CT-BCS specification. The CT-API has access to every class defined in the core driver, so it can create the objects and call its functionality as it is needed.
CT-API / CT_BCS interface contains three classes:
A CardTerminal object represent one reader with any number of ICC slots, that is attached to a serial port. A CardTerminal can be initialized, sent a CT-BCS control command and closed.
A CT_Slot object represent one slot located in a CardTerminal. It contains one IFD object, which can have one ICC inserted and one Protocol object to handle the ICC. A CT_Slot object can be initialized and closed by the CardTerminal, accept commands for the ICC, and has control methods for checking the presence of card and detecting the type of card inserted.
The CT-API interface defines that any number of CardTerminals can be attached to a single machine, each one accessible via a ctn number. CT_List implements a linked list that stores CardTerminal objects that are created by the user, so they can be obtained and erased giving its ctn identification.
The following diagram represent the interactions between the CT-API / CT-BCS interface and the layers of the core driver.
+-------------------------------+
| CT-API / CT-BCS |
+-------+-----------------------+
| | CT_Slot |
| | +---------------+
| | | Protocol |
| | |---------------|
| | | ICC |
| | |---------------|
| | | IFD |
| +-------+---------------+
| CardTerminal | IO |
+---------------+---------------+ |
The PCSC IFD handler is a simple layer on top of CT-API / CT-BCS interface that implements the mapping to the functions needed to access the driver via MUSCLE PCSC Lite Resource manager.
This chapter explains guidelines followed in order to thread-enable the access to smartcard and terminal resources provided by the driver.
The goal is allow a Multi-threading application to use one or more readers and smartcards from one or more threads concurrently, managing the access to shared resources as efficiently as possible.
The responsibility of providing thread-safe functionality to the application is distributed between the core driver and the Interfaces:
The core driver functions are reentrant, but not thread-safe:
They do not use any static variable in read/write mode.
They do not return a reference to static data. All data managed by functions are provided by the caller of the function.
They do not call non-reentrant functions.
They are not thread-safe because they share physical resources like the serial port, the smartcard and the reader, whose response depends on the order in which they receive events. It's not responsibility of the core driver to implement access in mutual exclusion to these resources.
The Interfaces are thread-safe, but not necessarily reentrant:
CT-API cannot be reentrant because it's design force to maintain a static list of card-terminal contexts.
IFD Handler cannot be reentrant as far as it's based on CT-API interface.
Both of these interfaces and future interfaces must implement mutual exclusion access to it's static variables, and serialize the access to the resources IO, IFD, ICC and Protocol, provided by the core driver.