FIDO2 security key management via commandline

FIDO2 Security keys are starting to take off. Many online services support them and the number is growing every day. At this point it seems FIDO Security keys are the way forward. FIDO2 being the second iteration of the FIDO suite. Managing the features of a FIDO2 security key is the first step in using and understanding a security key. As FIDO is an open standard, there are manufacturer independent ways to manage a FIDO security key.

While the FIDO security keys where pretty simple, FIDO2 adds a another level of features. As of this, there are some things that can be set up and managed. Before starting to manage the features, lets look at the details of security keys.

Wit FIDO being an open standard, there is nothing holding it back from wide adoption. As of this, most modern browsers have already pretty good support for FIDO and FIDO2 protocols. There is still a long way for full support in all the major browser but the state changes all the time.

Browser Management

At this time many browser support FIDO authentication to web services. Not many support managing the FIDO related features. One of the most known browser to manage FIDO security keys is the Chrome/Chromium web browser. This browser contains a settings page, sadly hidden deep inside the settings, to allow management of FIDO2 security keys. In the Chrome/Chromium browser settings, navigate to “Privacy and security” then “Security” then “Manage security keys”. In this settings sub-page, the browser allows to manage FIDO2 features.

Managing FIDO2 security keys can also be managed in a different way. In this article let’s focus on the alternative approach of managing the FIDO2 details of a security key in a browser independant way.

Command line management

As a alternative to the browser, there is a command line utility allowing to manage FIDO2 security keys. The command line tool is called fido2-token(1) and was created by Yubico. Still, the utility is working with security keys from other manufacturers as well, not only with those from Yubico.

To install the required package containing this utility, use the package manager of the Linux distributions of your choice. The package is called differently depending on the distribution used. On a mac, the fido2-token utility is also available using homebrew. The package might be called either “fido2-token or just “libfido2” depending on the distribution.

$ sudo apt-get install fido2-tools

The above example shows the installation on a Ubuntu based system. For further details on the package and it’s content, please refer to the website of the libfido2 project.

List security keys

When a security key is connected, a device file is created. The fido2-token(1) utility allows to list the security keys connected and the device file created for it. This device file is required for most of the other operations.

$ fido2-token -L
/dev/hidraw10: vendor=0x1050, product=0x0407 (Yubico YubiKey OTP+FIDO+CCID)
/dev/hidraw3: vendor=0x1915, product=0x520b (Crayonic KeyVault)
/dev/hidraw4: vendor=0x349e, product=0x0022 (TOKEN2 FIDO2 Security Key)
/dev/hidraw5: vendor=0x1209, product=0xbeee (SoloKeys Solo 2 Security Key)
/dev/hidraw7: vendor=0x096e, product=0x0853 (FS ePass FIDO)
/dev/hidraw8: vendor=0x20a0, product=0x42b2 (Nitrokey Nitrokey 3)

The option “-L” lists all authenticators (security keys in that context) connected to the system with the device file name. In the example above, a number of different hardware security keys are connected to the system.

On macOS, the output shows the device in a different way. Instead of the device file name like “/dev/hidraw5”, the device is identified with a I/O Registry URI starting with “ioreg://” followed by a number.

$ fido2-token -L
ioreg://4296168038: vendor=0x1915, product=0x520b (Crayonic KeyVault)

Even with the identifier looking different, fido2-token handles both the same way.

Security key information

With the identifier for the connected security key, the fido2-token(1) utility allows a number of operations. The following “-I” option allows to list a number of details about the security key. This and many other calls to fido2-token requires the identifier to address a specific security key.

$ fido2-token -I ioreg://4296168038
$ fido2-token -I /dev/hidraw3

The above shows both, the identifier format used in macOS “ioreg://4296168038” as well as the Linux identifier format “/dev/hidraw3”. No mather what OS you use, the returned information is the same as the output describes the hardware security key which is independent from the used OS.

$ fido2-token -I /dev/hidraw2
proto: 0x02
major: 0x02
minor: 0x01
build: 0x00
caps: 0x05 (wink, cbor, msg)
version strings: U2F_V2, FIDO_2_0, FIDO_2_1, FIDO_2_1_PRE
extension strings: credBlob, credProtect, hmac-secret, largeBlobKey, minPinLength
transport strings: usb
algorithms: es256 (public-key), eddsa (public-key)
aaguid: ab32f0c62239afbbc470d2ef4e254db7
options: rk, up, uv, noplat, noalwaysUv, credMgmt, authnrCfg, bioEnroll, clientPin, largeBlobs, pinUvAuthToken, setMinPINLength, makeCredUvNotRqd, credentialMgmtPreview, userVerificationMgmtPreview
maxmsgsiz: 2048
maxcredcntlst: 8
maxcredlen: 96
fwversion: 0x100
pin protocols: 2, 1
pin retries: 8
uv retries: 5
sensor type: 1 (touch)
max samples: 4

The above is an example output of a Token2 hardware security key.

Set the PIN

For some FIDO2 features, a PIN is required. To set that PIN in the Security key, the fido2-token(1) command line tool provides the “-S” option.

$ fido2-token -S /dev/hidraw3
Enter new PIN for /dev/hidraw3: 
Enter the same PIN again: 

When the command is executed, the user is asked for the PIN. After that, the PIN is set and can be used. To change the PIN after that, the “-C” can be used.

$ fido2-token -C /dev/hidraw4 
Enter current PIN for /dev/hidraw4: 
Enter new PIN for /dev/hidraw4: 
Enter the same PIN again: 

Reset the security key

In some cases it might be needed to rest the entire FIDO security key. This can be achieved as well using the fido2-token command. Resetting a FIDO2 security key is done with the “-R” option.

$ fido2-token -R /dev/hidraw4

When the resetting command is executed, the security keys button must be pressed/touched to perform the reset. There is one limitation to the reset implemented in FIDO2 security keys. Most security keys can only be reset for a short time after they have been connected to the system.

After a successful reset, the security key set back to the state it was delivered. A new master key is generated inside the security key and the old one is gone making any credentials created with it useless. Any resident keys generated will also be removed and the PIN reset/removed too.

Manufacturer support

At this point I want to say thank you for all the support from all the security key manufacturers from around the globe. Thank you for not only providing your devices for free testing but also your know how and patience with all our questions. And all without asking for any special treatment or talking points.

Without any particular order, here are the security key manufacturers that were supporting us. Make sure to check their websites if you are looking for a security key.


Read more of my posts on my blog at https://blog.tinned-software.net/.

This entry was posted in Security and tagged , , , , . Bookmark the permalink.