Project

General

Profile

Wiki » History » Version 48

laforge, 02/09/2022 08:05 PM
link to HTML manual on downloads

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