Project

General

Profile

pySim WiKi

pySim-prog is a small command line utility written in python, which is used for programming various programmable SIM/USIM cards.

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

Usage instructions

Install dependencies:

 sudo apt-get install pcscd pcsc-tools libccid libpcsclite-dev python-pyscard
  • 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

Get the code of PySIM by entering command:

 git clone git://git.osmocom.org/pysim pysim
 cd pysim

Read 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 !

Program your SIM card

  • 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

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 !

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 !

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 !

README

pySim comes with following README file:

https://git.osmocom.org/pysim/tree/README