--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/GrcardSIM2-security-model	Sat Mar 06 20:59:23 2021 +0000
@@ -0,0 +1,132 @@
+GrcardSIM2 cards (previously sold as sysmoSIM-GR2 and now being reintroduced as
+FCSIM1) have two different ADM access levels, each guarded by a separate secret
+code.  These two ADM access levels are referred to as ADM and SUPER ADM in the
+Osmocom wiki page for GrcardSIM2, but they can also be called ADM5 and ADM11,
+as the access level numbers appear in the actual APDUs.
+
+If you successfully authenticate with ADM5 secret code, you gain the following
+abilities:
+
+* You can change the ADM5 secret code itself;
+* You can reset PIN1, PIN2, PUK1 and PUK2 to new codes without having to know
+  any previous ones.
+
+If you successfully authenticate with ADM11 secret code, you gain the following
+abilities:
+
+* You can change the ADM11 secret code itself;
+* You can reset PIN1, PIN2, PUK1, PUK2 and ADM5 to new codes without having to
+  know any previous ones.
+
+Most admin-write-only files are writable after either ADM5 or ADM11
+authentication, but some files (particular EF.WEKI that holds Ki) can only be
+read and written with ADM11.  More precisely, if a given access condition
+(returned in response to SELECT) is listed as ADM11, then you need to
+authenticate with ADM11, but if it is listed as ADM5, then either ADM5 or ADM11
+is acceptable.  Because of this permissive design whereby ADM11 alone is
+sufficient, one can typically ignore ADM5 altogether for programming purposes.
+
+Both ADM5 and ADM11 can be set to any arbitrary string of 8 bytes, i.e., each
+is effectively a 64-bit key.  However, it is common for users to treat ADM5
+and/or ADM11 as being a string of 8 ASCII-encoded decimal digits like standard
+PUK1/PUK2 - the initial default ADM11 secret code from Grcard factory is set to
+64-bit hex string 3838383838383838, which corresponds to PIN/PUK-style decimal
+88888888.
+
+fc-simtool provides commands to set and verify ADM5 and ADM11 secret codes in
+either full hex or ASCII-encoded decimal representation; the former allows any
+arbitrary 64-bit key to the entered, whereas the latter is restricted to those
+64-bit keys which correspond to 8 ASCII-encoded decimal digits.  The commands
+are:
+
+verify-ext 5 XXXXXXXX		# authenticate as ADM5, decimal format
+verify-hex 5 xxxxxxxxxxxxxxxx	# authenticate as ADM5, arbitrary hex format
+
+verify-ext 11 XXXXXXXX		# authenticate as ADM11, decimal format
+verify-hex 11 xxxxxxxxxxxxxxxx	# authenticate as ADM11, arbitrary hex format
+
+grcard2-set-adm XXXXXXXX		# set new ADM5, decimal format
+grcard2-set-adm-hex xxxxxxxxxxxxxxxx	# set new ADM5, arbitrary hex format
+
+grcard2-set-super XXXXXXXX		# set new ADM11, decimal format
+grcard2-set-super-hex xxxxxxxxxxxxxxxx	# set new ADM11, arbitrary hex format
+
+Setting PIN1/PIN2/PUK1/PUK2
+===========================
+
+The following commands reset standard PIN and PUK secret codes after
+authenticating with either ADM5 or ADM11:
+
+grcard2-set-pin1 XXXX
+grcard2-set-pin2 XXXX
+grcard2-set-puk1 XXXXXXXX
+grcard2-set-puk2 XXXXXXXX
+
+These 4 commands take decimal string arguments and send them to the card in
+ASCII encoding per standard SIM spec definition of PIN1/PIN2/PUK1/PUK2.
+
+The underlying command APDUs sent by fc-simtool grcard2-set-* commands are
+proprietary to Grcard.  If you craft the right APDUs manually in hex (which our
+low-level apdu command allows), you can set PIN1/PIN2/PUK1/PUK2 to arbitrary
+64-bit hex strings which do not correspond to ASCII-encoded decimal - however,
+doing so would produce a SIM that violates the public interface definition for
+standard PIN1/PIN2/PUK1/PUK2, hence we do not provide such ability in our
+high-level grcard2-set-* command set.
+
+FCSIM1 default PINs
+===================
+
+The initial default ADM11 secret code from Grcard factory is decimal 88888888,
+meaning that you need to authenticate as follows:
+
+verify-ext 11 88888888
+
+If your card is unprogrammed (if you haven't programmed it yourself with
+fc-simtool), all other secret codes should be regarded as unknown - you need to
+reset them yourself in your own card programming or provisioning operation.
+Our fcsim1-default-pins command script sets the following FCSIM1 official
+defaults:
+
+grcard2-set-pin1 1234
+grcard2-set-pin2 6666
+grcard2-set-puk1 00099933
+grcard2-set-puk2 00099944
+grcard2-set-adm  55501234
+
+For as long as you keep the ADM11 secret code at its default of 88888888, there
+is no PIN security - even if you set PIN1/PIN2/PUK1/PUK2 to your own secrets,
+anyone can authenticate with the unchanged default ADM11 and then freely reset
+all lower PINs.  However, in the Mother's opinion there is very little need for
+PIN security in actual operational usage in this day and age - almost no one
+enables their PIN1, making it moot, and no one ever uses SIM "parental control"
+features controlled by PIN2.  In the present circumstances, the only real use
+for knowing SIM PINs is to exercise and test phone firmware code paths dealing
+with these PINs - and for this purpose having known fixed "secret" codes is
+very convenient.
+
+However, if someone does desire real PIN security, it *is* possible on FCSIM1
+cards - but then you have to not only set PIN1/PIN2/PUK1/PUK2 to your own
+secrets, but also set both ADM5 and ADM11 to your own truly-secret codes as
+well.  But be careful - if you set your own ADM11 secret code and then forget
+it, there is no recovery!  Maintaining a database of per-card secret codes is a
+development job which the Mother gladly leaves to other programmers, to be
+undertaken if and when someone actually needs such added complexity.
+
+How to (not) brick your card
+============================
+
+The following actions will brick your card beyond recovery:
+
+* If you enter ADM11 incorrectly 3 times in a row, ADM11 access is lost with no
+  possibility of recovery - this bricking mode is generally expected, there can
+  be no other way.
+
+* If you enter ADM5 incorrectly 3 times in a row, you unrecoverably lose the
+  ability to use ADM5 ever again - even if you successfully authenticate with
+  ADM11 and reset ADM5 with grcard2-set-adm, the attempt counter does not get
+  reset, and ADM5 remains blocked.
+
+* If you enter standard PUK1 or PUK2 incorrectly 10 times in a row, it is
+  similarly blocked beyond recovery, with no help from ADM5 or ADM11 -
+  grcard2-set-puk[12] commands reset the secret code, but not the associated
+  attempt counter.