--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/ADM-PIN-numbering	Tue Mar 23 23:30:00 2021 +0000
@@ -0,0 +1,87 @@
+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.