Project

General

Profile

Wiki » History » Version 45

laforge, 05/05/2020 08:20 PM

1 40 fixeria
h1. pySim WiKi
2 4 wirelesss
3 40 fixeria
{{>toc}}
4 1 laforge
5
pySim-prog is a small command line utility written in python, which is used for programming various programmable SIM/USIM cards.
6
7 39 laforge
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.
8
9
This is useful particularly if you are running your own cellular network, and want to issue your own SIM/USIM cards for that network.
10
11 37 wirelesss
h2. Supported Cards
12 1 laforge
13 33 wirelesss
* [[cellular-infrastructure:sysmoUSIM-SJS1]]
14 1 laforge
* [[cellular-infrastructure:GrcardSIM]]
15
* [[cellular-infrastructure:GrcardSIM2]]
16
* [[cellular-infrastructure:MagicSIM]]
17
18 41 laforge
h2. Supported Readers
19
20
pySim-prog supports two readar back-ends:
21
22
* simple serial/UART based readers, as sometimes shipped with GRcard SIMs
23
* any reader suppored by "pcsc-lite":https://pcsclite.apdu.fr/
24
** pcsc-lite supports any reader that provides a so-called @ifd_handler@ driver. Those could come e.g. from reader vendors, but
25
** pcsc-lite is very well integrated with "libccid":https://ccid.apdu.fr/ccid, whose reader support status is indicated at https://ccid.apdu.fr/ccid/section.html
26 1 laforge
27 37 wirelesss
h2. Usage instructions
28 1 laforge
29
30 37 wirelesss
h3. Install dependencies:
31
32
<pre>
33 38 wirelesss
 sudo apt-get install pcscd pcsc-tools libccid libpcsclite-dev python-pyscard
34 37 wirelesss
</pre>
35 36 neels
36 37 wirelesss
* Connect SIM card reader.
37 16 wirelesss
38 37 wirelesss
* Insert programmable SIM card
39 1 laforge
40 37 wirelesss
h3. Check the status of connection by entering the following command:
41 1 laforge
42 37 wirelesss
<pre>
43 34 wirelesss
 pcsc_scan
44 37 wirelesss
</pre>
45 5 wirelesss
46 37 wirelesss
* If SIM card reader is recognised then we can expect something similar to the below output:
47 32 wirelesss
48 37 wirelesss
<pre>
49 5 wirelesss
 $ pcsc_scan
50
 PC/SC device scanner
51
 V 1.4.25 (c) 2001-2011, Ludovic Rousseau ludovic.rousseau@free.fr
52
 Compiled with PC/SC lite version: 1.8.14
53
 Using reader plug'n play mechanism
54
 Scanning present readers...
55
 0: SCM Microsystems Inc. SCR 3310 [CCID Interface] 00 00 
56
 Tue Oct 18 11:48:08 2016
57
 Reader 0: SCM Microsystems Inc. SCR 3310 [CCID Interface] 00 00
58
 Card state: Card inserted, 
59
 ATR: 3B 99 18 00 11 88 22 33 44 55 66 77 60
60
 + TS = 3B --> Direct Convention
61
 + T0 = 99, Y(1): 1001, K: 9 (historical bytes)
62 20 wirelesss
  TA(1) = 18 --> Fi=372, Di=12, 31 cycles/ETU
63 1 laforge
  129032 bits/s at 4 MHz, fMax for Fi = 5 MHz => 161290 bits/s
64 20 wirelesss
  TD(1) = 00 --> Y(i+1) = 0000, Protocol T = 0 
65 1 laforge
 -----
66
 + Historical bytes: 11 88 22 33 44 55 66 77 60
67 20 wirelesss
 Category indicator byte: 11 (proprietary format)
68 1 laforge
 Possibly identified card (using /usr/share/pcsc/smartcard_list.txt):
69
 3B 99 18 00 11 88 22 33 44 55 66 77 60
70
 sysmocom sysmoSIM-GR1
