FidoVault is a tool to control access to secrets via symmetric encryption and decryption using hardware FIDO2 keys. A FidoVault vault file contains a secret encrypted via one or more FIDO2 keys, such that the secret is inaccessible without at least one of the keys, but any single key can decrypt the secret. A password can optionally be required for decryption in addition to a key.
Caution
Most FIDO2 keys cannot be "backed up" or duplicated. If all the keys of a particular FidoVault are lost (or (presumably - I have not tested this) "reset"u), then that FidoVault will become irreversibly inaccessible.
Additionally, FIDO2 keys apparently have two separate secret keys, one used when "user verification" (userVerification or uv) is performed, and the other when it is not. Consequently, secrets encrypted by a key when user verification is not performed may not be accessible by the same key when user verification is performed (and vice versa). For more detailed discussion of this issue and its implications, see here.
Any hardware FIDO2 key that supports the HMAC Secret Extension (which reportedly most do) should work with FidoVault. Development and testing have primarily been done using a Yubico Security Key.
FidoVault is written in Python 3, and has the following dependencies:
- Cryptography (for symmetric encryption and decryption of secrets)
- python-fido2 version 1.2.0 (for accessing FIDO2 keys)
Note
Be sure to use version 1.2.0 of python-fido2; FidoVault will not work correctly with earlier versions.
Initialize a FidoVault:
$ fidovault.py -i -v <vaultname>
Enter secret:
Confirm secret:
Prompt for passwords to combine with FIDO2 hmac-secrets? (y/n - default is y) y
Please connect the FIDO2 key you wish to add (and disconnect any others).
Press <enter> when ready ...
Checking key at /dev/hidraw1 ...
Key supports the hmac-secret extension.
Making FIDO2 credential ...
Touch your authenticator device now ...
Success.
Getting hmac-secret ...
Touch your authenticator device now ...
Success.
Enter password (leave blank for none):
Confirm password:
Enter name for this key: Blue Key
FIDO2 key successfully added.
FidoVault '<vaultname>' updated.
Add an additional key to an existing FidoVault (connect an already configured FIDO2 key before proceeding):
$ fidovault.py -a -v <vaultname>
Checking key at /dev/hidraw1 ...
Key supports the hmac-secret extension.
Touch your authenticator device now ...
Enter password (leave blank for none):
Attempting to decrypt token of 'Blue Key' ...
Token decryption succeeded.
Please connect the FIDO2 key you wish to add (and disconnect any others).
Press <enter> when ready ...
Checking key at /dev/hidraw1 ...
Key supports the hmac-secret extension.
Making FIDO2 credential ...
Touch your authenticator device now ...
Success.
Getting hmac-secret ...
Touch your authenticator device now ...
Success.
Enter password (leave blank for none):
Confirm password:
Enter name for this key: Red Key
FIDO2 key successfully added.
FidoVault '<vaultname> updated.
Print a FidoVault secret:
$ fidovault.py -v <vaultname>
Checking key at /dev/hidraw1 ...
Key supports the hmac-secret extension.
Touch your authenticator device now ...
Enter password (leave blank for none):
Attempting to decrypt token of 'Blue Key' ...
Token decryption succeeded.
<secret>
FidoVault is designed to be used in conjunction with other programs, by providing a secret to them. For programs that accept a secret on STDIN, simply pipe FidoVault's STDOUT to them (all FidoVault user interaction output is written to STDERR / /dev/tty, and so will be printed to the terminal and not redirected to the other program). E.g., to use a FidoVault secret for symmetric encryption and decryption of a file with GnuPG, run:
$ fidovault.py -v <vaultname> | gpg --passphrase-fd 0 --pinentry-mode loopback -c <filename>
and:
$ fidovault.py -v <vaultname> | gpg --passphrase-fd 0 --pinentry-mode loopback --output <filename> -d <filename.gpg>
To open a KeePassXC database with a FidoVault secret as password, run:
$ fidovault.py -v <vaultname> | keepassxc --pw-stdin /path/to/database.kdbx
(Unfortunately, this only works if KeePassXC is not currently running.)
For programs that expect a secret as an argument, FidoVault can pass a secret to them via xargs. E.g., to open a KeePassXC database with a FidoVault secret as password via D-Bus when KeePassXC is already running, run:
$ fidovault.py -v <vaultname> | xargs qdbus org.keepassxc.KeePassXC.MainWindow /keepassxc org.keepassxc.KeePassXC.MainWindow.openDatabase /path/to/database.kdbx
(On Debian Sid, replace qdbus with qdbus6.)
To pass the secret at a position other than the end of the command, use the -I replace-str argument of xargs. E.g., to open a KeePassXC database with a FidoVault secret as a password plus a keyfile that resides somewhere in the filesystem via D-Bus, run:
$ fidovault.py -v <vaultname> | xargs -I % qdbus org.keepassxc.KeePassXC.MainWindow /keepassxc org.keepassxc.KeePassXC.MainWindow.openDatabase /path/to/database.kdbx % /path/to/keyfile
qdbus command is additionally insecure since it will place the secret on the D-Bus message bus, which also may be accessible to others.
The original motivation of FidoVault was the desire to implement a standalone tool to open KeePassXC databases with FIDO2 keys, but the code quickly evolved into a more general purpose tool. FidoVault's basic architecture was inspired by the discussion here, as well as the design of LUKS plus its systemd-cryptenroll extension. Indeed, I seriously contemplated using LUKS + systemd-cryptenroll (possibly with loop devices) as a general purpose FIDO2-protected secret store, but since LUKS is designed around block devices and the device mapper, it cannot be easily used by non-root users.
Other projects similar to FidoVault (which I encountered after implementing FidoVault):
FidoVault is absolutely free software, and there is no expectation of any sort of compensation or support for the project. That being said, if anyone wishes to donate (to Thomas More, the tool's primary author), this can be done via the Ko-fi platform.
FidoVault is free / open source software, released under the terms of the GNU GPLv3 or later.