SIM card related Projects » pySim

h1. pySim WiKi

{{>toc}}

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.

h2. 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

** [[cellular-infrastructure:sysmoISIM-SJA2]] (3GPP Release 16 SIM + USIM + ISIM)

** [[cellular-infrastructure:sysmoISIM-SJA5]] (3GPP Release 17 SIM + USIM + ISIM + HPSIM)

* Older fully programmable cards

** [[cellular-infrastructure:sysmoUSIM-SJS1]] (SIM + USIM)

* Older much less configurable cards

** [[cellular-infrastructure:GrcardSIM]] (SIM)

** [[cellular-infrastructure:GrcardSIM2]] (SIM)

** [[cellular-infrastructure:MagicSIM]] (SIM)

h2. 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":https://pcsclite.apdu.fr/

** 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":https://ccid.apdu.fr/, 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!

h2. Documentation

h3. 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":https://ftp.osmocom.org/docs/latest/osmopysim-usermanual.pdf and "HTML":https://downloads.osmocom.org/docs/latest/pysim/

h3. Video on pySim-shell usage

|_.Title|_.Event|_.Date|

|"pySim-shell - next generation SIM configuration tool":https://people.osmocom.org/tnt/osmodevcall/osmodevcall-20210409-laforge-pysim-shell_h264_420.mp4|OsmoDevCall|2021-04-09|

|"Using pySim-shell on sysmoISIM-SJA5 cards":https://media.ccc.de/v/osmodevcall-20231220-laforge-pysim-shell-sysmoisim-sja5|OsmoDevCall|2023-12-20|

|"Exploring eUICCs and eSIMs using pySim, lpac and osmo-smdpp":https://media.ccc.de/v/osmodevcall-20240117-laforce-euicc-esim|OsmoDevCall|2024-01-17|

h3. Recorded lectures on SIM/USIM/UICC technology

|_.Title|_.Event|_.Date|

|"SIM Card technology from A-Z":https://media.ccc.de/v/36c3-10737-sim_card_technology_from_a-z|36C3|2019-12-27|

|"SIM card profile creation, personalization, production":https://media.ccc.de/v/osmodevcall-20211022-laforge-sim|OsmoDevCall|2021-10-22|

|"Advanced SIM Card topics: SCP02, OTA, ARA-M, ISIM":https://media.ccc.de/v/osmodevcall-20220225-laforge-advanced-sim-topics|OsmoDevCall|2022-02-25|

|"Demystifying eSIM Technology":https://media.ccc.de/v/camp2023-57190-demystifying_esim_technology|ccccamp2023|2023-09-15|

|"GlobalPlatform in USIM and eUICC":https://media.ccc.de/v/osmodevcon2024-173-globalplatform-in-usim-and-euicc|OsmoDevCon2024|2024-05-04|

|"Detailed workings of OTA for SIM/USIM/eUICC":https://media.ccc.de/v/osmodevcon2024-175-detailed-workings-of-ota-for-sim-usim-euicc|OsmoDevCon2024|2024-05-04|

|"onomondo softsim":https://media.ccc.de/v/osmodevcon2024-180-onomondo-softsim-a-software-usim-implementation|OsmoDevCon2024|2024-05-04|

h3. Installation instructions

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

h3. Usage instructions

* Connect SIM card reader.

* Insert programmable SIM card

h4. Check the status of connection by entering the following command:

<pre>

 pcsc_scan

</pre>

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

<pre>

 $ 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

</pre>

** Exit pcsc_scan : _Ctrl+C_

h4. 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:

<pre>

 $ ./pySim-read.py -p0 

 Reading ...

 ICCID: 1791198229180000071

 IMSI: 001640000000071

 SMSP: ffffffffffffffffffffffffe1ffffffffffffffffffffffff0581005155f5ffffffffffff000000

 ACC: ffff

 MSISDN: Not available

 Done !

</pre>

h4. bulk programming of some common SIM parameters

See [[pySim-prog]] 

h4. interactive exploration and/or programming of any parameter in any file

See [[pySim-shell]]

h2. Continuous Integration / Automatic Testing

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

{{include(cellular-infrastructure:MacroCommercialSupport)}}