71 20 wirelesss
72 37 wirelesss
</pre>
73 20 wirelesss
74 37 wirelesss
** Exit pcsc_scan : _Ctrl+C_
75 20 wirelesss
76 1 laforge
77 37 wirelesss
h3. Get the code of PySIM by entering command:
78
79
<pre>
80 1 laforge
 git clone git://git.osmocom.org/pysim pysim
81 37 wirelesss
</pre>
82 1 laforge
83 37 wirelesss
<pre>
84 5 wirelesss
 cd pysim
85 37 wirelesss
</pre>
86 32 wirelesss
87 37 wirelesss
h3. Read your SIM card
88 5 wirelesss
89
 ./pySim-read.py -p0 or ./pySim-read.py -p1 
90 32 wirelesss
91 37 wirelesss
* Using sysmoSIM-GR1 and if everything is done correctly, you will see something similar to:
92 1 laforge
 
93 37 wirelesss
<pre>
94 1 laforge
 $ ./pySim-read.py -p0 
95 5 wirelesss
 Reading ...
96
 ICCID: 1791198229180000071
97
 IMSI: 001640000000071
98
 SMSP: ffffffffffffffffffffffffe1ffffffffffffffffffffffff0581005155f5ffffffffffff000000
99
 ACC: ffff
100
 MSISDN: Not available
101
 Done !
102
103 37 wirelesss
</pre>
104 5 wirelesss
105 37 wirelesss
h3. Program your SIM card
106 17 wirelesss
107 37 wirelesss
* Enter   @./pySim-prog.py -help@   to get overview of possible options. 
108 1 laforge
109 7 wirelesss
Similar result should appear: 
110 5 wirelesss
111
 $ ./pySim-prog.py -help
112
 Usage: pySim-prog.py [options]
113
 Options:
114
   -h, --help            show this help message and exit
115
   -d DEV, --device=DEV  Serial Device for SIM access [default: /dev/ttyUSB0]
116
   -b BAUD, --baud=BAUD  Baudrate used for SIM access [default: 9600]
117
   -p PCSC, --pcsc-device=PCSC
118
                         Which PC/SC reader number for SIM access
119
   -t TYPE, --type=TYPE  Card type (user -t list to view) [default: auto]
120
   -a PIN_ADM, --pin-adm=PIN_ADM
121
                         ADM PIN used for provisioning (overwrites default)
122
   -e, --erase           Erase beforehand [default: False]
123
   -S SOURCE, --source=SOURCE
124
                         Data Source[default: cmdline]
125
   -n NAME, --name=NAME  Operator name [default: Magic]
126
   -c CC, --country=CC   Country code [default: 1]
127
   -x MCC, --mcc=MCC     Mobile Country Code [default: 901]
128
   -y MNC, --mnc=MNC     Mobile Network Code [default: 55]
129
   -m SMSC, --smsc=SMSC  SMSP [default: '00 + country code + 5555']
130
   -M SMSP, --smsp=SMSP  Raw SMSP content in hex [default: auto from SMSC]
131
   -s ID, --iccid=ID     Integrated Circuit Card ID
132
   -i IMSI, --imsi=IMSI  International Mobile Subscriber Identity
133 1 laforge
   -k KI, --ki=KI        Ki (default is to randomize)
134 5 wirelesss
   -o OPC, --opc=OPC     OPC (default is to randomize)
135
   --op=OP               Set OP to derive OPC from OP and KI
136
   --acc=ACC             Set ACC bits (Access Control Code). not all card types
137
                         are supported
138
   -z STR, --secret=STR  Secret used for ICCID/IMSI autogen
139
   -j NUM, --num=NUM     Card # used for ICCID/IMSI autogen
140
   --batch               Enable batch mode [default: False]
141
   --batch-state=FILE    Optional batch state file
142
   --read-csv=FILE       Read parameters from CSV file rather than command line
143
   --write-csv=FILE      Append generated parameters in CSV file
144
   --write-hlr=FILE      Append generated parameters to OpenBSC HLR sqlite3
145
   --dry-run             Perform a 'dry run', don't actually program the card
146 32 wirelesss
147 37 wirelesss
h3. Example of how to program a sysmoSIM-GR1 card 
148 18 wirelesss
149 5 wirelesss
The GRcard SIM is a programmable GSM SIM card. It uses a mixture of TS11.11 / ISO7816-4 and proprietary commands for programming.
150
151 1 laforge
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.
152
 
