ADM access conditions
=====================

The response to SELECT of any EF in the classic GSM 11.11 SIM protocol carries
3 bytes that indicate access conditions for the selected file - or more
precisely, 5 nibbles that indicate access conditions plus one reserved nibble.
Each access condition nibble has the following encoding per standard specs
(GSM TS 11.11 and 3GPP TS 51.011):

Code	Meaning
---------------
0	ALW
1	CHV1
2	CHV2
3	RFU
4-14	ADM
15	NEV

Access condition codes 4 through 14 (0x4 through 0xE) are defined merely as ADM
by the standard specs, without further distinction.  However, those of us who
work with SIM cards on a tinkering or reverse engineering level and thus need
to fully decode SIM SELECT responses for intelligent analysis need to somehow
distinguish between these 11 possible ADM access levels, thus we had to make up
some scheme of our own for naming different ADMn access levels.

Unfortunately it just so happened that FC SIM tools and Grcard have come up with
two different ADMn naming conventions.  I (Mother Mychaela) feel that it is too
late now to change our FC SIM tools ADMn naming convention, and of course it is
not our place to tell Grcard company to change theirs.  Therefore, the only
remaining solution is to clearly document both naming conventions and just live
with there being two different ones.

In the FC SIM tools convention, the 11 possible ADM access levels for EFs are
named ADM4 through ADM14 - the 'n' in ADMn directly matches the nibble value
carried in the SIM protocol.  This convention is used by fc-simtool select and
readef commands when they display the access conditions returned by the SIM.

The convention used by Grcard names these 11 possible ADM access levels ADM1
through ADM11 instead.  As a result of this number shift, what Grcard call ADM1
is ADM4 to us, what Grcard call ADM2 is ADM5 to us, and so forth.

ADM key IDs in VERIFY CHV commands
==================================

Standard specs are silent on the question of exactly how administrative entities
authenticate themselves to the card to gain various ADM access levels, but most
card vendors implement an extended form of the standard VERIFY CHV command in
which the key ID in P2 is not 1 or 2 (standard CHV1 and CHV2), but some other
code identifying ADM keys and corresponding access levels.

There is no requirement that P2 key IDs in the extended VERIFY CHV command used
for ADM authentication have to correspond to the codes used to denote EF access
conditions.  However, on the traditional SIM (not UICC/USIM/ISIM) cards made by
Grcard, these two separate places in the binary protocol do use the same codes:
for example, if a given EF has an access condition indicated as code 5 in the
protocol (called ADM5 by us or ADM2 by Grcard), then the corresponding ADM
authentication has to be done with a VERIFY CHV command with P2=05.

ADM PIN numbers on Grcard SIM cards
===================================

We are aware of two different card models from Grcard that are specifically GSM
SIM, rather than UICC/USIM/ISIM.  (The latter kind also exist of course, but we
have no interest in them.)  The first such model is what we call GrcardSIM1
(previously sold by Sysmocom as sysmoSIM-GR1), and the other model is what we
call GrcardSIM2 - previously sold by Sysmocom as sysmoSIM-GR2, and now being
reintroduced as FreeCalypso Community SIM model FCSIM1.

GrcardSIM1 cards are currently understood very poorly because they are extremely
difficult to obtain in the present time (2021).  However, they seem to have two
different ADM access levels which Grcard officially call ADM1 and ADM2.  In our
FC SIM tools naming convention these ADM access levels become ADM4 and ADM5,
respectively.

GrcardSIM2 cards are understood much better because unlike GrcardSIM1, they are
readily available from Grcard in the present time.  They have two different ADM
access levels that are fully explained in the GrcardSIM2-security-model article,
and these two ADM levels are known by different names:

* Osmocom wiki page for GrcardSIM2 calls them ADM and SUPER ADM;

* For our FCSIM1 version of this card, we've named them ADM5 and ADM11, going
  by the numbers that appear in the actual binary protocol;

* Looking at Grcard's own documentation (see doc/vendor/grcard2-person-script),
  one can see that Grcard engineers refer to them as ADM2 and ADM8, following
  the numbering shift explained earlier in this article.