--- a/simtool/grcard1.c	Wed Mar 24 00:31:45 2021 +0000
+++ b/simtool/grcard1.c	Wed Mar 24 06:04:40 2021 +0000
@@ -2,13 +2,25 @@
  * This module implements a few special commands for those very few
  * incredibly lucky people on Earth who have no-longer-available
  * sysmoSIM-GR1 cards, or any other branded variant of the same card
- * from Grcard.
+ * from Grcard.  All knowledge of proprietary APDUs that appears in
+ * this code comes from this Osmocom wiki page:
+ *
+ * https://osmocom.org/projects/cellular-infrastructure/wiki/GrcardSIM
  */
 
 #include <sys/types.h>
 #include <stdio.h>
 #include "simresp.h"
 
+/*
+ * grcard1-set-pin1 command sets PIN1 and PUK1,
+ * grcard1-set-pin2 command sets PIN2 and PUK2.
+ *
+ * The proprietary APDU structure for these commands is naturally
+ * intuitive (agrees with common sense), hence they are expected
+ * to be correct despite lack of testing.
+ */
+
 cmd_grcard1_set_pin(argc, argv)
 	char **argv;
 {
@@ -47,6 +59,26 @@
 	return(0);
 }
 
+/*
+ * The ADM PIN structure of GrcardSIM1 cards is poorly understood.
+ * The Osmocom wiki page describes ADM1 and ADM2 per Grcard's ADMn
+ * naming convention (see ../doc/ADM-PIN-numbering), but each of those
+ * also has an associated unblock code (called AUK1 and AUK2 in the
+ * wiki page), and the command APDUs set ADM+AUK pairs: either
+ * ADM1+AUK1 or ADM2+AUK2.  The following blind (untested) code is
+ * based on this wiki page description.
+ *
+ * Because these access control codes are proprietary to Grcard
+ * (not standard PIN1/PIN2/PUK1/PUK2), they can be arbitrary 64-bit
+ * keys, not restricted to the ASCII-decimal subset used for standard
+ * PINs and PUKs.  According to pySim-prog, the canonical ADM2 key
+ * on these cards is hex 4444444444444444, which is outside of the
+ * ASCII-decimal range (contrast with the situation on GrcardSIM2,
+ * where the canonical SUPER ADM is decimal 88888888) - hence our
+ * grcard1-set-admN commands take hex strings for ADMn and AUKn,
+ * not decimal ones like grcard1-set-pinN.
+ */
+
 cmd_grcard1_set_adm(argc, argv)
 	char **argv;
 {
@@ -59,9 +91,11 @@
 	cmd[2] = 0x01;
 	switch (argv[0][15]) {
 	case '1':
+	case '4':
 		cmd[3] = 0x04;
 		break;
 	case '2':
+	case '5':
 		cmd[3] = 0x05;
 		break;
 	default:
@@ -71,10 +105,10 @@
 	cmd[4] = 18;
 	cmd[5] = 0x03;
 	cmd[6] = 0x00;
-	rc = encode_pin_entry(argv[1], cmd + 7);
+	rc = decode_hex_data_from_string(argv[1], cmd + 7, 8, 8);
 	if (rc < 0)
 		return(rc);
-	rc = encode_pin_entry(argv[2], cmd + 15);
+	rc = decode_hex_data_from_string(argv[2], cmd + 15, 8, 8);
 	if (rc < 0)
 		return(rc);
 	rc = apdu_exchange(cmd, 23);
@@ -87,6 +121,11 @@
 	return(0);
 }
 
+/*
+ * The command for setting Ki has been extensively exercised
+ * by Osmocom people, hence it is assumed to be correct.
+ */
+
 cmd_grcard1_set_ki(argc, argv)
 	char **argv;
 {