153 25 wirelesss
 $ ./pySim-prog.py -p 0 -n OpenBSC -t sysmosim-gr1 -i 901700000003080 -c 001 -x 001 -y 02 -s 1791198229180000075
154 5 wirelesss
 Insert card now (or CTRL-C to cancel)
155
 Generated card parameters :
156
  > Name    : OpenBSC
157
  > SMSP    : e1ffffffffffffffffffffffff0581005155f5ffffffffffff000000
158
  > ICCID   : 1791198229180000075
159
  > MCC/MNC : 1/2
160
  > IMSI    : 901700000003080
161
  > Ki      : 7edaeb6addbd72d2b2cc6ed7bfecc9c9
162
  > OPC     : 23f075ab9b1a113d4db822d8195ea20c
163
  > ACC     : None
164 1 laforge
 Programming ...
165 5 wirelesss
 Done !
166 32 wirelesss
167 37 wirelesss
h3. Example of how to program a sysmoUSIM-SJS1 card
168 31 wirelesss
169 5 wirelesss
(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.
170
171
172
Provisioning of different identities or keys.
173 13 wirelesss
 
174 5 wirelesss
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).
175
176 1 laforge
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.
177 26 wirelesss
178 5 wirelesss
 $ ./pySim-prog.py -p 0 -t sysmoUSIM-SJS1 -a 58001006  -x 901 -y 71 -i 901700000010659 -s 8988211000000110000 -o 398153093661279FB1FC74BE07059FEF -k 1D8B2562B992549F20D0F42113EAA6FA
179 11 wirelesss
 Insert card now (or CTRL-C to cancel)
180 5 wirelesss
 Generated card parameters :
181
  > Name    : Magic
182
  > SMSP    : e1ffffffffffffffffffffffff0581005155f5ffffffffffff000000
183
  > ICCID   : 8988211000000110000
184
  > MCC/MNC : 901/71
185 6 wirelesss
  > IMSI    : 901700000010659
186 5 wirelesss
  > Ki      : 1D8B2562B992549F20D0F42113EAA6FA
187
  > OPC     : 398153093661279FB1FC74BE07059FEF
188
  > ACC     : None
189 6 wirelesss
 Programming ...
190 5 wirelesss
 Done !
191
192 37 wirelesss
h3. Example of how to program a Magic SIM / SuperSIM 16-in-1 / X-sim card
193 5 wirelesss
194
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.
195
196 1 laforge
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.
197
198 5 wirelesss
 $ ./pySim-prog.py -p 0 -x 801 -y 71 -i 901990000000018 -s 8988211000000110000 -o 398153093661279FB1FC74BE07059FEF -k 1D8B2562B992549F20D0F42113EAA6FA
199
 Insert card now (or CTRL-C to cancel)
200
 Autodetected card type fakemagicsim
201
 Generated card parameters :
202
  > Name    : Magic
203
  > SMSP    : e1ffffffffffffffffffffffff0581005155f5ffffffffffff000000
204
  > ICCID   : 8988211000000110000
205
  > MCC/MNC : 801/71
206 1 laforge
  > IMSI    : 901990000000018
207 5 wirelesss
  > Ki      : 1D8B2562B992549F20D0F42113EAA6FA
208 1 laforge
  > OPC     : 398153093661279FB1FC74BE07059FEF
209 5 wirelesss
  > ACC     : None
210
 Programming ...
211
 Done !
212
213 37 wirelesss
h3. README 
214 6 wirelesss
215 37 wirelesss
pySim comes with following README file: 
216 5 wirelesss
217 42 gnutoo
https://git.osmocom.org/pysim/tree/README.md
218 43 laforge
219 44 roh
h3. Testing
220
221 45 laforge
pySim is continuously and automatically tested by a [[TestRig]] run by sysmocom
222 44 roh
223 45 laforge
{{include(cellular-infrastructure:MacroCommercialSupport)}}
Add picture from clipboard (Maximum size: 48.8 MB)