Skip to main content

FidoVault

GitHub Release GitHub Release Date - Published_At PyPI Version PyPI Downloads

GitHub issues GitHub closed issues GitHub commit activity

FidoVault is a tool to control access to secrets via symmetric encryption and decryption using FIDO2 authenticators. A FidoVault vault file contains a secret encrypted via one or more FIDO2 authenticators, such that the secret is inaccessible without at least one of the authenticators, but any single authenticator can decrypt the secret. A password can optionally be required for decryption in addition to an authenticator.

Hardware

Any standard USB authenticator that supports the HMAC Secret Extension (which reportedly most do) should work with FidoVault. NFC and Bluetooth authenticators have not been tested, and PC/SC authenticators are not currently supported. Development and testing have primarily been done using a Yubico Security Key.

Dependencies and Installation

FidoVault is written in Python 3, and has the following dependencies:

  • cryptography (Debian package python3-cryptography) (for symmetric encryption and decryption of secrets)
  • [python-]fido2>=2.0.0 (Debian package python3-fido2) (for accessing FIDO2 authenticators)

FidoVault should work on any platform on which Python 3 and the above dependencies can be installed, although running under Windows may require administrator privileges, since Windows apparently requires administrator privileges for certain FIDO APIs.

At least on Linux, if FidoVault's dependencies are installed and available (e.g., on Debian via apt install python3-fido2, which will pull in python3-cryptography as well), then the script can be run directly without installation as path/to/fidovault.py. It can also be installed from PyPI via pip / pipx, in which case it can be run simply as fidovault.

Usage

Display usage instructions:

$ fidovault -h
usage: fidovault.py [-h] [-v VAULT] [-k KEY] [-p PARAMETERS] [-g N] [-m] [-i | -a]

Create and manage FidoVaults - control access to secrets via symmetric encryption and decryption using FIDO2 authenticators

options:
  -h, --help            show this help message and exit
  -v, --vault VAULT     FidoVault filename
  -k, --key KEY         use (only) this key section of the FidoVault
  -p, --parameters PARAMETERS
                        Argon2id parameters (default: 't=1,p=4,m=2097152'), only used when initializing a FidoVault or adding a key section to one
  -g, --generate N      generate FidoVault secret utilizing N cryptographically random bytes (only used if initializing a FidoVault, otherwise ignored)
  -m, --mlockall        lock all process memory into RAM (Linux only, and the memlock limit must be high enough to accommodate the memory used by Argon2id)
  -i, --init            initialize a FidoVault
  -a, --add             add a key section to a FidoVault

If neither '--init' nor '--add' are specified, the program will attempt to output the FidoVault's secret to STDOUT

Initialize a FidoVault:

$ fidovault -i -v <vaultname>
Enter secret: 
Confirm secret: 
Please connect the device you wish to add (and disconnect any others).
Press <enter> when ready ... 
Checking device at /dev/hidraw1 ...
Device supports the hmac-secret extension
Creating FIDO2 credential ... 
Enter PIN: 
Touch your authenticator now ...
FIDO2 credential created
Enter name for this key section: (default is 'Key 1')
Perform user verification when using this key section? (y/n - default is y) 
Combine password with FIDO2 hmac-secret when using this key section? (y/n - default is y) 
Getting hmac-secret ...
Touch your authenticator now ...
Enter password: 
Confirm password: 
Key section 'Key 1' successfully added
FidoVault '<vaultname>' initialized

Add an additional authenticator to an existing FidoVault (connect an already added authenticator before proceeding):

$ fidovault -a -v <vaultname>
Checking device at /dev/hidraw1 ...
Valid credential found on device
Trying to decode token using 'Key 1' key section ...
Getting hmac-secret ...
Enter PIN: 
Touch your authenticator now ...
Enter password: 
Token decryption succeeded
Please connect the device you wish to add (and disconnect any others).
Press <enter> when ready ... 
Checking device at /dev/hidraw1 ...
Device supports the hmac-secret extension
Creating FIDO2 credential ... 
Enter PIN: 
Touch your authenticator now ...
FIDO2 credential created
Enter name for this key section: (default is 'Key 2')
Perform user verification when using this key section? (y/n - default is y) 
Combine password with FIDO2 hmac-secret when using this key section? (y/n - default is y) 
Getting hmac-secret ...
Touch your authenticator now ...
Enter password: 
Confirm password: 
Key section 'Key 2' successfully added
Updated FidoVault '<vaultname>'

Output a FidoVault secret:

$ fidovault -v <vaultname>
Checking device at /dev/hidraw1 ...
Valid credential found on device
Trying to decode token using 'Key 1' key section ...
Getting hmac-secret ...
Enter PIN: 
Touch your authenticator now ...
Enter password: 
Token decryption succeeded
<secret>

