Polish up docs

Author: BryanJacobs

docs/FAQ.md

@@ -38,3 +38,20 @@ I wanted my password to be used in such a way that without it, the
 authenticator was useless - in other words, a true second factor.
 
 So I wrote a CTAP2 implementation that [had that property](security.md).
+
+## You say there are "caveats" for some implementation bits. What are those?
+
+Well, first off, this app doesn't attempt to do a full CBOR parse, so its error
+statuses often aren't perfect and it's generally tolerant of invalid input.
+
+Secondly, OpenSSH has a bug that rejects makeCredential responses
+that don't have credProtect level two when it requests level two. The
+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.
+
+## Why don't you implement U2F/CTAP1?
+
+U2F doesn't support PINs, and requires an attestation certificate.
+
+[the security model](security.md) requires PINs.

docs/requirements.md

@@ -14,7 +14,7 @@ hash yourself - good enough for me.
 So it's not possible to make this app work in a meaningful way on
 Javacard 3.0.1 or earlier.
 
-So let's discuss the full requirements:
+So let's discuss the full requirements on the authenticator side:
 
 - Javacard Classic 3.0.4
 - Approximately 2kB of total RAM, of which around 300 bytes will be reserved
@@ -27,3 +27,13 @@ So let's discuss the full requirements:
 
 An example of a card I've tested working is the NXP J3H145, but many
 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`.
+
+Without either of those two things 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`.

docs/security.md

@@ -142,3 +142,12 @@ a "timeout" on a Javacard 3.0.4 device. Javacard 3.1 introduces an
 But the implementation currently always assumes user presence.
 
 This Could Be Better.
+
+### I gave my smartcard to somebody but I didn't "lock" the card
+
+They could probably install an applet that would make the scenario
+identical to one where they possessed the card AND the hardware
+was faulty.
+
+So, lock your smartcard ("set a transit key"), `gpp --lock <key>` or 
+however you communicate with it.