# HG changeset patch # User Mychaela Falconia # Date 1613794308 0 # Node ID 09a66626647d8e31ded85bf047ca7954555c8b9d # Parent c0cd0d4635bb18797c03de2fcebd1b7f2bb25d2d doc/Sysmocom-SIM-notes article written diff -r c0cd0d4635bb -r 09a66626647d doc/Sysmocom-SIM-notes --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Sysmocom-SIM-notes Sat Feb 20 04:11:48 2021 +0000 @@ -0,0 +1,161 @@ +The present suite of tools (fc-simtool and fc-uicc-tool) is NOT a good fit for +programming sysmoUSIM-SJS1 and sysmoISIM-SJA2 cards made by Sysmocom and sold +in their webshop, because of the following combination of factors: + +1) These cards are primarily USIM/ISIM, with classic GSM 11.11 SIM support + regarded as "backward compatibility" - thus they have a lot of important + files under ADF.USIM and ADF.ISIM which are not accessible via the classic + GSM 11.11 SIM protocol. + +2) Our main feature-rich tool is fc-simtool, but this tool speaks only the + classic GSM 11.11 SIM protocol, hence it cannot access any of the USIM/ISIM + files. + +3) We have fc-uicc-tool which speaks the UICC protocol that is native to these + Sysmocom cards, but it is only a low-level debug tool, not a feature match + to fc-simtool. + +The proper long-term solution for our 2G-centric GSM community is to get our own +SIMs made, either by paying big bucks to Sysmocom to produce a run of custom +cards (presumably based on their current SJA2 platform) with USIM and ISIM +removed, leaving only the file system tree under MF that can be fully +manipulated via the classic SIM protocol, or preferably by resurrecting the +older Grcard SIM-only platform if possible - it may take a long time to find out +if the latter option is possible or not. But in the meantime, if someone needs +to program a SIM right now, when Sysmocom webshop cards are the only available +option, we do have limited support for programming these SIMs: + +* It is possible to authenticate with the ADM1 key from within fc-simtool on + both sysmoUSIM-SJS1 and sysmoISIM-SJA2, as explained below. + +* Once you have authenticated with ADM1, you can use fc-simtool admin write + commands (write-imsi, SDN phonebook write operations, manual update-bin-imm + on various small transparent EFs) just as if you were working with a Grcard + SIM. + +* You can also use fc-uicc-tool to access and program every file on Sysmocom + cards, including files under ADF.USIM and ADF.ISIM - but in this case you will + have to do everything manually in raw hex, with a hex data file for every + update-bin and update-rec command. + +Authenticating with ADM1 +======================== + +The method for sending your ADM1 key to the card varies depending on whether +you are in an fc-simtool or fc-uicc-tool session, and whether your card is +sysmoUSIM-SJS1 or sysmoISIM-SJA2. There are 3 possibilities: + +* If you are in an fc-uicc-tool session with either type of card, the command + to authenticate with ADM1 is as follows: + + verify-pin 10 xxxxxxxx + + where xxxxxxxx are the 8 digits of the ADM1 secret code. There are no + restrictions as to when this command may be given in an fc-uicc-tool session. + +* If you are in an fc-simtool session with sysmoISIM-SJA2, the command becomes: + + verify-ext 10 xxxxxxxx + + There are no restrictions as to when this command may be given in an + fc-simtool session. + +* If you are in an fc-simtool session with sysmoUSIM-SJS1, the command becomes: + + verify-sjs1-adm1 xxxxxxxx + + Unlike the other two cases, this command must be issued at the very beginning + of your fc-simtool session, before any other commands. If you issue this + command later, after some GSM 11.11 SIM APDUs have already been exchanged, it + won't work. + +Changing the ADM1 PIN +===================== + +Experiments show that when speaking the UICC protocol to the card, the standard +CHANGE PIN command does work on ADM1 on both sysmoUSIM-SJS1 and sysmoISIM-SJA2, +thus you can do the following in fc-uicc-tool: + +change-pin 10 old-ADM1 new-ADM1 + +However, given that Sysmocom already assigns individual per-card random ADM1 and +communicates these secret codes securely to webshop customers, there does not +seem to be any practical need for changing ADM1 further downstream. Thus our +recommendation is that if you are going to change your ADM1 PIN just to prove +that you can do it, you should then change it back to the original. + +We can only surmise that there probably exist some secret commands that can +reset PUK1 and PUK2 after you've authenticated with ADM1, but they will probably +remain forever proprietary to Sysmocom, especially given the lack of any +practical need for such downstream changing of PUK1/PUK2. + +Thoughts on card (re)formatting +=============================== + +ETSI and 3GPP specs give many more degrees of freedom to SIM card issuers than +just the content of various EFs: the card issuer gets to decide which DFs and +EFs will be present vs. which ones won't be present at all, and for many EFs +the size (allocated space) is variable per the specs and up to the card issuer. +In the case of record-based EFs, both the record size and the number of records +are often left up to card issuers to tune as desired. + +In the Mother's opinion, a truly programmable SIM would be one where every +downstream owner of each card (not just the initial factory or the party putting +up big bucks for a large custom production run) can do a full reformat: erase +the file system and then create whatever tree of DFs and EFs she desires, with +full control over each file's allocated size, structure and access conditions. + +In the case of Sysmocom webshop SIMs, we (FreeCalypso) are not aware of any +publicly available documents describing how to perform such a reformat - it +appears that Sysmocom keeps this knowledge proprietary. In contrast, the older +Grcard-based SIMs had some publicly documented commands for erasing the card +and creating new directories and files: + +https://osmocom.org/projects/cellular-infrastructure/wiki/GrcardSIM + +It remains to be seen whether we (FreeCalypso) can get new SIMs from Grcard +which are also freely formattable. + +MSISDN misprogramming on early sysmoUSIM-SJS1 cards +=================================================== + +Referring to the previous section regarding formatting degrees of freedom, +Sysmocom webshop cards have their EF_MSISDN file allocated as 6 records of 34 +bytes each. Record length of 34 bytes translates into 20 bytes of alpha tag +plus the required 14-byte structure at the end of each record. + +When Sysmocom made their early sysmoUSIM-SJS1 cards, they intended to program +the first record of EF_MSISDN as +882110xxxxx, where xxxxx are equal to the last +5 digits of their 901-70 IMSI and also to the last 5 content digits (before the +Luhn check digit) of their 8988211 ICCID. A correctly structured EF_MSISDN +phonebook record with a +882110xxxxx phone number would look like this, for the +record size of 34 bytes: + +00: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF +10: FF FF FF FF 07 91 88 12 01 xx xx Fx FF FF FF FF +20: FF FF + +The first 20 bytes are all FF because that is the space reserved for the alpha +tag, then the phone number is encoded in 8 bytes as 07 91 88 12 01 xx xx Fx, +and the rest of the required 14-byte structure is filled with FF bytes. +However, the actual programming of this MSISDN record on early sysmoUSIM-SJS1 +cards (at least on the 10-pack I bought in 2017) looks like this: + +00: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF +10: FF FF 07 91 88 12 01 xx xx Fx FF FF FF FF FF FF +20: FF FF + +The not-all-FF field of 8 bytes is written into the wrong location, two bytes +earlier than where it should be. When I saw this misprogramming early in the +course of developing fc-simtool, I finally understood why the AT+CNUM command +on a FreeCalypso modem with this SIM inserted reported a 10xxxxx number instead +of the +882110xxxxx listed in the sysmoUSIM manual. :-) + +When I saw this misprogramming, I also added a fix-sysmo-msisdn command to +fc-simtool: this command checks for this particular misprogramming, and if it +finds such, it rewrites the MSISDN record with the 8-byte phone number field +moved to its correct place. However, this fix-sysmo-msisdn command probably +won't get much use: the factory-programmed EF_MSISDN is now completely blank on +Sysmocom's current sysmoISIM-SJA2 cards, and also on the late sysmoUSIM-SJS1 +cards - or at least it is blank on the last-stock cards I bought in 2020-11. +EF_MSISDN is writable without needing ADM1 - it only needs CHV1.