card

This is a Python project to help reading and accessing smartcards, mostly focused on telecom smartcards and SIMs. The project was originally developped around 2009, and keeps being maintained. Any feedback and contribution are always welcomed !

Table Of Content

Background
Structure
Install
- Prerequisites
- Library install
Usage
Contributing
License
Examples

Background

Smartcards with electrical connectors are in general all compliant with the basis standard ISO7816 - part 1-2-3-4. Most of the ISO standards are not public, but you can have a good view on ISO7816 here: cardwerk website The principle is to communicate with the card over a serial interface, sending APDU commands, and receiving replies with always 2 bytes of SW codes and eventually more byte of data.

All the Subscriber Identity Module (abbr. SIM) and USIM cards are based on this ISO 7816 standard. They are additionally based on ETSI and 3GPP standards. ETSI standards are public, see ETSI ; 3GPP standards are too, see 3GPP.

SIM cards are easy to read as they are only mono-application: check 3GPP TS 11.11 or TS 51.011. UICC / USIM cards are some more evolved as they are multi-applications / multi-channels cards: check ETSI TS 101.221 and 3GPP TS 31.101 and 31.102. Moreover, recent cards often holds more application, such as from GlobalPlatform (abbr. GP), and may also support contact-less access based on the ISO 14443 standard.

The following card library has been developped mostly for experiencing with SIM and USIM cards, with a focus on they security procedures (e.g. mobile subscriber authentication). Most of its content stays quite experimental.

It was originally developped for Python 2.6, supporting then Python 2.7. Some efforts were made to support Python 3 (starting with 3.5). Most of the library is known to work on Python 3, but it could happen that some methods or functions have not been perfectly migrated.

Structure

The library is entirely made of Python files under the card directory.

It is splitted into the following files:

utils.py: contains facilities for parsing TV, TLV, BER_TLV records and some other utility functions
ICC.py: contains the 2 main classes:
- ISO7816: which implements a little part of the ISO7816 (mainly part 4) standard
- UICC: which implements part of the ETSI standard, and inherits from the ISO7816 class
SIM.py: contains the SIM class inheriting from the ISO7816 class, implementing part of TS 51.011
USIM.py: contains the USIM class inheriting from the UICC class, implementing part of TS 31.102
FS.py: dictionnaries refencing SIM and USIM files addresses as described in those 3GPP standards
GP.py: contains the GP class inheriting from the UICC class, implementing few basic methods for application recognition
EMV.py: contains the EMV class inheriting from the UICC class, only supporting basic EMV AID scanning

Morevoer, scripts to configure sysmocom SIM / USIM cards are provided:

prog_sysmo_sim.py: for programming the old sysmo-SIM
prog_sysmo_usim.py: for programming the old sysmo-USIM
prog_sysmo_sjs1.py: for programming the sysmo-USIM-SJS1

Install

Prerequisites

First of all, you need a smartcard reader. Some laptops have one integrated, otherwise, you can find USB-based readers (a well-known USB-reader provider is OmniKey).

Then, you need a middleware in your OS that will drive the smartcard reader and expose a PC-SC (for PC SmartCard) compliant API. Windows has a built-in smartcard service, Linux has the pcsc-lite project. This last one is packaged for all the main distribs, and installing is often a matter of apt install pcscd or rpm -ivh pcsc-lite.

Finally, you need the Python wrapper for the PCSC API, which is brought by the pyscard project.

Optionally, you may need pydot which is required in case you want to generate a nice picture of your SIM card's filesystem graph, after scanning it.

Library install

A setup.py script is provided at the root of the project, you just need to use it to install the library (system-wide with sudo, or only for your user).

python3 setup.py install

Usage

The library as such does not provide any specific service or application. If you are interested to use it to build you own application, you can check the several examples, for a quick view on the main classes and methods that may be of interest. Otherwise, you can check the docstrings which are provided for most of the classes and methods, or more simply check at the source code.

The 3 scripts prog_sysmo_*.py can be used through their personnalize() class. You will however need first to adapt / update their content for the different files you want to update in your SIM or USIM card.

Contributing

Any contribution is always very welcomed ! It can come in different ways:

in case you find some bugs, please open an issue in the project issue tracker, and provide detailed information regarding your configuration and the bug you encountered ;
in case you fixed a bug, or you did a nice addition or extension, do not hesitate to submit a pull request ;
in case you are using this project in one of your application, or you just find it useful, do not hesitate to send an email: getting feedback is always a pleasure.

