SIM card related Projects » pySim

{{>toc}}

h1. pySim WiKi 

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

h2. Supported Cards

* [[cellular-infrastructure:SysmoUSIM-SJS1]]

* [[cellular-infrastructure:GrcardSIM]]

* [[cellular-infrastructure:GrcardSIM2]]

* [[cellular-infrastructure:MagicSIM]]

h3. 1. Firstly install dependencies

 sudo apt-get install pcscd pcsc-tools libccid libpcsclite-dev

h3. 2. Connected your SIM card reader

h3. 3. Plug in it your programmable SIM card

h3. 4. Check the status of connection by execution of the following command:

 pcsc_scan

h3. 5. If SIM card reader is recognised then we can expect 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

h3. 6. Exit pcsc_scan : Ctrl+C

h3. 7. Get the code of PySIM by entering command:

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

 cd pysim

h3. 8. Run the /pySim-read.py to read your SIM card:

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

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

h3. 9.1. in case of sysmoUSIM-SJS1 SIM card, you will see something similar to:

 $ ./pySim-read.py -p0

 Reading ...

 ICCID: 8988211000000106594

 IMSI: 901700000010659

 SMSP: ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff

 ACC: 0200

 MSISDN: Not available

 Done !

h3. 9.2. in case of SuperSIM/X-sim card, you will see something similar to:

 $ ./pySim-read.py -p0

 Reading ...

 ICCID: 8949901990000000184

 IMSI: 901990000000018

 SMSP: ffffffffffffffffffffffffe1ffffffffffffffffffffffff058100945555ffffffffffff000000

 ACC: ffff

 MSISDN: Not available

 Done !

h3. 10. SIM cards programming 

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. 11. Programming examples

h4. 11.1 Programming example of 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.

 $ ./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 !

h4. 11.2 Programming example of a SysmoUSIM-SJS1 (orange) 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).

ADM1 key can be found at:

[https://openerp.sysmocom.de/web#page=0&limit=80&view_type=list&model=sysmocom.simcard&menu_id=679&action=912]

In the below example, we are changing the card’s IMSI to 901710000011000 (it was 901700000011000 before), and specify a

new set of K and OPC 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. 12 README 

pySim comes with following README file:

This utility allows to :

* Program customizable SIMs. Two modes are possible:

- one where you specify every parameter manually :

./pySim-prog.py -n 26C3 -c 49 -x 262 -y 42 -i <IMSI> -s <ICCID>

- one where they are generated from some minimal set :

./pySim-prog.py -n 26C3 -c 49 -x 262 -y 42 -z <random_string_of_choice> -j <card_num>

With <random_string_of_choice> and <card_num>, the soft will generate

'predictable' IMSI and ICCID, so make sure you choose them so as not to

conflict with anyone. (for eg. your name as <random_string_of_choice> and

0 1 2 ... for <card num>).

You also need to enter some parameters to select the device :

-t TYPE : type of card (supersim, magicsim, fakemagicsim or try 'auto')

-d DEV  : Serial port device (default /dev/ttyUSB0)

-b BAUD : Baudrate (default 9600)

* Interact with SIMs from a python interactive shell (ipython for eg :)

from pySim.transport.serial import SerialSimLink

from pySim.commands import SimCardCommands

sl = SerialSimLink(device='/dev/ttyUSB0', baudrate=9600)

sc = SimCardCommands(sl)

sl.wait_for_card()

# Print IMSI

print sc.read_binary(['3f00', '7f20', '6f07'])

# Run A3/A8

print sc.run_gsm('00112233445566778899aabbccddeeff')