Extend docs

Author: StarGate01

docs/3-dev-setup.md

@@ -1,6 +1,6 @@
 # JavaCard Development Setup
 
-If you want to compile applets from source, you need to install a few requirements. These instructions are for Linux, but it should work on Windows as well (using Docker, see below).
+If you want to compile applets from source, you need to install a few requirements. These instructions are for Linux, but it should work on Windows as well (using Docker or maybe WSL, see below).
 
 ## Local Development
 
@@ -74,7 +74,7 @@ opensc-tool -r 'Virtual PCD 00 00' -s '80 b8 00 00 KK  PP  QQ QQ QQ ... 00 [RR S
 
 Replace `KK` with the amount of bytes after `KK`. Replace `PP` with the amount of `QQ` bytes. Replace `QQ QQ QQ ...` with the AID of the applet. If you want to pass initialization parameters, replace `RR` with the amount of `SS` bytes, and `SS SS SS ...` with the initialization data. Do not actually write the `[ ]` brackets, these just mean that the initialization section is optional. Example: `80 b8 00 00 0A  07  a0 00 00 05 27 20 01  00  FF`.
 
-make sure the command was successful by watching for `Received (SW1=0x90, SW2=0x00)`.
+Make sure the command was successful by watching for `Received (SW1=0x90, SW2=0x00)`.
 
 ### Using the Emulated Applet
 

docs/applets/1-pgp.md

@@ -33,7 +33,7 @@ For more options, see the SmartPGP README file.
 
 ## Installing the Applet
 
-To install the applet to your card, you have to first construct a valid AID (refer to section 4.2.1 of the OpenPGP card specification, linked below). Every AID starts with `D2 76 00 01 24 01`, which is the unique identifier of the FSFE joined with the application identifier `01`. Next comes the OpenPGP version, which is `03 04` (3.4) for this applet. The next two bytes are a manufacturer id, which should be registered with the FSF Europe e.V. , however you can just put whatever you like - I use `C0 FE`. The next four bytes specify the card serial number (e.g. `00 00 00 01`), and the last two bytes are reserved for future use and alway zero.
+To install the applet to your card, you have to first construct a valid AID (refer to section 4.2.1 of the OpenPGP card specification, linked below). Every AID starts with `D2 76 00 01 24 01`, which is the unique identifier of the FSFE, joined with the application identifier `01`. Next comes the OpenPGP version, which is `03 04` (3.4) for this applet. The next two bytes are a manufacturer id, which should be registered with the FSF Europe e.V. , however you can just put whatever you like - I use `C0 FE`. The next four bytes specify the card serial number (e.g. `00 00 00 01`), and the last two bytes are reserved for future use and are always zero.
 
 The complete AID should look like this: `D2 76 00 01 24 01 03 04 C0 FE 00 00 00 01 00 00`.
 

docs/applets/3-hmac-sha1.md

@@ -2,7 +2,7 @@
 
 HMAC-SHA1 challenge-response provides a mechanism for two systems to ensure bilateral knowledge of a secret, without disclosing or transmitting the secret.
 
-This applets is compatible to the Yubikey-style protocol, used in e.g. KeepassXC.
+This applet is compatible to the Yubikey-style protocol, supported by e.g. KeePassXC.
 
 ## Applet Information
 
@@ -42,7 +42,7 @@ PKG: A00000052720 (LOADED)
 
 This applet behaves the same way as the challenge-response functionality on a Yubikey. However, it cannot be initialized using the Yubikey Personalization GUI tools, because these require a USB connection. Instead, various other tools can be used.
 
-First of all, make sure no YubiKey is connected to your PC, or it might be overwritten if you are not careful.
+First of all, make sure no YubiKeys are connected to your PC, or it might be overwritten if you are not careful.
 
 Second, make sure to keep a backup of your secret key somewhere.
 
@@ -80,7 +80,7 @@ If everything is encoded correctly, the commands should give the same response.
 
 ### Usage with KeePassXC
 
