The current programmable SIM card model sold by Sysmocom in their webshop
(sysmoISIM-SJA2) is probably good for people who run their own cellular networks
of the LTE/5G kind, but it is NOT a good choice for those of us who are only
interested in GSM/2G, to the exclusion of all later G's:

* The triple-cut physical form factor is inferior (compared to solid-piece 2FF
  without 3FF or 4FF cuts) for use in classic GSM/2G phones with 2FF SIM
  sockets.

* The presence of unwanted USIM and ISIM applications with their associated
  ADF.USIM and ADF.ISIM file systems is very unpleasant: it forces us to either
  study up on completely unwanted-to-us USIM and ISIM specs and program all
  those files to something sensible (and just what would be sensible programming
  of USIM and ISIM files for a 2G-only network that exists solely to provide
  service to classic GSM/2G phones?), plus expend oodles of time and effort to
  develop the necessary programming tools that can write all those files under
  ADF.USIM and ADF.ISIM, or leave all those files unprogrammed, and take a
  gamble if someone sticks the partially-programmed card (classic SIM
  programmed, USIM and ISIM left unprogrammed) into a phone that knows about
  USIM and/or ISIM.

* Some of the advertising which Sysmocom prints on their current webshop cards,
  plus the very name sysmoISIM (emphasizing and glorifying ISIM rather than
  plain SIM) is offensive at least to me (Mother Mychaela), and should be
  offensive to any truly devoted lover of classic GSM/2G technology.

Because of the above considerations, we (FreeCalypso) are currently in the
process of getting our own community SIMs made, to serve as an alternative to
Sysmocom webshop product.  Our FreeCalypso community SIMs are currently as of
this writing (2021-03) being made for us by Grcard in China, they are a GSM-only
SIM card model (GrcardSIM2) without USIM/ISIM (they don't speak UICC protocol
at all, yay!), and we are having them made in a 2FF-only cut, meaning that the
2FF piece is fully solid.

However, despite our general dislike of Sysmocom's current USIM/ISIM-centric
product and our ongoing effort to produce a GSM/2G-centric alternative, we do
have some support in FC SIM tools for Sysmocom's current sysmoISIM-SJA2 card
and for their previous sysmoUSIM-SJS1 model.  This limited support exists
because these webshop cards are very readily and inexpensively available, and
because of natural human curiosity - we've been playing with these readily
available Sysmocom webshop cards while enduring the long delays involved in our
Grcard-based quest for a better alternative.

Sysmocom webshop card database
==============================

Whenever you buy a 10-pack of sysmoUSIM-SJS1 or sysmoISIM-SJA2 cards from
Sysmocom webshop, they send you an email with per-card identities and keys.
The information in that email is essential for doing any kind of admin writes
to the cards (the necessary ADM1 key is randomly assigned per card), and also
for any CHV2 operations: the randomly assigned PIN1 and PUK1 are printed on the
plastic, but not PIN2 or PUK2, which are also randomly assigned.

To reduce the need for manual lookups in email data, we have implemented a tool
that converts Sysmocom webshop emails into our own database format, and we have
integrated support for this database into fc-simtool and fc-uicc-tool.

Sysmocom webshop emails with USIM/ISIM card key material feature a MIME
multipart/alternative structure with text/plain and text/html parts, with each
part further encoded in base64.  To extract the bits of interest and convert
them into our sws-card-db format, follow these steps:

1) Extract the text/plain portion from the MIME structure and decode it from
   base64.

2) Open the extracted and decoded text/plain email portion in your favourite
   text editor and find the heading block of 19 lines, beginning with a line
   that reads "IMSI" and ending with a line that reads "KIK3".  (If you bought
   the cheaper option without ADM and OTA keys, there will only be 9 lines here,
   starting with IMSI and ending with OPC.)  Then there should be a blank line,
   followed by 19 lines of data per card (or 9 lines for sans-ADM/OTA variant),
   with blank lines separating each card data block from the next.  Extract the
   portion beginning with the heading block and ending with the last card data
   block in the batch.

3) Feed the data extract from the previous step to our sws-email2db utility.

sms-email2db sends its output to stdout, thus you should run it like this

sws-email2db email_extract.txt >> /opt/freecalypso/sim-data/sws-card-db

If you have bought multiple card batches from Sysmocom over the years, you will
need to collect those old emails and repeat the extraction procedure for each of
them, using the '>>' form of output redirection to gather all data in one
sws-card-db file.  Edit the finished database file with vi if necessary.

Using fc-simtool to program Sysmocom webshop cards
==================================================

Even though it is a UICC-native card that clearly prefers being admin-programmed
via the UICC protocol, sysmoISIM-SJA2 allows its ADM1 PIN to be entered in a
GSM 11.11 SIM protocol session with a VERIFY CHV command with P2=0x0A.
Therefore, the command to enter sysmoISIM-SJA2 ADM1 manually in fc-simtool is:

verify-ext 10 xxxxxxxx

