The PC/SC API
The PC/SC API is a set of a few dozens of functions, all of them named SCardSomething.
- On Windows, these functions are provided by the system-supplied winscard.dll library and documented in docs.microsoft.com/en-us/windows/desktop/api/winscard/.
- On Linux (and most UNIX systems), they are provided by the open-source PCSC-Lite project. PCSC-Lite binaries and headers are included in all major Linux distributions, or can be compiled from source. Visit pcsclite.apdu.fr for details on the project, and pcsclite.apdu.fr/api/group__API.html for the API reference.
- On Apple Mac OS X, these functions are provided by the Smart Card Services project / CryptoTokenKit API, which is a fork of Linux' PCSC-Lite. Please visit smartcardservices.github.io for details.
It is better to always refer to the documentation of the PC/SC API written for your actual operating system, for accurate prototypes and contextualized examples.
Mobile systems (Android and iOS namely) do not support PC/SC. SpringCard offers so-called "PC/SC-like" software libraries to use SpringCore devices in these contexts.
Minimal function set
Not all functions are useful in a typical card-aware application. The basic functions one always have to use are listed in the table below.
|SCardEstablishContext||Open an access to the PC/SC library and subsystem||For a multi-thread application, each thread should have its own context.|
|SCardReleaseContext||Close the access||To be called when exiting.|
|SCardListReaders||Return a list of available PC/SC readers||Every PC/SC reader has a friendly name and an instance number. Pay attention that the instance number is likely to change when the computer restarts or the reader is unplugged and plugged again. Also the friendly name is not consistent among different operating systems.|
|SCardGetStatusChange||Monitor one or more PC/SC readers, and receive an event when a card is inserted, removed, or its status is changed||For unattended applications (card printing, kiosks...) this function allows to start processing as soon as a card becomes available.
For GUI applications, the key for a good user experience is to use this function in a background thread and reflect the availability of the card into the actions that can be performed -or not- in the user interface.
|SCardConnect||Open a communication channel a smart card (given its reader name)||The card has to be connected using either the T=0 or T=1 protocol. A typical application would always let the reader select the best protocol, and not enforce it.
The application may specify whether it accept to share the card or wants it for exclusive use. Sharing the card opens a potential security hole and requires an external mutual-exclusion scheme; a typical application would always ask for an exclusive access. If the card has already been connected by another application, just use SCardGetStatusChange to pause until the other application is done with it, and try again.
SCardConnect is also sometimes used without a card in the reader, to open a direct SCardControl channel.
|SCardStatus||Get the card's ATR and retrieve an up-to-date status||The card's ATR is also provided by SCardGetStatusChange.|
|SCardTransmit||Send a command to the card, and receive its response||A smart card must comply with the ISO/IEC 7816-4 standard. SCardTransmit conveys APDUs (application-level protocol datagram units) from the application to the card, and back.
In the case of non-compliant cards (for instance RFID labels or NFC Tags), the PC/SC reader "interprets" the APDU commands and "translates" them into the equivalent specific command (and protocol) of the given chip.
|SCardDisconnect||Close the communication channel||This function must ALWAYS be called when the application is done with the card (even if the card has been removed during the transaction) to cleanup the channel.
When the card has not been removed yet, the application has to specify whether the card is to be resetted, or powered down, or left active.
Leaving a card active after opens a potential security hole: if your software has gained priviledges against the card (e.g. valid authentication or PIN code) and leaves the card "as it", the next software connecting to the same card will benefit of the same priviledges.
|SCardControl||Send a direct command to the reader, and receive its response||This function is used to control the LEDs and buzzer, to change the device's configuration, etc.
SpringCore devices offer a direct communication channel to do the same while removing the intrication with PC/SC card processing. New developments should use the direct communication method instead of SCardControl.