FreeCalypso > hg > fc-sim-tools

comparison doc/Sysmocom-SIM-notes @ 56:b9fc7022f9ac

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Sysmocom-SIM-notes: update for current situation
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 22 Mar 2021 21:30:42 +0000
parents da6e9d0b2ee6
children 6ccc4d952830
comparison
equal deleted inserted replaced
55:a754d4f117cf 56:b9fc7022f9ac
1 The present suite of tools (fc-simtool and fc-uicc-tool) is NOT a good fit for 1 The current programmable SIM card model sold by Sysmocom in their webshop
2 programming sysmoUSIM-SJS1 and sysmoISIM-SJA2 cards made by Sysmocom and sold 2 (sysmoISIM-SJA2) is probably good for people who run their own cellular networks
3 in their webshop, because of the following combination of factors: 3 of the LTE/5G kind, but it is NOT a good choice for those of us who are only
4 4 interested in GSM/2G, to the exclusion of all later G's:
5 1) These cards are primarily USIM/ISIM, with classic GSM 11.11 SIM support 5
6 regarded as "backward compatibility" - thus they have a lot of important 6 * The triple-cut physical form factor is inferior (compared to solid-piece 2FF
7 files under ADF.USIM and ADF.ISIM which are not accessible via the classic 7 without 3FF or 4FF cuts) for use in classic GSM/2G phones with 2FF SIM
8 GSM 11.11 SIM protocol. 8 sockets.
9 9
10 2) Our main feature-rich tool is fc-simtool, but this tool speaks only the 10 * The presence of unwanted USIM and ISIM applications with their associated
11 classic GSM 11.11 SIM protocol, hence it cannot access any of the USIM/ISIM 11 ADF.USIM and ADF.ISIM file systems is very unpleasant: it forces us to either
12 files. 12 study up on completely unwanted-to-us USIM and ISIM specs and program all
13 13 those files to something sensible (and just what would be sensible programming
14 3) We have fc-uicc-tool which speaks the UICC protocol that is native to these 14 of USIM and ISIM files for a 2G-only network that exists solely to provide
15 Sysmocom cards, but it is only a low-level debug tool, not a feature match 15 service to classic GSM/2G phones?), plus expend oodles of time and effort to
16 to fc-simtool. 16 develop the necessary programming tools that can write all those files under
17 17 ADF.USIM and ADF.ISIM, or leave all those files unprogrammed, and take a
18 The proper long-term solution for our 2G-centric GSM community is to get our own 18 gamble if someone sticks the partially-programmed card (classic SIM
19 SIMs made, either by paying big bucks to Sysmocom to produce a run of custom 19 programmed, USIM and ISIM left unprogrammed) into a phone that knows about
20 cards (presumably based on their current SJA2 platform) with USIM and ISIM 20 USIM and/or ISIM.
21 removed, leaving only the file system tree under MF that can be fully 21
22 manipulated via the classic SIM protocol, or preferably by resurrecting the 22 * Some of the advertising which Sysmocom prints on their current webshop cards,
23 older Grcard SIM-only platform if possible - it may take a long time to find out 23 plus the very name sysmoISIM (emphasizing and glorifying ISIM rather than
24 if the latter option is possible or not. But in the meantime, if someone needs 24 plain SIM) is offensive at least to me (Mother Mychaela), and should be
25 to program a SIM right now, when Sysmocom webshop cards are the only available 25 offensive to any truly devoted lover of classic GSM/2G technology.
26 option, we do have limited support for programming these SIMs: 26
27 27 Because of the above considerations, we (FreeCalypso) are currently in the
28 * It is possible to authenticate with the ADM1 key from within fc-simtool on 28 process of getting our own community SIMs made, to serve as an alternative to
29 both sysmoUSIM-SJS1 and sysmoISIM-SJA2, as explained below. 29 Sysmocom webshop product. Our FreeCalypso community SIMs are currently as of
30 30 this writing (2021-03) being made for us by Grcard in China, they are a GSM-only
31 * Once you have authenticated with ADM1, you can use fc-simtool admin write 31 SIM card model (GrcardSIM2) without USIM/ISIM (they don't speak UICC protocol
32 commands (write-imsi, SDN phonebook write operations, manual update-bin-imm 32 at all, yay!), and we are having them made in a 2FF-only cut, meaning that the
33 on various small transparent EFs) just as if you were working with a Grcard 33 2FF piece is fully solid.
34 SIM. 34
35 35 However, despite our general dislike of Sysmocom's current USIM/ISIM-centric
36 * You can also use fc-uicc-tool to access and program every file on Sysmocom 36 product and our ongoing effort to produce a GSM/2G-centric alternative, we do
37 cards, including files under ADF.USIM and ADF.ISIM - but in this case you will 37 have some support in FC SIM tools for Sysmocom's current sysmoISIM-SJA2 card
38 have to do everything manually in raw hex, with a hex data file for every 38 and for their previous sysmoUSIM-SJS1 model. This limited support exists
39 update-bin and update-rec command. 39 because these webshop cards are very readily and inexpensively available, and
40 40 because of natural human curiosity - we've been playing with these readily
41 Authenticating with ADM1 41 available Sysmocom webshop cards while enduring the long delays involved in our
42 ======================== 42 Grcard-based quest for a better alternative.
43 43
44 The method for sending your ADM1 key to the card varies depending on whether 44 Sysmocom webshop card database
45 you are in an fc-simtool or fc-uicc-tool session, and whether your card is 45 ==============================
46 sysmoUSIM-SJS1 or sysmoISIM-SJA2. There are 3 possibilities: 46
47 47 Whenever you buy a 10-pack of sysmoUSIM-SJS1 or sysmoISIM-SJA2 cards from
48 * If you are in an fc-uicc-tool session with either type of card, the command 48 Sysmocom webshop, they send you an email with per-card identities and keys.
49 to authenticate with ADM1 is as follows: 49 The information in that email is essential for doing any kind of admin writes
50 50 to the cards (the necessary ADM1 key is randomly assigned per card), and also
51 verify-pin 10 xxxxxxxx 51 for any CHV2 operations: the randomly assigned PIN1 and PUK1 are printed on the
52 52 plastic, but not PIN2 or PUK2, which are also randomly assigned.
53 where xxxxxxxx are the 8 digits of the ADM1 secret code. There are no 53
54 restrictions as to when this command may be given in an fc-uicc-tool session. 54 To reduce the need for manual lookups in email data, we have implemented a tool
55 55 that converts Sysmocom webshop emails into our own database format, and we have
56 * If you are in an fc-simtool session with sysmoISIM-SJA2, the command becomes: 56 integrated support for this database into fc-simtool. (Replicating the same
57 57 functionality in fc-uicc-tool, as would be appropriate for these UICC-native
58 verify-ext 10 xxxxxxxx 58 cards, is on the to-do list.)
59 59
60 There are no restrictions as to when this command may be given in an 60 Sysmocom webshop emails with USIM/ISIM card key material feature a MIME
61 fc-simtool session. 61 multipart/alternative structure with text/plain and text/html parts, with each
62 62 part further encoded in base64. To extract the bits of interest and convert
63 * If you are in an fc-simtool session with sysmoUSIM-SJS1, the command becomes: 63 them into our sws-card-db format, follow these steps:
64 64
65 verify-sjs1-adm1 xxxxxxxx 65 1) Extract the text/plain portion from the MIME structure and decode it from
66 66 base64.
67 Unlike the other two cases, this command must be issued at the very beginning 67
68 of your fc-simtool session, before any other commands. If you issue this 68 2) Open the extracted and decoded text/plain email portion in your favourite
69 command later, after some GSM 11.11 SIM APDUs have already been exchanged, it 69 text editor and find the heading block of 19 lines, beginning with a line
70 won't work. 70 that reads "IMSI" and ending with a line that reads "KIK3". (If you bought
71 the cheaper option without ADM and OTA keys, there will only be 9 lines here,
72 starting with IMSI and ending with OPC.) Then there should be a blank line,
73 followed by 19 lines of data per card (or 9 lines for sans-ADM/OTA variant),
74 with blank lines separating each card data block from the next. Extract the
75 portion beginning with the heading block and ending with the last card data
76 block in the batch.
77
78 3) Feed the data extract from the previous step to our sws-email2db utility.
79
80 sms-email2db sends its output to stdout, thus you should run it like this
81
82 sws-email2db email_extract.txt >> /opt/freecalypso/sim-data/sws-card-db
83
84 If you have bought multiple card batches from Sysmocom over the years, you will
85 need to collect those old emails and repeat the extraction procedure for each of
86 them, using the '>>' form of output redirection to gather all data in one
87 sws-card-db file. Edit the finished database file with vi if necessary.
88
89 Using fc-simtool to program Sysmocom webshop cards
90 ==================================================
91
92 Even though it is a UICC-native card that clearly prefers being admin-programmed
93 via the UICC protocol, sysmoISIM-SJA2 allows its ADM1 PIN to be entered in a
94 GSM 11.11 SIM protocol session with a VERIFY CHV command with P2=0x0A.
95 Therefore, the command to enter sysmoISIM-SJA2 ADM1 manually in fc-simtool is:
96
97 verify-ext 10 xxxxxxxx
98
99 Unlike the situation with sysmoUSIM-SJS1 (see below), there are no restrictions
100 as to when this command may be given in an fc-simtool session.
101
102 The above is the manual command, requiring the operator to manually look up the
103 correct ADM1 key for the card being programmed. However, if you have your
104 sws-card-db file initialized with data from email per above instructions, you
105 can authenticate with ADM1 as simply as:
106
107 sws-auth-adm1
108
109 This command reads the ICCID record from the card (totally immutable on SJA2
110 cards, and always readable without depending on CHV1 status), looks up this
111 ICCID in sws-card-db, and sends a VERIFY CHV P2=0x0A command to the card with
112 ADM1 extracted from the card db record.
113
114 The following additional commands are available that work in a similar manner:
115
116 sws-auth-pin1 -- send VERIFY CHV1 with PIN1 from sws-card-db
117 sws-auth-pin2 -- send VERIFY CHV2 with PIN2 from sws-card-db
118 sws-pin1-disable -- send DISABLE CHV with PIN1 from sws-card-db
119 sws-pin1-enable -- send ENABLE CHV with PIN1 from sws-card-db
120
121 sysmoUSIM-SJS1 difference
122 =========================
123
124 Both sysmoUSIM-SJS1 and sysmoISIM-SJA2 are UICC-native cards, and both really
125 prefer to be admin-programmed via the UICC protocol, rather than GSM 11.11 SIM
126 protocol. Both cards do allow ADM1 authentication to be performed in a GSM
127 11.11 SIM protocol session, but sysmoUSIM-SJS1 is less "happy" about it, and
128 imposes a more burdensome restriction. sysmoISIM-SJA2 allows its ADM1 key to
129 be submitted via a VERIFY CHV (CLA=A0, P2=0A) APDU in a GSM 11.11 SIM session,
130 but sysmoUSIM-SJS1 does not allow the same. sysmoUSIM-SJS1 accepts its ADM1 key
131 only via UICC-style (CLA=00) VERIFY PIN APDUs, thus at first it appears that
132 these cards cannot be admin-programmed via the classic GSM 11.11 SIM protocol.
133 They do have one open loophole, however: if the UICC-style VERIFY PIN command
134 for ADM1 is sent as the very first command in a card session, it can be followed
135 by other UICC protocol commands (making a regular UICC session), or it can be
136 followed by GSM 11.11 SIM protocol commands with CLA=A0, thus allowing one
137 special exception to the general rule which prohibits mixing these two protocols
138 in the same card session.
139
140 Our fc-simtool command for sending SJS1 ADM1 keys in the manner this card model
141 requires is as follows:
142
143 verify-sjs1-adm1 xxxxxxxx
144
145 The really big restriction is that this command must be issued at the very
146 beginning of your fc-simtool session, before any other commands. If you issue
147 this command later, after some GSM 11.11 SIM APDUs have already been exchanged,
148 it won't work. For this reason, our sws-auth-adm1 "macro" command cannot be
149 used in fc-simtool with SJS1 cards: in order to use sws-card-db, one has to read
150 the ICCID record to identify the specific card out of the pool, and once some
151 APDUs have been exchanged to make that ICCID read, the special exception to the
152 protocol mixing prohibition is no longer available. One could develop a more
153 complicated system where you read the ICCID, then reset the card and have a new
154 card session beginning with ADM1 authentication - but because this
155 sysmoUSIM-SJS1 card model is no longer sold by Sysmocom, there is no
156 justification for expending the effort.
157
158 Using fc-uicc-tool with Sysmocom webshop cards
159 ==============================================
160
161 The UICC protocol is native to both sysmoUSIM-SJS1 and sysmoISIM-SJA2, thus
162 fc-uicc-tool works like a charm with both card models. The problem, however,
163 is that fc-uicc-tool is only a low-level debug and manual tinkering tool: it
164 can do "everything", but only 100% manually in raw hex. Most of the high-level
165 functions of fc-simtool are not replicated in fc-uicc-tool, and furthermore, an
166 approach of mindlessly translating fc-simtool high-level functions to use the
167 UICC protocol for card file access won't work either: the USIM spec definition
168 of many important files is quite different from the original DF_GSM and
169 DF_TELECOM definitions for classic SIM.
170
171 The issue is ultimately one of project purpose and direction: FreeCalypso
172 focuses on GSM/2G to the exclusion of later G's, our preferred SIM cards are
173 our own FCSIM1, our primary SIM card manipulation tool is fc-simtool, and
174 fc-uicc-tool exists only as a bounded-effort side utility. For people who
175 prefer to work with USIM/ISIM cards natively, programming all of their new
176 files for later-G functionality, other software tool projects like pysim-shell
177 would be more appropriate.
178
179 ADM1 and other PIN authentication in fc-uicc-tool
180 =================================================
181
182 If you are in an fc-uicc-tool session with either sysmoUSIM-SJS1 or
183 sysmoISIM-SJA2, the command to authenticate with ADM1 is as follows:
184
185 verify-pin 10 xxxxxxxx
186
187 where xxxxxxxx are the 8 digits of the ADM1 secret code. There are no
188 restrictions as to when this command may be given in an fc-uicc-tool session.
189
190 sws-auth-* commands have not been ported over fc-uicc-tool yet, but this
191 omission will be easy to fill.
71 192
72 Changing the ADM1 PIN 193 Changing the ADM1 PIN
73 ===================== 194 =====================
74 195
75 Experiments show that when speaking the UICC protocol to the card, the standard 196 Experiments show that when speaking the UICC protocol to the card, the standard
87 We can only surmise that there probably exist some secret commands that can 208 We can only surmise that there probably exist some secret commands that can
88 reset PUK1 and PUK2 after you've authenticated with ADM1, but they will probably 209 reset PUK1 and PUK2 after you've authenticated with ADM1, but they will probably
89 remain forever proprietary to Sysmocom, especially given the lack of any 210 remain forever proprietary to Sysmocom, especially given the lack of any
90 practical need for such downstream changing of PUK1/PUK2. 211 practical need for such downstream changing of PUK1/PUK2.
91 212
92 Thoughts on card (re)formatting
93 ===============================
94
95 ETSI and 3GPP specs give many more degrees of freedom to SIM card issuers than
96 just the content of various EFs: the card issuer gets to decide which DFs and
97 EFs will be present vs. which ones won't be present at all, and for many EFs
98 the size (allocated space) is variable per the specs and up to the card issuer.
99 In the case of record-based EFs, both the record size and the number of records
100 are often left up to card issuers to tune as desired.
101
102 In the Mother's opinion, a truly programmable SIM would be one where every
103 downstream owner of each card (not just the initial factory or the party putting
104 up big bucks for a large custom production run) can do a full reformat: erase
105 the file system and then create whatever tree of DFs and EFs she desires, with
106 full control over each file's allocated size, structure and access conditions.
107
108 In the case of Sysmocom webshop SIMs, we (FreeCalypso) are not aware of any
109 publicly available documents describing how to perform such a reformat - it
110 appears that Sysmocom keeps this knowledge proprietary. In contrast, the older
111 Grcard-based SIMs had some publicly documented commands for erasing the card
112 and creating new directories and files:
113
114 https://osmocom.org/projects/cellular-infrastructure/wiki/GrcardSIM
115
116 It remains to be seen whether we (FreeCalypso) can get new SIMs from Grcard
117 which are also freely formattable.
118
119 MSISDN misprogramming on early sysmoUSIM-SJS1 cards 213 MSISDN misprogramming on early sysmoUSIM-SJS1 cards
120 =================================================== 214 ===================================================
121 215
122 Referring to the previous section regarding formatting degrees of freedom, 216 Sysmocom webshop cards (both sysmoUSIM-SJS1 and sysmoISIM-SJA2) have their
123 Sysmocom webshop cards have their EF_MSISDN file allocated as 6 records of 34 217 EF_MSISDN file allocated as 6 records of 34 bytes each. Record length of 34
124 bytes each. Record length of 34 bytes translates into 20 bytes of alpha tag 218 bytes translates into 20 bytes of alpha tag plus the required 14-byte structure
125 plus the required 14-byte structure at the end of each record. 219 at the end of each record.
126 220
127 When Sysmocom made their early sysmoUSIM-SJS1 cards, they intended to program 221 When Sysmocom made their early sysmoUSIM-SJS1 cards, they intended to program
128 the first record of EF_MSISDN as +882110xxxxx, where xxxxx are equal to the last 222 the first record of EF_MSISDN as +882110xxxxx, where xxxxx are equal to the last
129 5 digits of their 901-70 IMSI and also to the last 5 content digits (before the 223 5 digits of their 901-70 IMSI and also to the last 5 content digits (before the
130 Luhn check digit) of their 8988211 ICCID. A correctly structured EF_MSISDN 224 Luhn check digit) of their 8988211 ICCID. A correctly structured EF_MSISDN