Screenshot of quick-gui

Slides for a talk during the
Linuxwochen 2010 in Vienna.

The big picture

This project is about three things:

Current status

For both quick and ecard, there is a CLI and a GUI application. Concerning application behavior, they are not feature complete, but have a working core functionality, and are expeced to be ready for end users soon. The parts concerned with parsing the card will probably stay work in progress forever for lack of public documentation.

The underlying infrastructure changed a lot at the beginning, but has been more stable recently. Don't rely on it to be stable until there is a versioned release.

Plattform support: Development happens on Debian GNU/Linux, but care is taken not to obstruct running everything under Microsoft Windows or Apple's MacOS X.

Running the software

All of the programs in this project need

The GUI applications additionaly require python-gtk to be installed.

To test if your pcsc connection is working, try pcsc_scan.

A current version of the software can be obtained with git:

$ git clone
$ cd carddecoders

The applications for viewing the ecard (ecard-gui, ecard-cli) don't take command line arguments, those for quick cards (quick-gui, quick-cli) can be given file names of log files (which can be generated by $ ./quick-cli -o logfile_name.log) and optionally a -n switch to avoid reading the current card.

On windows

The software already works on MS Windows, at least partially. ecard-gui works, quick-cli would work if I wouldn't refuse to manually encode to UTF8 everything I print (that's a FIXME), quick-gui has trouble with the GTK select magic in nonblocking.

Architecture overview


As byte sequences are essential in smartcard communications but handled differently throughout python libraries, a carddecoders.bytestring.ByteString class (typically imported as B) was introduced, which is a python str (and Python3's bytes) object that can also behave like a list of numbers and has various decoding facilities.


Card communication is based on the pyscard framework, but subclassed as carddecoders.iso7816.smartcard.CardConnection, which uses B for input and output and provides a .check_transmit method that raises B/Exceptions if the card reports an error. Additionally, such CardConnections have methods to directly send APDUs (smartcard commands) as described by the carddecoders.iso7816.apdu module.

Like the pyscard card connections, they are not created directly, but using a dispatcher, carddecoders.dispatch.ConnectionDispatcher().autodispatch(). If logging=True is passed to autodispatch, all commands sent and received will be logged in the connection's .conversation attribute.


Analysis of such carddecoders.conversation.Conversations is important in reverse engineering; the conversations provide a .python() method which produces python code that replays the conversation, resolving all known APDUs back to their commands.

Conversations from other programs or virtual machines that have been sniffed using Linux' usbmon interface can be decoded using the carddecoders.usbmon module, usable through the logdecoder program.


Smartcard communication usually happens in a blocking fashion and in a procedural programming style, which is appropriate considering the protocols (in short, much of it is hopping through a directory structure), but feels bad in graphical user interfaces. Thus, GUI applications can let the card reading run in an own process using python's multiprocessing.

To give the application an object oriented interface, the multiprocessing.managers module is used, which helps in passing around objects which are wrapped in proxies or serialized/deserialized. Unfortunately, there is no nonblocking way to call these objects in the standard library, so the nonblocking module was created.

A detailed description on how to use nonblocking will follow soon.


This project is © chrysn 2010 and published under the terms of the GPLv3 or any later version.

Powered by quintessenz.