carddecoders

Screenshot of quick-gui

Slides for a talk during the
Linuxwochen 2010 in Vienna.

The big picture

This project is about three things:

providing infrastructure to work with smartcards in a pythonic way and reverse engineering their protocols
providing infrastructure to build GUI applications that interact with smartcards
implementations of such tools for cards whose protocols have been reverse engineered:
- Austrian quick e-purses, including some more general Maestro card features
- Austrian ecards (health insurance card)

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

Python (>=2.5 with multiprocessing or >=2.6)
pyscard
a PC/SC daemon like pcscd and a compatible card reader (unless you only operate on saved files)
pcsc-tools (not really a dependency, but useful in the environment)

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 https://gitlab.com/chrysn/carddecoders/
$ 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

`bytestring`

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.

Connections

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.

Conversations

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.

`nonblocking`

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.