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 be 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-adm5 XXXXXXXX		# set new ADM5, decimal format
grcard2-set-adm5-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

ADM11 MF quirk
==============

The operation of authenticating with ADM11 (verify-ext 11 or verify-hex 11) is
only allowed when the currently selected directory is MF - either as the very
first command in an fc-simtool session, or after an explicit 'select MF'.  If
the current directory is DF_GSM or DF_TELECOM, the command to authenticate with
ADM11 (VERIFY CHV with P2=0x0B) fails with SW of 0x9802.

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:

select MF
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-adm5 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-adm5, 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.