Please refrain from opening an issue however before you have read all the README. Most of the basic questions regarding this project may be answered here.

License

The project was historically licensed under the GPLv2, when it was originally released. The detail of the license is provided in the license.txt file.

Examples

Here is a series of examples for using the main classes and methods of the library. When communicating with the smartcard, pyscard uses list of bytes (uint8 values). Every APDU and communication with the smartcard is handled in this way also by card.

ISO7816 session

The ISO7816 class within the ICC module provides basic methods for many of the ISO7816 commands, together with a method to interpret SW codes returned by the card and methods to work with the smartcard filesystem. It does not provide high-level methods and may not be of great help if you want to simply work with SIM cards. It provides however the following methods useful to do some scanning of a card: ATR_scan(), bf_cla() and bf_ins(). The last 2 methods being dangerous, I am not using them that often !

In [1]: from card.ICC import *

In [2]: c = ISO7816()

In [3]: c.ATR_scan()

smartcard reader: Alcor Micro AU9560 00 00

smart card ATR is: 3B 9F 96 80 3F C7 A0 80 31 E0 73 FE 21 1B 64 07 68 9A 00 82 90 00 B4
ATR analysis: 
TA1: 96
TD1: 80
TD2: 3f
TA3: c7
TB3: a0
supported protocols T=0,T=15
T=0 supported: True
T=1 supported: False
checksum: 180
	clock rate conversion factor: 512
	bit rate adjustment factor: 32
	maximum programming current: 50
	programming voltage: 5
	guard time: None
nb of interface bytes: 5
nb of historical bytes: 15
None

historical bytes: 80 31 E0 73 FE 21 1B 64 07 68 9A 00 82 90 00
checksum: 0xB4

using pcsc_scan ATR list file: /usr/share/pcsc/smartcard_list.txt
no ATR fingerprint found in file: /usr/share/pcsc/smartcard_list.txt

In [4]: help(c.bf_cla)
Signature: c.bf_cla(start=0, param=[164, 0, 0, 2, 63, 0])
Docstring:
bf_cla( start=int(starting CLA), 
        param=list(bytes for selecting file 0x3F, 0x00) ) ->
    list( CLA which could be supported )
    
tries all classes CLA codes to check the possibly supported ones
prints CLA suspected to be supported
returns the list of those CLA codes

WARNING: 
can block the card definitively
Do not do it with your own VISA / MASTERCARD
File:      ~/src/card/card/ICC.py
Type:      method

In [5]: help(c.bf_ins)
Signature: c.bf_ins(start=0)
Docstring:
bf_cla( start=int(starting INS) ) 
    -> list( INS which could be supported )
    
tries all instructions INS codes to check the supported ones
prints INS suspected to be supported
returns the list of those INS codes

WARNING: 
can block the card definitively
Do not do it with your own VISA / MASTERCARD
File:      ~/src/card/card/ICC.py
Type:      method

In [8]: c.bf_ins()
[DBG] (INS bruteforce) ['apdu: 00 00 00 00', 'sw1, sw2: 6E 00 - checking error: class not supported', (110, 0), []]
[DBG] (INS bruteforce) ['apdu: 00 01 00 00', 'sw1, sw2: 6E 00 - checking error: class not supported', (110, 0), []]
[DBG] (INS bruteforce) ['apdu: 00 02 00 00', 'sw1, sw2: 6E 00 - checking error: class not supported', (110, 0), []]
[DBG] (INS bruteforce) ['apdu: 00 03 00 00', 'sw1, sw2: 6E 00 - checking error: class not supported', (110, 0), []]
[DBG] (INS bruteforce) ['DEACTIVATE FILE apdu: 00 04 00 00', 'sw1, sw2: 69 86 - checking error: command not allowed: command not allowed (no current EF)', (105, 134), []]
[DBG] (INS bruteforce) ['apdu: 00 05 00 00', 'sw1, sw2: 6E 00 - checking error: class not supported', (110, 0), []]
[DBG] (INS bruteforce) ['apdu: 00 06 00 00', 'sw1, sw2: 6E 00 - checking error: class not supported', (110, 0), []]
[DBG] (INS bruteforce) ['apdu: 00 07 00 00', 'sw1, sw2: 6E 00 - checking error: class not supported', (110, 0), []]
[DBG] (INS bruteforce) ['apdu: 00 08 00 00', 'sw1, sw2: 6E 00 - checking error: class not supported', (110, 0), []]
[DBG] (INS bruteforce) ['apdu: 00 09 00 00', 'sw1, s

Card

Install / Use

README