-Thanks to a patch by me (https://github.com/keepassxreboot/keepassxc/pull/6895, https://github.com/keepassxreboot/keepassxc/pull/6766) KeePassXC is able to interface with this applet and Yubikeys via NFC using any compatible reader. This work on Windows, Linux and Mac.
+Thanks to a PR by me (https://github.com/keepassxreboot/keepassxc/pull/6895, https://github.com/keepassxreboot/keepassxc/pull/6766) KeePassXC is able to interface with this applet and Yubikeys via NFC using any compatible reader. This work on Windows, Linux and Mac.
 
 To add a Yubikey as protection to your Database, refer to the KeePassXC documentation (or just look at the UI).
 

docs/applets/4-ndef.md

@@ -17,7 +17,6 @@ Use git to clone the sources, and change into the directory. To compile, run `an
 
 The build definition produces various versions of the applet, the most interesting ones are `full`, which is a read-write enabled version, and `tiny`, which is a read-only version with static data.
 
-
 ## Installing the Applet
 
 To install the applet to your card, you have to pass along some configuration data.
@@ -30,7 +29,7 @@ To install the `full` variant with 2KB re-writeable storage:
 gp -install openjavacard-ndef-full.cap -create D2760000850101 -params 8102000082020800
 ```
 
-The TLV configuration format is not trivial, for the specification see the openjavacard-ndef documentation at https://github.com/OpenJavaCard/openjavacard-ndef/blob/master/doc/install.md .
+The TLV configuration format has a few options, for the specification see the openjavacard-ndef documentation at https://github.com/OpenJavaCard/openjavacard-ndef/blob/master/doc/install.md .
 
 To install the `tiny` variant with the static URL "https://chrz.de":
 

docs/applets/5-fido.md

@@ -1,21 +1,25 @@
 # Universal Two-Factor Authentication using FIDO
 
-FIDO U2F is a standard for two-factor authentication. It is extended and superseded by FIDO2, but still widely used. 
+**FIDO** (Fast IDentity Online) **U2F** (Universal 2nd Factor) is a standard for two-factor authentication. It is extended and superseded by FIDO2, but still widely used. 
 
-FIDO2 CTAP2 is an extension and improvement over FIDO U2F, and remains backwards-compatible to U2F.
+The applet requires an attestation certificate. This certificate can be a default one, or generated by you, or an official one signed by a company like Vivokey or Yubico. You don't want to generate a unique certificate for each token, because that would make the tokens uniquely identifiable, leading to privacy concerns. 
 
-The FIDO2 applet is still in development, and not completely finished. You can test the beta code, but keep in mind that some features do not work yet, e.g. Windows Hello. In addition, only the FIDO U2F applet has been certified to be standards compliant as of now.
+The attestation certificate is used to sign certificates for transport when you register with a service. The token manufacturer (e.g. Vivokey) can also use this certificate (which they sign using their certificate authority) to validate the authenticity and model of the token and applet.
+
+**FIDO2 CTAP2** (Client to Authenticator Protocol) is an extension and improvement over FIDO U2F, and remains backwards-compatible to U2F.
+
+The FIDO2 applet is still in development, and not completely finished. For example, Windows Hello is not supported yet. The attestation certificate loading procedure is not yet properly documented, and neither is the generation of such a certificate. Stay tuned.
 
 ## Applet Information
 
-### FIDO U2F
+### FIDO U2F (recommended)
 
 - Repository: https://github.com/darconeous/u2f-javacard
 - Binary name: `U2FApplet.cap`
 - Download: https://github.com/StarGate01/flexsecure-applets/releases
 - AID: `A0:00:00:06:47:2F:00:01`, Package: `a0:00:00:06:17:00:4f:97:a2:e9:50:01`
 
-### FIDO2 CTAP2
+### FIDO2 CTAP2 (in development)
 
 - Repository: https://github.com/VivoKey/vk-u2f (forked from u2f-javacard)
 - Binary name: `CTAP2.cap`
@@ -32,15 +36,99 @@ Use git to clone the sources recursively, and change into the directory. To comp
 
 You can not use the U2F applet at the same time as the FIDO2 one because they use the same AID.
 
-Use GlobalPlatformPro (GPP) from https://github.com/martinpaljak/GlobalPlatformPro/releases to install the applet:
+Loading the attestation certificate requires manual steps as of now, but Vivokey and I are planning to release tools for U2F and FIDO2 attestation certificate loading sometime in the future.
+
+### Default Attestation Certificate
+
+You can use the default example U2F attestation certificate, which I have extracted from https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-raw-message-formats-v1.2-ps-20170411.html#examples and converted to the OpenSSL x509 / ECC PEM format. Note that it is no longer valid according to its date, but it still works. Then again, it was never signed by any company, so it was never seen as valid in the first place.
+
+`attestation.pem`:
+```
+-----BEGIN CERTIFICATE-----
+MIIBPDCB5KADAgECAgpHkBKAABFVlXNSMAoGCCqGSM49BAMCMBcxFTATBgNVBAMT
+DEdudWJieSBQaWxvdDAeFw0xMjA4MTQxODI5MzJaFw0xMzA4MTQxODI5MzJaMDEx
+LzAtBgNVBAMTJlBpbG90R251YmJ5LTAuNC4xLTQ3OTAxMjgwMDAxMTU1OTU3MzUy
+MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEjWF+ZclQjmS8xWc6yCpnmdo8FEZo
+LCWMRj//31jf0vo+bDeLU9eVxKTf+0GZ7deGLyOrrwIDtLiRG6BWmZThATAKBggq
+hkjOPQQDAgNHADBEAiBgzbYGHpwiJi0arB2W2McIKbI2ZTHdomiDLLg2vNMN+gIg
+YxsUWfCeYzAFVyLI2Jt/SIg7kIm4jWDR2XlZArMEEN8=
+-----END CERTIFICATE-----
+```
+
+`attestation_key.pem`:
+```
+-----BEGIN PRIVATE KEY-----
+MEECAQAwEwYHKoZIzj0CAQYIKoZIzj0DAQcEJzAlAgEBBCDz/MwNANgDGVT5CGTU
+PCR/S/XwZlxrUMwXdJon0c92ZA==
+-----END PRIVATE KEY-----
+```
+
+This is the one used in the installation instructions below.
+
+### Generate Attestation Certificate
+
+You can also generate your own attestation certificate. Install `openssl` and `xxd` (or any binary hex viewer).
+
+Create a file `attestation.config`, you can add more information if you want to:
+
+```
+[req]
+distinguished_name = req_dn
+attributes = req_att
+x509_extensions = req_ext
+req_extensions = req_ext
+prompt = no
+
+[req_dn]
+CN=FlexSecure U2F Token
+
+[req_att]
+
+[req_ext]
+basicConstraints = critical,CA:FALSE
+1.3.6.1.4.1.45724.2.1.1 = ASN1:FORMAT:BITLIST,BITSTRING:3
+```
+
+The x509 `1.3.6.1.4.1.45724.2.1.1` extension limits this token to the NFC transport type (`3`).
 
-Using the default example FIDO attestation certificate:
+Next, generate the private key (`attestation_key.pem`) and certificate signing request (`attestation.csr`):
+
+```
+openssl ecparam -genkey -noout -name prime256v1 -out attestation_key.pem
+
+openssl req -config attestation.config -new -sha256 -key attestation_key.pem -out attestation.csr
+```
+
+Then, self-sign it (e.g. for 10 years) to generate the final certificate (`attestation.pem`):
+
+```
+openssl req -x509 -config attestation.config -extensions req_ext -sha256 -key attestation_key.pem -in attestation.csr -out attestation.pem -days 3650
+```
+
+Creating and signing using a proper certificate authority is out of scope for this document.
+
+Next, extract the private key (32 bytes), look for `priv`:
+
+```
+openssl ec -in attestation_key.pem -text -noout
+```
+
+The bytes for the certificate are just the verbatim DER encoding:
+
+```
+openssl x509 -outform der -in attestation.pem -out attestation.der
+
+xxd -c 128 -p attestation.der
+wc -c < attestation.der
+```
+
+Use GlobalPlatformPro (GPP) from https://github.com/martinpaljak/GlobalPlatformPro/releases to install the applet:
 
 ```
 gp -install U2FApplet.cap --create A0000006472F0001 --params 000140f3fccc0d00d8031954f90864d43c247f4bf5f0665c6b50cc17749a27d1cf7664
 ```
 
-You have to pass a few parameters for the installer, e.g. the private key of the attestation certificate. See https://github.com/darconeous/u2f-javacard/blob/master/README.md and for more details.
+The parameter data is `00`, the length of the public attestation certificate (hex `0140`), and the private key (32 bytes). See https://github.com/darconeous/u2f-javacard/blob/master/README.md for more info.
 
 Listing the applets using `gp --list` should print something like this:
 
@@ -55,25 +143,21 @@ PKG: A000000617004F97A2E95001 (LOADED)
      Applet:  A000000617004F97A2E94901
 ```
 
-Next, you have to load the attestation certificate by sending a few APDUs:
+Next, you have to load the public attestation certificate by sending a few chained APDUs. The DER encoded public certificate has to be chopped into `128` byte chunks, which are sent attached to a small header. The header is `80 01 HHLL KK`, with `HHLL` being a 16 bit integer offset of that chunk, and `KK` being the chunk length (hex `80`, usually smaller for the last chunk). Before sending the certificate, a small preamble command is required.
 
 ```
-gp -d -v \
-  -a "00 A4 04 00 08 A0 00 00 06 47 2F 00 01" \
-  -a "80 01 00 00 80 30 82 01 3c 30 81 e4 a0 03 02 01 02 02 0a 47 90 12 80 00 11 55 95 73 52 30 0a 06 08 2a 86 48 ce 3d 04 03 02 30 17 31 15 30 13 06 03 55 04 03 13 0c 47 6e 75 62 62 79 20 50 69 6c 6f 74 30 1e 17 0d 31 32 30 38 31 34 31 38 32 39 33 32 5a 17 0d 31 33 30 38 31 34 31 38 32 39 33 32 5a 30 31 31 2f 30 2d 06 03 55 04 03 13 26 50 69 6c 6f 74 47 6e 75 62 62 79 2d 30 2e 34 2e 31 2d 34 37 39 30" \
-  -a "80 01 00 80 80 31 32 38 30 30 30 31 31 35 35 39 35 37 33 35 32 30 59 30 13 06 07 2a 86 48 ce 3d 02 01 06 08 2a 86 48 ce 3d 03 01 07 03 42 00 04 8d 61 7e 65 c9 50 8e 64 bc c5 67 3a c8 2a 67 99 da 3c 14 46 68 2c 25 8c 46 3f ff df 58 df d2 fa 3e 6c 37 8b 53 d7 95 c4 a4 df fb 41 99 ed d7 86 2f 23 ab af 02 03 b4 b8 91 1b a0 56 99 94 e1 01 30 0a 06 08 2a 86 48 ce 3d 04 03 02 03 47 00 30 44 02 20 60 cd" \
-  -a "80 01 01 00 40 b6 06 1e 9c 22 26 2d 1a ac 1d 96 d8 c7 08 29 b2 36 65 31 dd a2 68 83 2c b8 36 bc d3 0d fa 02 20 63 1b 14 59 f0 9e 63 30 05 57 22 c8 d8 9b 7f 48 88 3b 90 89 b8 8d 60 d1 d9 79 59 02 b3 04 10 df"
+gp -d -v -a "00 A4 04 00 08 A0 00 00 06 47 2F 00 01" -a "80 01 0000 80 3082013c3081e4a003020102020a47901280001155957352300a06082a8648ce3d0403023017311530130603550403130c476e756262792050696c6f74301e170d3132303831343138323933325a170d3133303831343138323933325a3031312f302d0603550403132650696c6f74476e756262792d302e342e312d34373930" -a "80 01 0080 80 313238303030313135353935373335323059301306072a8648ce3d020106082a8648ce3d030107034200048d617e65c9508e64bcc5673ac82a6799da3c1446682c258c463fffdf58dfd2fa3e6c378b53d795c4a4dffb4199edd7862f23abaf0203b4b8911ba0569994e101300a06082a8648ce3d0403020347003044022060cd" -a "80 01 0100 40 b6061e9c22262d1aac1d96d8c70829b2366531dda268832cb836bcd30dfa0220631b1459f09e6330055722c8d89b7f48883b9089b88d60d1d9795902b30410df"
 ```
 
-In the future, Vivokey or I will provide a nice tool to generate and load attestation certificates.
+See also https://gist.github.com/darconeous/adb1b2c4b15d3d8fbc72a5097270cdaf for more info on these APDUs.
 
 ## Using the Applet
 
-Using the applet requires a modern browser with support for FIDO. NFC tokens don't work on Linux (yet, see https://twitter.com/FIDOAlliance/status/1278331283874156544).
+Using the applet in the web requires a modern browser with support for FIDO. NFC tokens don't work on Linux (yet, see https://twitter.com/FIDOAlliance/status/1278331283874156544).
 
 You can use the *Yubikey WebAuthn test page* at https://demo.yubico.com/webauthn-technical/registration to test your token.
 
-On Android, you can use the *FIDO / Webauthn Example* App at https://play.google.com/store/apps/details?id=de.cotech.hw.fido.example for testing. 
+On Android, you can use the *FIDO / Webauthn Example* App at https://play.google.com/store/apps/details?id=de.cotech.hw.fido.example for testing (Use the U2F tab).
 
 ## Sources and Further Reading
 
@@ -88,5 +172,8 @@ On Android, you can use the *FIDO / Webauthn Example* App at https://play.google
 - https://research.kudelskisecurity.com/2020/02/12/fido2-deep-dive-attestations-trust-model-and-security/
 - https://fidoalliance.org/specs/fido-v2.0-rd-20180702/fido-client-to-authenticator-protocol-v2.0-rd-20180702.html
 - https://play.google.com/store/apps/details?id=de.cotech.hw.fido.example
+- https://research.kudelskisecurity.com/2020/02/12/fido2-deep-dive-attestations-trust-model-and-security/
+- https://developers.yubico.com/U2F/Attestation_and_Metadata/
+- https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-authenticator-transports-extension-v1.2-ps-20170411.html#fido-u2f-certificate-extensions
 
 Improve this document: https://github.com/StarGate01/flexsecure-applets/tree/master/docs

scripts/clean-all.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
 cd "${0%/*}"
 

scripts/compile-all.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
 cd "${0%/*}"
 

scripts/test-all.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
 cd "${0%/*}"
 

scripts/test/res/SmartPGP.generate.ECC.expect

@@ -1,4 +1,4 @@
-#!/usr/bin/expect -f
+#!/usr/bin/env expect -f
 
 set curve [lindex $argv 0];
 

scripts/test/res/SmartPGP.generate.RSA.expect

@@ -1,4 +1,4 @@
-#!/usr/bin/expect -f
+#!/usr/bin/env expect -f
 
 set size [lindex $argv 0];