Admin Applet
To manage your CanoKey, you can use the admin applet to
- Reset OpenPGP / PIV / OATH.
- Import FIDO private key and certification.
1. General Definitions
AID
The AID of the admin applet is F000000000.
Instructions
Instructions marked as Require PIN require a successful Verify PIN command to be performed before they are available.
| Name |
Code |
Require PIN |
| Write FIDO Key |
01h |
Y |
| Write FIDO Cert |
02h |
Y |
| Reset OpenPGP |
03h |
Y |
| Reset PIV |
04h |
Y |
| Reset OATH |
05h |
Y |
| Export OATH |
06h |
Y |
| Reset NDEF |
07h |
Y |
| Set NDEF Read-only |
08h |
Y |
| OpenPGP Touch Policy |
09h |
Y |
| Verify PIN |
20h |
N |
| Change PIN |
21h |
Y |
| Write SN |
30h |
Y |
| Get Version |
31h |
N |
| Get SN |
32h |
N |
| Config |
40h |
Y |
| Flash Usage |
41h |
Y |
| Read Config |
42h |
Y |
| Factory Reset |
50h |
N |
| Select |
A4h |
N |
| Vendor Specific |
FFh |
Y |
2. Select
Selects the application for use.
Request
| Field |
Value |
| CLA |
00h |
| INS |
A4h |
| P1 |
04h |
| P2 |
00h |
| Lc |
Length of AID (5) |
| Data |
AID (F0 00 00 00 00) |
Response
| SW |
Description |
| 9000 |
Success |
3. Verify PIN
Verify the PIN of this admin applet. The default PIN is 123456 (in string) or 31 32 33 34 35 36 (in hex).
PINs are independent between Admin / OpenPGP / PIV applets.
The max retries is 3. When you exceed this limit, the applet will be locked. Successful verification will reset this limit.
If the input is empty (Lc = 0), the actual access status of the PIN is returned. If the PIN is verified, the applet answers with normal status bytes (SW = 9000). If the PIN is not checked and the verification is required, the applet answers with the status bytes 63CX, where ‘X’ encodes the number of further allowed retries.
Request
| Field |
Value |
| CLA |
00h |
| INS |
20h |
| P1 |
00h |
| P2 |
00h |
| Lc |
Length of PIN or 0 |
| Data |
PIN |
Response
| SW |
Description |
| 9000 |
Success |
| 63CX |
Verification failed, X retries left |
| 6983 |
Applet is blocked |
4. Change PIN
After a successful verification, you can use this command to change your PIN directly. The length of the PIN should be between 6 and 64.
Request
| Field |
Value |
| CLA |
00h |
| INS |
21h |
| P1 |
00h |
| P2 |
00h |
| Lc |
Length of new PIN |
| Data |
New PIN |
Response
| SW |
Description |
| 9000 |
Success |
| 6700 |
Incorrect length |
5. Write FIDO Key
You can manually write it using this command. The private key should be a secp256r1 (NIST P-256) key.
When the private key is updated, the certification should be also updated accordingly.
Once you write a new private key, your old 2FA credentials (FIDO2) will be invalid.
Request
| Field |
Value |
| CLA |
00h |
| INS |
01h |
| P1 |
00h |
| P2 |
00h |
| Lc |
Length of the key (20h) |
| Data |
Private key |
Response
| SW |
Description |
| 9000 |
Success |
| 6700 |
Incorrect length |
6. Write FIDO Certification
The FIDO certification is an X.509 der format certificate corresponding to your private key. Use an extended command APDU to set it.
The maximum length of the certification is 1152 bytes.
Request
| Field |
Value |
| CLA |
00h |
| INS |
02h |
| P1 |
00h |
| P2 |
00h |
| Lc |
Length of the certification (2 bytes) |
| Data |
The certification |
Response
| SW |
Description |
| 9000 |
Success |
| 6700 |
Incorrect length |
7. Reset OpenPGP / PIV / OATH / NDEF
Executing these commands will reset the corresponding applets.
| Instruction Code |
Applet |
| 03h |
OpenPGP |
| 04h |
PIV |
| 05h |
OATH |
| 07h |
NDEF |
Request
| Field |
Value |
| CLA |
00h |
| INS |
03h / 04h / 05h / 07h |
| P1 |
00h |
| P2 |
00h |
Response
| SW |
Description |
| 9000 |
Success |
8. Export OATH
Export data in the OATH applet.
Request
| Field |
Value |
| CLA |
00h |
| INS |
06h |
| P1 |
00h |
| P2 |
00h |
Response
| SW |
Description |
| 9000 |
Success |
9. Change NDEF read-only
Set if NDEF is read-only.
Request
| Field |
Value |
| CLA |
00h |
| INS |
08h |
| P1 |
00h for read/write, 01h for read-only |
| P2 |
00h |
Response
| SW |
Description |
| 9000 |
Success |
10. OpenPGP Touch Policy
Set if OpenPGP operations require a touch.
Request
| Field |
Value |
| CLA |
00h |
| INS |
09h |
| P1 |
00h for SIG, 01h for DEC, 02h for AUT, 03h for cache time |
| P2 |
When P1 is 00/01/02, 00h for no touch, 01h for touch. When P1 is 03h, cache time (in seconds) |
Response
| SW |
Description |
| 9000 |
Success |
11. Write SN
The SN can be only set once. Due to the limitation of OpenPGP card spec, the serial number is 4-byte long.
If you build your own CanoKey, you should use this command to write the SN. Otherwise, the SN has been already set.
Request
| Field |
Value |
| CLA |
00h |
| INS |
30h |
| P1 |
00h |
| P2 |
00h |
| Lc |
Length of the SN (4) |
| Data |
SN |
Response
| SW |
Description |
| 9000 |
Success |
| 6700 |
Incorrect length |
| 6985 |
SN has been set |
12. Get version
Read the version of the firmware and the hardware.
Request
| Field |
Value |
| CLA |
00h |
| INS |
31h |
| P1 |
00h for firmware version, 01h for hardware version |
| P2 |
00h |
| LE |
00h |
Response
The version encoded in UTF-8.
| SW |
Description |
| 9000 |
Success |
13. Get serial number
Read the sn of the CanoKey and the chip.
Request
| Field |
Value |
| CLA |
00h |
| INS |
32h |
| P1 |
00h for CanoKey SN, 01h for chip ID |
| P2 |
00h |
| LE |
00h |
Response
The raw data.
| SW |
Description |
| 9000 |
Success |
14. Config
Configure the USB interfaces and the LED status:
- The LED can be configured ON or OFF when not blinking. The default value is ON.
- The keyboard interface can be enabled to input the HOTP by simply touching the key. The default value is OFF.
Request
| Field |
Value |
| CLA |
00h |
| INS |
40h |
| P1 |
01h: LED; 03h: Keyboard |
| P2 |
00h: Off, 01h: On |
Response
| SW |
Description |
| 9000 |
Success |
15. Get flash usage
Get the capacity of the flash.
Request
| Field |
Value |
| CLA |
00h |
| INS |
41h |
| P1 |
00h |
| P2 |
00h |
Response
Two bytes in total. The first byte indicates the free space in KiB. And the second indicates the total size of the flash in KiB.
| SW |
Description |
| 9000 |
Success |
16. Get current configurations
Get current configurations.
Request
| Field |
Value |
| CLA |
00h |
| INS |
42h |
| P1 |
00h |
| P2 |
00h |
Response
7 bytes in total.
| Byte |
Meaning |
| 1 |
LED |
| 2 |
Keyboard |
| 3 |
NDEF read-only |
| 4 |
OpenPGP SIG touch policy |
| 5 |
OpenPGP DEC touch policy |
| 6 |
OpenPGP AUT touch policy |
| 7 |
OpenPGP touch cache time |
| SW |
Description |
| 9000 |
Success |
17. Factory Reset
Reset the applets (FIDO key/cert and SN will not be reset).
PIN retries must be used up for reset to begin.
Once the command is executed, you must touch within 2 seconds when blinking until it responds with 9000.
Request
| Field |
Value |
| CLA |
00h |
| INS |
50h |
| P1 |
00h |
| P2 |
00h |
| Lc |
05h |
| Data |
RESET (in ASCII) |
Response
| SW |
Description |
| 9000 |
Success |
| 6982 |
Not touched when blinking |
| 6985 |
PIN not locked yet |
18. Vendor specific
This command is used for NFC configurations, which should not be used directly.