Project

General

Profile

Wiki » History » Version 49

laforge, 07/18/2022 10:15 AM
elaborate on different programs; mention all supported cards / readers

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