#fido2 #luks #u2f #encryption-decryption

app fido2luks

Decrypt your LUKS partition using a FIDO2 compatible authenticator

18 releases

0.2.19 Jul 26, 2021
0.2.16 Feb 8, 2021
0.2.14 Sep 6, 2020
0.2.9 Jun 23, 2020
0.2.1 Oct 10, 2019

#289 in Authentication

Download history 1/week @ 2024-02-13 44/week @ 2024-02-20 3/week @ 2024-02-27 8/week @ 2024-03-12 19/week @ 2024-03-26 77/week @ 2024-04-02

96 downloads per month

MPL-2.0 license

1.5K SLoC

Rust 1.5K SLoC // 0.0% comments Shell 283 SLoC // 0.1% comments Bitbake 14 SLoC // 0.3% comments

fido2luks Crates.io Version

This will allow you to unlock your LUKS encrypted disk with an FIDO2 compatible key.

Note: This has only been tested under Fedora 31, Ubuntu 20.04, NixOS using a Solo Key, Trezor Model T, YubiKey(fw >= 5.2.3)



dnf install clang cargo cryptsetup-devel -y


git clone https://github.com/shimunn/fido2luks.git && cd fido2luks

# Alternativly cargo build --release && sudo cp target/release/fido2luks /usr/bin/
sudo -E cargo install -f --path . --root /usr

# Copy template
cp dracut/96luks-2fa/fido2luks.conf /etc/
# Name is optional but useful if your authenticator has a display
echo FIDO2LUKS_CREDENTIAL_ID=$(fido2luks credential [NAME]) >> /etc/fido2luks.conf

# Load config into env
set -a
. /etc/fido2luks.conf

# Repeat for each luks volume
# You can also use the `--token` flag when using LUKS2 which will then store the credential in the LUKS header,
# enabling you to use `fido2luks open-token` without passing a credential as parameter
sudo -E fido2luks -i add-key /dev/disk/by-uuid/<DISK_UUID>

# Test(only works if the luks container isn't active)
sudo -E fido2luks -i open /dev/disk/by-uuid/<DISK_UUID> luks-<DISK_UUID>


cd dracut

sudo make install


Add rd.luks.2fa=<CREDENTIAL_ID>:<DISK_UUID> to GRUB_CMDLINE_LINUX in /etc/default/grub

Note: This is only required for your root disk, systemd will try to unlock all other LUKS partions using the same key if you added it using fido2luks add-key

grub2-mkconfig > /boot/grub2/grub.cfg

I'd also recommend to copy the executable onto /boot so that it is accessible in case you have to access your disk from a rescue system

mkdir /boot/fido2luks/
cp /usr/bin/fido2luks /boot/fido2luks/
cp /etc/fido2luks.conf /boot/fido2luks/


Just reboot and see if it works, if that's the case you should remove your old less secure password from your LUKS header:

# Recommend in case you lose your authenticator, store this backupfile somewhere safe
cryptsetup luksHeaderBackup /dev/disk/by-uuid/<DISK_UUID> --header-backup-file luks_backup_<DISK_UUID>
# There is no turning back if you mess this up, make sure you made a backup
# You can also pass `--token` if you're using LUKS2 which will then store the credential in the LUKS header,
# which will enable you to use `fido2luks open-token` without passing a credential as parameter
fido2luks -i add-key --exclusive /dev/disk/by-uuid/<DISK_UUID>

Addtional settings

Password less

Remove your previous secret as described in the next section, in case you've already added one.

Open /etc/fido2luks.conf and replace FIDO2LUKS_SALT=Ask with FIDO2LUKS_SALT=string:<YOUR_RANDOM_STRING> but be warned that this password will be included to into your initramfs.

Import the new config into env:

set -a
. /etc/fido2luks.conf

Then add the new secret to each device and update dracut afterwards dracut -f

Multiple keys

Additional/backup keys are supported, Multiple fido2luks credentials can be added to your /etc/fido2luks.conf file. Credential tokens are comma separated.



Remove rd.luks.2fa from GRUB_CMDLINE_LINUX in /etc/default/grub

set -a
. fido2luks.conf
sudo -E fido2luks -i replace-key /dev/disk/by-uuid/<DISK_UUID>

sudo rm -rf /usr/lib/dracut/modules.d/96luks-2fa /etc/dracut.conf.d/luks-2fa.conf /etc/fido2luks.conf

Theory of operation

fido2luks builds on two basic building blocks, LUKS as an abstraction over linux disk encryption and and the FIDO2 extension hmac-secret. The hmac-secret extension allows for an secret to be dervied on the FIDO2 device from two inputs, the user supplied salt/password/keyfile and another secret contained within the FID2 device. The output of the hmac-secret function will then be used to decrypt the LUKS header which in turn is used to decrypt the disk.

        |                                                                               |
        |                       +-----------------------------------------+             |
        |                       |               FIDO2 device              |             |
        |                       |                                         |             |
        |                       |                                         |             |
+-------+--------+   +------+   |                      +---------------+  |             |             +------------------------+
| Salt/Password  +-> |sha256+------------------------> |               |  |             v             |      LUKS header       |
+----------------+   +------+   |                      |               |  |                           |                        |           +---------------+   
                                |                      |               |  |        +--------+         +------------------------+-------->  |Disk master key| 
                                |                      |  sha256_hmac  +---------> | sha256 +-------> | Keyslot 1              |           +---------------+ 
+----------------+              |  +----------+        |               |  |        +--------+         +------------------------+
| FIDO credential+---------------> |Credential| +----> |               |  |                           | Keyslot 2              |
+----------------+              |  |secret    |        |               |  |                           +------------------------+
                                |  +----------+        +---------------+  |
                                |                                         |
                                |                                         |

Since all these components build upon each other losing or damaging just one of them will render the disk undecryptable, it's threfore of paramount importance to backup the LUKS header and ideally set an backup password or utilise more than one FIDO2 device. Each additional credential and password combination will require it's own LUKS keyslot since the credential secret is randomly generated for each new credential and will thus result in a completly different secret.


Licensed under


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the MPL 2.0 license, shall be licensed as above, without any additional terms or conditions.


~371K SLoC