document solokey commands

micolous · Oct 26, 2023 · da2811f · da2811f
1 parent 057d3c6
commit da2811f
Showing 1 changed file with 31 additions and 0 deletions.
diff --git a/fido-key-manager/README.md b/fido-key-manager/README.md
@@ -80,6 +80,33 @@ Command | Description | Requirements
 [Enterprise Attestation]: https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-errata-20220621.html#sctn-feature-descriptions-enterp-attstn
 [Minimum PIN Length]: https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-errata-20220621.html#sctn-feature-descriptions-minPinLength
 
+## Vendor-specific commands
+
+**Warning:** for safety, ensure that you **only** have security key(s) from that
+vendor connected to your computer when using **any** vendor-specific command,
+**even benign ones**.
+
+In the CTAP 2 protocol, vendor-specific command IDs can (and do!) have different
+meanings on different vendors – one vendor may use a certain ID as a safe
+operation (such as "get info"), but another vendor might use the same ID to
+start firmware updates, change the key's operating mode or perform some
+potentially-destructive operation.
+
+For operations that require multiple commands be sent to a security key, this
+tool will attempt to stop early if a key reports that it does not support one
+of the commands, or returns an unexpected value.
+
+### SoloKey 2 / Trussed
+
+SoloKey 2 / Trussed commands are currently **only** supported over USB HID. NFC
+support may be added in future, but we have encountered many problems
+communicating with SoloKey / Trussed devices *at all* over NFC.
+
+Command | Description
+------- | -----------
+`solo-key-info` | get all connected SoloKeys' unique ID, firmware version and secure boot status
+`solo-key-random` | get some random bytes from a SoloKey
+
 ## Platform-specific notes
 
 Bluetooth is currently disabled by default, as it's not particularly reliable on
@@ -145,6 +172,10 @@ anything but macOS, and can easily accidentally select nearby devices.
 * NFC should "just work", provided you've installed a PC/SC initiator
   (driver) for your transciever (if it is not supported by `libccid`).
 
+  macOS tends to "butt in" on exclusive connections by selecting the PIV applet,
+  which can cause issues for some keys' firmware, especially if they support
+  PIV.
+
 * USB should "just work".
 
 ### Windows