[][src]Crate pcsc

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.dll library 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.

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 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.

Structs

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.

Functions

PNP_NOTIFICATION

A special reader name for detecting card reader insertions and removals.