Crate pcsc [−] [src]
Communicate with smart cards using the PC/SC protocol.
PC/SC (Personal Computer/Smart Card) is a standard protocol 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.dll library and "Smart Card" service. See MSDN for documentation of the implemented API.
On Apple, 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.
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 Apple, 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 ☺
Structs
| Canceler |
A structures that can be moved to another thread to allow it to cancel a blocking operation in the Context. |
| Card |
A connection to a smart card. |
| Context |
Library context to the PCSC service. |
| Protocols |
A mask of possible communication protocols. |
| ReaderNames |
An iterator over card reader names. |
| ReaderState |
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. |
| AttributeClass |
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. |
| ShareMode |
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. |
| PROTOCOL_ANY | |
| PROTOCOL_RAW | |
| PROTOCOL_T0 | |
| PROTOCOL_T1 | |
| PROTOCOL_UNDEFINED | |
| STATE_ATRMATCH | |
| STATE_CHANGED | |
| STATE_EMPTY | |
| STATE_EXCLUSIVE | |
| STATE_IGNORE | |
| STATE_INUSE | |
| STATE_MUTE | |
| STATE_PRESENT | |
| STATE_UNAVAILABLE | |
| STATE_UNAWARE | |
| STATE_UNKNOWN | |
| STATE_UNPOWERED | |
| STATUS_ABSENT | |
| STATUS_NEGOTIABLE | |
| STATUS_POWERED | |
| STATUS_PRESENT | |
| STATUS_SPECIFIC | |
| STATUS_SWALLOWED | |
| STATUS_UNKNOWN |
Functions
| PNP_NOTIFICATION |
A special value for detecting card reader insertions and removals. |