Communicate with smart cards using the PC/SC API.
PC/SC (Personal Computer/Smart Card) is a standard API for communicating with smart cards -- enumerating card readers, connecting to smart cards, sending them commands, etc. See Wikipedia and PC/SC Workgroup for more information.
This library is a safe and ergonomic FFI wrapper around the following PC/SC implementations:
On Windows, the built-in
WinSCard.dlllibrary and "Smart Card" service. See MSDN for documentation of the implemented API.
On macOS, the built-in PCSC framework.
On Linux, BSDs and (hopefully) other systems, the PCSC lite library and pcscd daemon. See pcsclite for documentation of the implemented API.
To communicate with a smart card, you send it APDU (Application Protocol Data Unit) commands, and receive APDU responses.
The format of these commands is described in the ISO 7816 Part 4 standard. The commands themselves vary based on the application on the card.
The various implementations are not fully consistent with each other, and some may also miss various features or exhibit various bugs. Hence, you cannot assume that code which works on one platform will behave the same in all other platforms - unfortunately, some adjustments might be needed to reach a common base. See pcsclite for a list of documented differences, and Ludovic Rousseau's blog archive for many more details.
Not all PC/SC functionality is covered yet; if you are missing something, please open an issue.
The library uses C strings (
&CStr) for all strings (e.g. card reader
names), to avoid any allocation and conversion overhead.
In pcsclite and macOS, all strings are guaranteed to be UTF-8 encoded.
In Windows, the API provides two variants of all functions dealing with strings - ASCII and Unicode (in this case, meaning 16-bits wide strings). For ease of implementation, this library wraps the ASCII variants only. (If you require Unicode names in Windows, please open an issue.)
Since ASCII is a subset of UTF-8, you can thus safely use UTF-8
conversion functions such as
to_str() to obtain an
from this library -- but don't do this if you don't need to ☺
A library context can be safely moved to another thread or used from multiple threads.
Operations on a given context are not performed concurrently. If one
thread performs a blocking operation on a context, such as
get_status_change(), then another operation on the context will
block until the ongoing operation finishes.
An ongoing blocking operation on a context can be canceled from another
thread by calling the
cancel function on the context.
If you want to perform concurrent operations, for example, monitor smart card reader changes in one thread, and send commands to cards in another, create a different context for each thread.
Note however, that if one context has an exclusive transaction with a card, any operation on the same underlying card from not within the transaction will block even across contexts.
See MSDN for more details.
A connection to a smart card.
Library context to the PCSC service.
A mask of possible communication protocols.
An iterator over card reader names.
A structure for tracking the current state of card readers and cards.
A mask of the state a card reader.
A mask of the status of a card in a card reader.
An exclusive transaction with a card.
Card reader attribute types.
A class of Attributes.
Disposition method when disconnecting from a card reader.
Possible library errors.
A smart card communication protocol.
Scope of a context.
How a reader connection is shared.
Maximum amount of bytes in an ATR.
Maximum amount of bytes in a short APDU command or response.
Maximum amount of bytes in an extended APDU command or response.
A special reader name for detecting card reader insertions and removals.