FreeCalypso > hg > fc-sim-tools

comparison doc/Sysmocom-SIM-notes @ 18:da6e9d0b2ee6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
data, doc, scripts: import from previous fc-pcsc-tools repo
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 14 Mar 2021 07:57:09 +0000
parents
children b9fc7022f9ac
comparison
equal deleted inserted replaced
17:372ecc4aa2c4 18:da6e9d0b2ee6
1 The present suite of tools (fc-simtool and fc-uicc-tool) is NOT a good fit for
2 programming sysmoUSIM-SJS1 and sysmoISIM-SJA2 cards made by Sysmocom and sold
3 in their webshop, because of the following combination of factors:
4
5 1) These cards are primarily USIM/ISIM, with classic GSM 11.11 SIM support
6 regarded as "backward compatibility" - thus they have a lot of important
7 files under ADF.USIM and ADF.ISIM which are not accessible via the classic
8 GSM 11.11 SIM protocol.
9
10 2) Our main feature-rich tool is fc-simtool, but this tool speaks only the
11 classic GSM 11.11 SIM protocol, hence it cannot access any of the USIM/ISIM
12 files.
13
14 3) We have fc-uicc-tool which speaks the UICC protocol that is native to these
15 Sysmocom cards, but it is only a low-level debug tool, not a feature match
16 to fc-simtool.
17
18 The proper long-term solution for our 2G-centric GSM community is to get our own
19 SIMs made, either by paying big bucks to Sysmocom to produce a run of custom
20 cards (presumably based on their current SJA2 platform) with USIM and ISIM
21 removed, leaving only the file system tree under MF that can be fully
22 manipulated via the classic SIM protocol, or preferably by resurrecting the
23 older Grcard SIM-only platform if possible - it may take a long time to find out
24 if the latter option is possible or not. But in the meantime, if someone needs
25 to program a SIM right now, when Sysmocom webshop cards are the only available
26 option, we do have limited support for programming these SIMs:
27
28 * It is possible to authenticate with the ADM1 key from within fc-simtool on
29 both sysmoUSIM-SJS1 and sysmoISIM-SJA2, as explained below.
30
31 * Once you have authenticated with ADM1, you can use fc-simtool admin write
32 commands (write-imsi, SDN phonebook write operations, manual update-bin-imm
33 on various small transparent EFs) just as if you were working with a Grcard
34 SIM.
35
36 * You can also use fc-uicc-tool to access and program every file on Sysmocom
37 cards, including files under ADF.USIM and ADF.ISIM - but in this case you will
38 have to do everything manually in raw hex, with a hex data file for every
39 update-bin and update-rec command.
40
41 Authenticating with ADM1
42 ========================
43
44 The method for sending your ADM1 key to the card varies depending on whether
45 you are in an fc-simtool or fc-uicc-tool session, and whether your card is
46 sysmoUSIM-SJS1 or sysmoISIM-SJA2. There are 3 possibilities:
47
48 * If you are in an fc-uicc-tool session with either type of card, the command
49 to authenticate with ADM1 is as follows:
50
51 verify-pin 10 xxxxxxxx
52
53 where xxxxxxxx are the 8 digits of the ADM1 secret code. There are no
54 restrictions as to when this command may be given in an fc-uicc-tool session.
55
56 * If you are in an fc-simtool session with sysmoISIM-SJA2, the command becomes:
57
58 verify-ext 10 xxxxxxxx
59
60 There are no restrictions as to when this command may be given in an
61 fc-simtool session.
62
63 * If you are in an fc-simtool session with sysmoUSIM-SJS1, the command becomes:
64
65 verify-sjs1-adm1 xxxxxxxx
66
67 Unlike the other two cases, this command must be issued at the very beginning
68 of your fc-simtool session, before any other commands. If you issue this
69 command later, after some GSM 11.11 SIM APDUs have already been exchanged, it
70 won't work.
71
72 Changing the ADM1 PIN
73 =====================
74
75 Experiments show that when speaking the UICC protocol to the card, the standard
76 CHANGE PIN command does work on ADM1 on both sysmoUSIM-SJS1 and sysmoISIM-SJA2,
77 thus you can do the following in fc-uicc-tool:
78
79 change-pin 10 old-ADM1 new-ADM1
80
81 However, given that Sysmocom already assigns individual per-card random ADM1 and
82 communicates these secret codes securely to webshop customers, there does not
83 seem to be any practical need for changing ADM1 further downstream. Thus our
84 recommendation is that if you are going to change your ADM1 PIN just to prove
85 that you can do it, you should then change it back to the original.
86
87 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
89 remain forever proprietary to Sysmocom, especially given the lack of any
90 practical need for such downstream changing of PUK1/PUK2.
91
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
120 ===================================================
121
122 Referring to the previous section regarding formatting degrees of freedom,
123 Sysmocom webshop cards have their EF_MSISDN file allocated as 6 records of 34
124 bytes each. Record length of 34 bytes translates into 20 bytes of alpha tag
125 plus the required 14-byte structure at the end of each record.
126
127 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
129 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
131 phonebook record with a +882110xxxxx phone number would look like this, for the
132 record size of 34 bytes:
133
134 00: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
135 10: FF FF FF FF 07 91 88 12 01 xx xx Fx FF FF FF FF
136 20: FF FF
137
138 The first 20 bytes are all FF because that is the space reserved for the alpha
139 tag, then the phone number is encoded in 8 bytes as 07 91 88 12 01 xx xx Fx,
140 and the rest of the required 14-byte structure is filled with FF bytes.
141 However, the actual programming of this MSISDN record on early sysmoUSIM-SJS1
142 cards (at least on the 10-pack I bought in 2017) looks like this:
143
144 00: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
145 10: FF FF 07 91 88 12 01 xx xx Fx FF FF FF FF FF FF
146 20: FF FF
147
148 The not-all-FF field of 8 bytes is written into the wrong location, two bytes
149 earlier than where it should be. When I saw this misprogramming early in the
150 course of developing fc-simtool, I finally understood why the AT+CNUM command
151 on a FreeCalypso modem with this SIM inserted reported a 10xxxxx number instead
152 of the +882110xxxxx listed in the sysmoUSIM manual. :-)
153
154 When I saw this misprogramming, I also added a fix-sysmo-msisdn command to
155 fc-simtool: this command checks for this particular misprogramming, and if it
156 finds such, it rewrites the MSISDN record with the 8-byte phone number field
157 moved to its correct place. However, this fix-sysmo-msisdn command probably
158 won't get much use: the factory-programmed EF_MSISDN is now completely blank on
159 Sysmocom's current sysmoISIM-SJA2 cards, and also on the late sysmoUSIM-SJS1
160 cards - or at least it is blank on the last-stock cards I bought in 2020-11.
161 EF_MSISDN is writable without needing ADM1 - it only needs CHV1.