Unlike the situation with sysmoUSIM-SJS1 (see below), there are no restrictions
as to when this command may be given in an fc-simtool session.

The above is the manual command, requiring the operator to manually look up the
correct ADM1 key for the card being programmed.  However, if you have your
sws-card-db file initialized with data from email per above instructions, you
can authenticate with ADM1 as simply as:

sws-auth-adm1

This command reads the ICCID record from the card (totally immutable on SJA2
cards, and always readable without depending on CHV1 status), looks up this
ICCID in sws-card-db, and sends a VERIFY CHV P2=0x0A command to the card with
ADM1 extracted from the card db record.

The following additional commands are available that work in a similar manner:

sws-auth-pin1		-- send VERIFY CHV1 with PIN1 from sws-card-db
sws-auth-pin2		-- send VERIFY CHV2 with PIN2 from sws-card-db
sws-pin1-disable	-- send DISABLE CHV with PIN1 from sws-card-db
sws-pin1-enable		-- send ENABLE CHV  with PIN1 from sws-card-db

There is also a generic sws-lookup command that looks up arbitrary sws-card-db
fields for the current card - examples:

sws-lookup puk1		-- look up and display PUK1 for this card
sws-lookup ki opc	-- look up and display Ki and OPc for this card

sysmoUSIM-SJS1 difference
=========================

Both sysmoUSIM-SJS1 and sysmoISIM-SJA2 are UICC-native cards, and both really
prefer to be admin-programmed via the UICC protocol, rather than GSM 11.11 SIM
protocol.  Both cards do allow ADM1 authentication to be performed in a GSM
11.11 SIM protocol session, but sysmoUSIM-SJS1 is less "happy" about it, and
imposes a more burdensome restriction.  sysmoISIM-SJA2 allows its ADM1 key to
be submitted via a VERIFY CHV (CLA=A0, P2=0A) APDU in a GSM 11.11 SIM session,
but sysmoUSIM-SJS1 does not allow the same.  sysmoUSIM-SJS1 accepts its ADM1 key
only via UICC-style (CLA=00) VERIFY PIN APDUs, thus at first it appears that
these cards cannot be admin-programmed via the classic GSM 11.11 SIM protocol.
They do have one open loophole, however: if the UICC-style VERIFY PIN command
for ADM1 is sent as the very first command in a card session, it can be followed
by other UICC protocol commands (making a regular UICC session), or it can be
followed by GSM 11.11 SIM protocol commands with CLA=A0, thus allowing one
special exception to the general rule which prohibits mixing these two protocols
in the same card session.

Our fc-simtool command for sending SJS1 ADM1 keys in the manner this card model
requires is as follows:

verify-sjs1-adm1 xxxxxxxx

The really big restriction is that 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.  For this reason, our sws-auth-adm1 "macro" command cannot be
used in fc-simtool with SJS1 cards: in order to use sws-card-db, one has to read
the ICCID record to identify the specific card out of the pool, and once some
APDUs have been exchanged to make that ICCID read, the special exception to the
protocol mixing prohibition is no longer available.  One could develop a more
complicated system where you read the ICCID, then reset the card and have a new
card session beginning with ADM1 authentication - but because this
sysmoUSIM-SJS1 card model is no longer sold by Sysmocom, there is no
justification for expending the effort.

Using fc-uicc-tool with Sysmocom webshop cards
==============================================

The UICC protocol is native to both sysmoUSIM-SJS1 and sysmoISIM-SJA2, thus
fc-uicc-tool works like a charm with both card models.  The problem, however,
is that fc-uicc-tool is only a low-level debug and manual tinkering tool: it
can do "everything", but only 100% manually in raw hex.  Most of the high-level
functions of fc-simtool are not replicated in fc-uicc-tool, and furthermore, an
approach of mindlessly translating fc-simtool high-level functions to use the
UICC protocol for card file access won't work either: the USIM spec definition
of many important files is quite different from the original DF_GSM and
DF_TELECOM definitions for classic SIM.

The issue is ultimately one of project purpose and direction: FreeCalypso
focuses on GSM/2G to the exclusion of later G's, our preferred SIM cards are
our own FCSIM1, our primary SIM card manipulation tool is fc-simtool, and
fc-uicc-tool exists only as a bounded-effort side utility.  For people who
prefer to work with USIM/ISIM cards natively, programming all of their new
files for later-G functionality, other software tool projects like pysim-shell
would be more appropriate.

ADM1 and other PIN authentication in fc-uicc-tool
=================================================

If you are in an fc-uicc-tool session with either sysmoUSIM-SJS1 or
sysmoISIM-SJA2, 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.

sws-auth-* and sws-lookup commands work in fc-uicc-tool exactly the same way as
in fc-simtool.

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.

MSISDN misprogramming on early sysmoUSIM-SJS1 cards
===================================================

Sysmocom webshop cards (both sysmoUSIM-SJS1 and sysmoISIM-SJA2) 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.