From da2811fc523e191f012bf7db90f3d041b8f3342e Mon Sep 17 00:00:00 2001 From: Michael Farrell Date: Thu, 26 Oct 2023 11:43:21 +1000 Subject: [PATCH] document solokey commands --- fido-key-manager/README.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/fido-key-manager/README.md b/fido-key-manager/README.md index 1bb4121c..4ec8fd41 100644 --- 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