More documentation

Author: BryanJacobs

docs/FAQ.md

@@ -15,13 +15,19 @@ If you don't know what that is, you DEFINITELY don't need this.
 ## Don't you need a CBOR parser to write a CTAP2 authenticator?
 
 Apparently not. Instead of implementing a real CBOR parser I just
-poured more sweat into the implemnentation, and added a topping of
+poured more sweat into the implementation, and added a topping of
 non-standards-compliance.
 
 As a result of not having a proper CBOR parser, the app will often
 return undesirable error codes on invalid input, but it should
 handle most valid input acceptably.
 
+It does this by linearly scanning a byte-buffer with the CBOR object in it,
+and moving a read index forward the desired amount. Unknown objects get skipped.
+Any object declaring a length greater than two bytes long causes an error,
+because it's not possible to have >65535 of something in a 1,024-byte-long
+buffer, and the CTAP2 standard requires that CBOR be "canonical".
+
 ## Why did you write this, when someone else said they were almost done writing a better version?
 
 Well, they said that, but they hadn't published the source code and I got impatient.
@@ -50,12 +56,31 @@ CTAP2.1 standard says it's okay to return level three if two was requested,
 but that breaks OpenSSH, so... credProtect is incorrectly implemented in
 that it always applies level three internally.
 
+Finally, the CTAP API requires user presence detection, but there's really no
+way to do that on Javacard 3.0.4. We can't even use the "presence timeout"
+that is described in the spec for NFC devices. So you're always treated as
+being present, which is to some extent offset by the fact that anything real
+requires you type your PIN (if one is set)...
+
+So set a PIN, and unplug your card when you're not using it.
+
 ## Why don't you implement U2F/CTAP1?
 
 U2F doesn't support PINs, and requires an attestation certificate.
 
-[the security model](security.md) requires PINs.
+[The security model](security.md) requires PINs.
+
+It would be possible to implement U2F commands in non-standards-compliant ways,
+but implementing them the normal way would require turning off the `alwaysUv`
+key feature for U2F-accessible credentials.
 
 ## Isn't PBKDF2 on a smartcard a fig leaf?
 
 Probably, yes, but it makes me feel better.
+
+You can raise the iteration count, but really there's only so much that can be
+done here. At least it means off-the-shelf rainbow tables probably won't work.
+
+## I hear bcrypt or Argon2id is better than PBKDF2
+
+Good luck implementing those on a 16-bit microprocessor. I welcome you to try.

docs/requirements.md

@@ -31,9 +31,12 @@ others should work fine too.
 # Platform-side requirements
 
 On the computer side of things, you'll likely want `libfido2` compiled
-with support for PC/SC, which is currently experimental, or `libnfc`.
+with support for PC/SC, which is currently experimental, or `libnfc`. On
+Arch this is not the default - out of the box `libfido2` only works with
+USB HID tokens, which this is **not**.
 
-Without either of those two things options you will Have A Bad Day.
+Without one of those two options you will Have A Bad Day.
 
 If you have them, you should see the card start showing up in the output
-of `fido2-token -L`.
+of `fido2-token -L`. You can see what gets sent to and from the card by
+setting `FIDO_DEBUG=1` before running your command.

docs/security.md

@@ -32,10 +32,14 @@ or used unless you provide your PIN...
 On boot, the device generates an AES256 key, the "wrapping key".
 
 Each individual credential issued by the app is a SecP256r1 keypoint,
-generated randomly on-device for that credential. The private key
+generated randomly on-device for that credential. The cred private key
 is then AES256-CBC encrypted along with the RP ID, using a random
 IV, and the result is used as the "credential ID".
 
+When using resident keys, the cred private key is only stored encrypted
+(after being initially generated). When not using resident keys, the
+cred private key isn't stored on the authenticator at all.
+
 This means relying parties are holding their own encrypted private
 keys. The keypair itself provides approximately 128 bits of
 brute-force resistance. The wrapping key provides a strong 256 bits.
@@ -151,3 +155,24 @@ was faulty.
 
 So, lock your smartcard ("set a transit key"), `gpp --lock <key>` or 
 however you communicate with it.
+
+### I deleted a resident key and then someone compromised my card
+
+Deleting a credential doesn't currently wipe it from the flash, just
+marks it as trashed. But a compromised card is a compromised card...
+
+### My smartcard's random number generator is not really random
+
+Keys generated by the card will be weak, so the "wrapping key" will be weak.
+
+This entirely breaks the security model of the card and you can't trust
+anything it does.
+
+### I don't trust your code
+
+You can see the code, and modify it until you do trust it. The only homespun
+crypto in the repository is an implementation of HMAC and an implementation
+of PBKDF2. Those were written because PBKDF2 isn't part of the Javacard API
+at all, and although HMA-SHA256 is it's not implemented on any of my cards.
+
+Open source is open.