Expand description
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.
This crate depends on the pcsc-sys crate. See its documentation
if you need to customize how the PCSC implementation is found.
§Communicating with a smart card
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.
§Note on portability
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.
§Note on strings
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 &str/String
from this library – but don’t do this if you don’t need to ☺
§Note on thread safety and blocking operations
A library context can be safely moved to another thread or cloned and 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.
When issuing a series of commands to a card, it is recommended to always use a transaction – other programs and even system services can get in the way otherwise, even if you don’t expect it.
See MSDN for more details.
Re-exports§
pub use pcsc_sys as ffi;
Structs§
- Card
- A connection to a smart card.
- Card
Status - Status of a card in a card reader.
- Card
Status Owned - Status of a card in a card reader (owned).
- Context
- Library context to the PCSC service.
- Protocols
- A mask of possible communication protocols.
- Reader
Names - An iterator over card reader names.
- Reader
State - A structure for tracking the current state of card readers and cards.
- State
- A mask of the state a card reader.
- Status
- A mask of the status of a card in a card reader.
- Transaction
- An exclusive transaction with a card.
Enums§
- Attribute
- Card reader attribute types.
- Attribute
Class - A class of Attributes.
- Disposition
- Disposition method when disconnecting from a card reader.
- Error
- Possible library errors.
- Protocol
- A smart card communication protocol.
- Scope
- Scope of a context.
- Share
Mode - How a reader connection is shared.
Constants§
- MAX_
ATR_ SIZE - Maximum amount of bytes in an ATR.
- MAX_
BUFFER_ SIZE - Maximum amount of bytes in a short APDU command or response.
- MAX_
BUFFER_ SIZE_ EXTENDED - Maximum amount of bytes in an extended APDU command or response.
Functions§
- PNP_
NOTIFICATION - A special reader name for detecting card reader insertions and removals.
- ctl_
code - Transform a control code in the form expected by the platform.