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

* @piSim-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

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

h2. Usage instructions

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

* Connect SIM card reader.

* Insert programmable SIM card

h3. 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_

h3. Get the code of PySIM by entering command:

<pre>

 git clone https://gitea.osmocom.org/sim-card/pysim

</pre>

<pre>

 cd pysim

</pre>

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

h3. Program (very few fields of) your SIM card using legacy pySim-prog

* Enter   @./pySim-prog.py -help@   to get overview of possible options. 

Similar result should appear: 

 $ ./pySim-prog.py -help

 Usage: pySim-prog.py [options]

 Options:

   -h, --help            show this help message and exit

   -d DEV, --device=DEV  Serial Device for SIM access [default: /dev/ttyUSB0]

   -b BAUD, --baud=BAUD  Baudrate used for SIM access [default: 9600]

   -p PCSC, --pcsc-device=PCSC

                         Which PC/SC reader number for SIM access

   -t TYPE, --type=TYPE  Card type (user -t list to view) [default: auto]

   -a PIN_ADM, --pin-adm=PIN_ADM

                         ADM PIN used for provisioning (overwrites default)

   -e, --erase           Erase beforehand [default: False]

   -S SOURCE, --source=SOURCE

                         Data Source[default: cmdline]

   -n NAME, --name=NAME  Operator name [default: Magic]

   -c CC, --country=CC   Country code [default: 1]

   -x MCC, --mcc=MCC     Mobile Country Code [default: 901]

   -y MNC, --mnc=MNC     Mobile Network Code [default: 55]

   -m SMSC, --smsc=SMSC  SMSP [default: '00 + country code + 5555']

   -M SMSP, --smsp=SMSP  Raw SMSP content in hex [default: auto from SMSC]

   -s ID, --iccid=ID     Integrated Circuit Card ID

   -i IMSI, --imsi=IMSI  International Mobile Subscriber Identity

   -k KI, --ki=KI        Ki (default is to randomize)

   -o OPC, --opc=OPC     OPC (default is to randomize)

   --op=OP               Set OP to derive OPC from OP and KI

   --acc=ACC             Set ACC bits (Access Control Code). not all card types

                         are supported

   -z STR, --secret=STR  Secret used for ICCID/IMSI autogen

   -j NUM, --num=NUM     Card # used for ICCID/IMSI autogen

   --batch               Enable batch mode [default: False]

   --batch-state=FILE    Optional batch state file

   --read-csv=FILE       Read parameters from CSV file rather than command line

   --write-csv=FILE      Append generated parameters in CSV file

   --write-hlr=FILE      Append generated parameters to OpenBSC HLR sqlite3

   --dry-run             Perform a 'dry run', don't actually program the card

h3. Example of how to program a sysmoSIM-GR1 card 

The GRcard SIM is a programmable GSM SIM card. It uses a mixture of TS11.11 / ISO7816-4 and proprietary commands for programming.

In the below example, we are changing the card’s IMSI to 901700000003080 (option -i) and we are specifying a new set of -n NAME (Operator name), -t TYPE (Card type), -c CC (Country code), -x MCC (Mobile Country Code), -y MNC (Mobile Network Code) and -s ID (Integrated Circuit Card ID) values.

 $ ./pySim-prog.py -p 0 -n OpenBSC -t sysmosim-gr1 -i 901700000003080 -c 001 -x 001 -y 02 -s 1791198229180000075

 Insert card now (or CTRL-C to cancel)

 Generated card parameters :

  > Name    : OpenBSC

  > SMSP    : e1ffffffffffffffffffffffff0581005155f5ffffffffffff000000

  > ICCID   : 1791198229180000075

  > MCC/MNC : 1/2

  > IMSI    : 901700000003080

  > Ki      : 7edaeb6addbd72d2b2cc6ed7bfecc9c9

  > OPC     : 23f075ab9b1a113d4db822d8195ea20c

  > ACC     : None

 Programming ...

 Done !

h3. Example of how to program a sysmoUSIM-SJS1 card

(U)SIM cards are Java capable and there is the Globalplatform that specifies standards API. SMS can be addressed directly to the SIM card, the SIM card will get events for network selection and others, it can modify call establishment attempts.

Provisioning of different identities or keys.

If you have a variant of the card-individual ADM1 key of your sysmoUSIM-SJS1 card,  you can change any identity (IMSI, ICCID, MSISDN) stored on the (U)SIM, as well as the private key data (K, OPC).

In the below example, we are changing the card’s IMSI to 901700000003080 (option -i) and we are specifying a new set of -t TYPE (Card type), - a ADM_PIN (ADM PIN used for provisioning), -x MCC (Mobile Country Code), -y MNC (Mobile Network Code), -s ID (Integrated Circuit Card ID), -o OPC and -k KI (Ki) values.

 $ ./pySim-prog.py -p 0 -t sysmoUSIM-SJS1 -a 58001006  -x 901 -y 71 -i 901700000010659 -s 8988211000000110000 -o 398153093661279FB1FC74BE07059FEF -k 1D8B2562B992549F20D0F42113EAA6FA

 Insert card now (or CTRL-C to cancel)

 Generated card parameters :

  > Name    : Magic

  > SMSP    : e1ffffffffffffffffffffffff0581005155f5ffffffffffff000000

  > ICCID   : 8988211000000110000

  > MCC/MNC : 901/71

  > IMSI    : 901700000010659

  > Ki      : 1D8B2562B992549F20D0F42113EAA6FA

  > OPC     : 398153093661279FB1FC74BE07059FEF

  > ACC     : None

 Programming ...

 Done !

h3. Example of how to program a Magic SIM / SuperSIM 16-in-1 / X-sim card

The 16-in-1 SIM cards are intended for COMP128v1 based cloning and enable the user to aggregate up to 16 SIM card identities in a single card. This multi-IMSI property is not used in the context of Osmocom.

Below example shows how we can change the card’s IMSI to 901990000000018 (option -i) and at the same time we are specifying a new set of -x MCC (Mobile Country Code), -y MNC (Mobile Network Code), -s ID (Integrated Circuit Card ID) , -o OPC and -k KI (Ki) values.

 $ ./pySim-prog.py -p 0 -x 801 -y 71 -i 901990000000018 -s 8988211000000110000 -o 398153093661279FB1FC74BE07059FEF -k 1D8B2562B992549F20D0F42113EAA6FA

 Insert card now (or CTRL-C to cancel)

 Autodetected card type fakemagicsim

 Generated card parameters :

  > Name    : Magic

  > SMSP    : e1ffffffffffffffffffffffff0581005155f5ffffffffffff000000

  > ICCID   : 8988211000000110000

  > MCC/MNC : 801/71

  > IMSI    : 901990000000018

  > Ki      : 1D8B2562B992549F20D0F42113EAA6FA

  > OPC     : 398153093661279FB1FC74BE07059FEF

  > ACC     : None

 Programming ...

 Done !

h3. Continuous Integration / Automatic Testing

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

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