--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Sysmocom-SIM-notes	Sun Mar 14 07:57:09 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.