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.