Providing a FidoVault secret to another program

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 -v <vaultname> | gpg --passphrase-fd 0 --pinentry-mode loopback -c <filename>

and:

$ fidovault -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 -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 -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 -v <vaultname> | xargs -I % qdbus org.keepassxc.KeePassXC.MainWindow /keepassxc org.keepassxc.KeePassXC.MainWindow.openDatabase /path/to/database.kdbx % /path/to/keyfile

Memory Security

On Linux, on startup FidoVault calls prctl(PR_SET_DUMPABLE, 0) to disable ptracing and core dumping. If the -m command line flag is given, then FidoVault will also call mlockall(MCL_FUTURE) to lock memory into RAM and disable paging. Memory locking is not done by default, since FidoVault uses the Argon2id algorithm for key derivation, and Argon2id is designed to use a considerable amount of memory, which will cause the program to crash with a memory allocation error when run under typical memlock limits (e.g., 8 MiB in Debian).

Key Derivation

FidoVault currently uses the Argon2id algorithm to derive an encryption key from a combination of a FIDO2 hmac-secret, an optional password, and a randomly chosen key derivation salt. (Earlier versions of the program used the PBKDF2HMAC algorithm; to access a key section created with PBKDF2HMAC, use version 0.1.0 of the program.) The Argon2id parameters of iterations (t), lanes (p), and memory cost (m) can be specified via the FidoVault -p parameter, e.g.:

  • -p 't=1,p=4,m=2097152': This is the "FIRST RECOMMENDED option" of RFC 9106. It requires 2 GiB of memory, and is currently the default if -p is not specified.
  • -p 't=3,p=4,m=65536: This is the "SECOND RECOMMENDED option" of the RFC, for situations where "much less memory is available."

See the RFC for more information on choosing parameters. (The KDF salt and tag lengths cannot be user-specified: the former is always 128 bits (16 bytes), and the latter is always 256 bits (32 bytes).)

Background

The original motivation of FidoVault was the desire to implement a standalone tool to open KeePassXC databases with FIDO2 authenticators, 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.

Alternatives

Other projects similar to FidoVault:

  • tokenring: "TokenRing is a back-end for the Python keyring module, which uses a hard token to encrypt your collection of passwords as a large Fernet token, composed of individual password entries, each of which is separately encrypted as a smaller Fernet token of its own."
  • age-plugin-fido: "draft fido plugin for age(1)" ("early draft, likely buggy, protocol not finalized", "usability issues with multiple fido keys", "not actually tested with age(1) yet")
  • age-plugin-yubikey: "Encrypt files with fido2 keys that support the "hmac-secret" extension."
  • FileKey: "Files need protection. FileKey secures them. Works with Yubikeys. Drop files in. They lock. Drop them again. They unlock. Your data stays on your device, and only you hold the key. Open source and powered by AES-256 encryption—the same standard trusted by the US government for top-secret information." (Reddit announcement thread)
  • khefin: "A system for using a FIDO2 authenticator with hmac-secret extension support to generate passphrase-protected secrets." (abandoned a couple of years ago)

Contributors

Donations

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.

License

FidoVault is free / open source software, released under the terms of the GNU GPLv3 or later.

Metadata

Release files for fidovault 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fidovault 0.3.0
File Size Uploaded Provenance Actions
fidovault-0.3.0.tar.gz 27.8 kB Without provenance Details for fidovault-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fidovault 0.3.0
File Interpreter ABI Platform Actions
fidovault-0.3.0-py2.py3-none-any.whl Python 2, Python 3 none any Details for fidovault-0.3.0-py2.py3-none-any.whl

Total release size: 53.1 kB

Release files / fidovault-0.3.0.tar.gz

Download URL fidovault-0.3.0.tar.gz
Size 27.8 kB
Tags Source
SHA-256 checksum
How to use checksums
4270b66f714f7e8fa414d2533a8c6cac7c9185c346a24ab44c5c6ea38552c0b3
BLAKE2b-256 checksum
How to use checksums
272b02fbc0e76962486a9d10203b49b70513bfb85bf61dec1250d6091cbc8c5d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via python-requests/2.34.2

Release files / fidovault-0.3.0-py2.py3-none-any.whl

Download URL fidovault-0.3.0-py2.py3-none-any.whl
Size 25.4 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
034c37141463943d414758820eb77efa74ba70e89ab052e89698030c3774ff33
BLAKE2b-256 checksum
How to use checksums
f7abd4b304cd0309fff9c1cef44208ead8dbff0079da67931be9d39b1453b332
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via python-requests/2.34.2

Security for fidovault 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page