scardface — Library reference

This module implements a smart card interface libary, on top of PC/SC or WINSCARD APIs.


The SCard class provides a simple framework for interfacing with a smart card, once inserted into a smart card reader. It features many useful features as exposed by the PC/SC API.

class scardface.SCard(readers=None, groups=None, timeout=-1, atr=None, pnp=False)

Initialize the SCard object, when attempting to acquire a connection to a valid smart card.

The optional readers argument can be either string or iterable of strings, containing the reader(s) to watch. Default is None, meaning all readers are scanned.

The optional groups argument can be either string or iterable of strings, containing the reader group(s) to watch. Default is None, meaning default group is scanned.

The optional timeout expresses, in seconds (can be float), the maximum time to wait for acquiring a valid smart card session. Upon timeout, an SCardError exception is thrown (command timeout).

  • atr: bytes, regular expression on ATR to match. is used to find a pattern, so please include ‘^’ in front of the string to match from the beginning.

  • pnp: bool, default is False.

    if set to True, then ‘readers’ and ‘groups’ are ignored, and the reader is taken amongst the detected list of readers. In case a reader is added to or removed from the system, the list gets adjusted automatically.

    This mode allows for auto-insertion of a reader while the API is waiting for a card insertion.

    Caution: as a side effect, this mode will watch forever even if no reader is connected, when no timeout is specified.

    platform availability: Windows

If no reader or group is given, default readers are detected.

The algorithm attempts to find a valid smartcard connection, until the timeout expires.

When in main thread, the command can be interrupted by hitting CTRL-C (KeyboardInterrupt).

When called from another thread, the command can be interrupted through calling self.cancel() or cancel_all().



SCard objects

A SCard instance has the following methods:

send(self, *apdu, callback=None):

send one or several Command APDU to the ICC interface, using the detected protocol. meant to be protocol-independent as much as possible.

`*apdu` is one or several instance(s) of C_APDU object, to be sent to the card.

callback is a reference to a callback function, which is called after every sending of a command APDU. Defaults to None, meaning the default callback being used.

returns an R_APDU instance.

In case several C_APDU are chained, the sending carries on until the response code is different from b'\x90\x00'. In such case, it is the failing R_APDU that returns.

scardface functions

Table Of Contents

Previous topic

Dealing with readers hot insertion and removal

Next topic

Downloading SCardFace

This Page