pySim WiKi¶

• Table of contents
• pySim WiKi
  • Supported Cards
  • Supported Card Interfaces ("Readers")
  • Documentation
    • User Manual
    • Video on pySim-shell usage
    • Installation instructions
    • Usage instructions
      • Check the status of connection by entering the following command:
      • Read (a few fields of) your SIM card
      • bulk programming of some common SIM parameters
      • interactive exploration and/or programming of any parameter in any file
  • Continuous Integration / Automatic Testing
• Commercial Support

pySim is a suite of programs (develped in python) for interfacing with SIM/UICC/USIM/ISIM cards.

• pySim-shell is an interactive command line tool for navigating around the card file system, reading/writing data to the files as well as administrative commands. It is the most sophisticated general purpose tool of the pySim suite and has long surpassed the capabilities of its older cousins like pySim-prog.
• pySim-prog is a small command line utility for programming a small subset of parameters like IMSI, K, OP[c], SMSP in (batches of) various programmable SIM/USIM cards.
• pySim-read is a small command line utility for reading some commonly used fields of a SIM card
• pySim-trace is a high-level decoder of SIM card protocol traces (for example, traces generated by SIMtrace2)

Such SIM/USIM cards are special cards, which - unlike those issued by regular commercial operators - come with the kind of keys that allow you to write the files/fields that normally only an operator can program.

This is useful particularly if you are running your own cellular network, and want to issue your own SIM/USIM cards for that network.

Supported Cards¶

• Generic SIM/UICC/USIM/ISIM card
  • only ETSI/3GPP standard files supported on generic cards
  • writing of most fields is typically not possible as nobody except the card-issuing operator posesses the keys / ADM1 PIN to write
• Actively supported, fully programmable cards
  • sysmoISIM-SJA2 (3GPP Release 16 SIM + USIM + ISIM)
  • sysmoISIM-SJA5 (3GPP Release 17 SIM + USIM + ISIM + HPSIM)
• Older fully programmable cards
  • sysmoUSIM-SJS1 (SIM + USIM)
• Older much less configurable cards
  • GrcardSIM (SIM)
  • GrcardSIM2 (SIM)
  • MagicSIM (SIM)

Supported Card Interfaces ("Readers")¶

The best-supported/recommended configuration is to use a Smart Card Interface device compliant with the USB CCID specification, using the libccid/pcsc-lite driver stack.

However, pySim supports multiple card interface back-ends:

• pcsc: any reader suppored by pcsc-lite
  • pcsc-lite supports any reader that provides a so-called ifd_handler driver. Those could come e.g. from reader vendors, but
  • pcsc-lite is very well integrated with libccid, whose reader support status is indicated at https://ccid.apdu.fr/ccid/section.html
• serial: simple serial/UART based readers, as sometimes shipped with GRcard SIMs
• calypso: A calypso chipset based mobile phone runnung OsmocomBB
• modem_atcmd: Any cellular modem offering the AT+CSIM command

The pySim developers as well as the continuous integration / automatic testing are utilizing USB-CCID readers via pcsc-lite. Your milage with other backends (not used much, not automatically tested) may vary!

Documentation¶

User Manual¶

The manual / documentation can be built from the source code by (cd docs && make html latexpdf).

Pre-rendered versions of the current master branch are available as PDF and HTML

Video on pySim-shell usage¶

On April 9. 2021 laforge gave a presentation on @pySim-shell, a video recording can be found at
https://people.osmocom.org/tnt/osmodevcall/osmodevcall-20210409-laforge-pysim-shell_h264_420.mp4

Installation instructions¶

Please follow the instructions provided in [source:README.md]

Usage instructions¶

• Connect SIM card reader.
• Insert programmable SIM card

Check the status of connection by entering the following command:¶

 pcsc_scan

• If SIM card reader is recognised then we can expect something similar to the below output:

 $ pcsc_scan
 PC/SC device scanner
 V 1.4.25 (c) 2001-2011, Ludovic Rousseau ludovic.rousseau@free.fr
 Compiled with PC/SC lite version: 1.8.14
 Using reader plug'n play mechanism
 Scanning present readers...
 0: SCM Microsystems Inc. SCR 3310 [CCID Interface] 00 00 
 Tue Oct 18 11:48:08 2016
 Reader 0: SCM Microsystems Inc. SCR 3310 [CCID Interface] 00 00
 Card state: Card inserted, 
 ATR: 3B 99 18 00 11 88 22 33 44 55 66 77 60
 + TS = 3B --> Direct Convention
 + T0 = 99, Y(1): 1001, K: 9 (historical bytes)
  TA(1) = 18 --> Fi=372, Di=12, 31 cycles/ETU
  129032 bits/s at 4 MHz, fMax for Fi = 5 MHz => 161290 bits/s
  TD(1) = 00 --> Y(i+1) = 0000, Protocol T = 0 
 -----
 + Historical bytes: 11 88 22 33 44 55 66 77 60
 Category indicator byte: 11 (proprietary format)
 Possibly identified card (using /usr/share/pcsc/smartcard_list.txt):
 3B 99 18 00 11 88 22 33 44 55 66 77 60
 sysmocom sysmoSIM-GR1

• Exit pcsc_scan : Ctrl+C

Read (a few fields of) your SIM card¶

./pySim-read.py -p0 or ./pySim-read.py -p1

• Using sysmoSIM-GR1 and if everything is done correctly, you will see something similar to:

 $ ./pySim-read.py -p0 
 Reading ...
 ICCID: 1791198229180000071
 IMSI: 001640000000071
 SMSP: ffffffffffffffffffffffffe1ffffffffffffffffffffffff0581005155f5ffffffffffff000000
 ACC: ffff
 MSISDN: Not available
 Done !

bulk programming of some common SIM parameters¶

See pySim-prog

interactive exploration and/or programming of any parameter in any file¶

See pySim-shell

Continuous Integration / Automatic Testing¶

pySim is continuously and automatically tested by a TestRig run by sysmocom

Commercial Support¶

Commercial support as well as development, system integration and training services for this project are available from sysmocom