Debian Codegraph @

README.md

raw ◀ ▶
Source reconstructed at patch state 0 of 2 — not the installed (fully patched) source.
2 Debian patches touch this file
1 # fido2luks
2
3 This is an initramfs-tools extension to unlock LUKS-encrypted
4 volumes at boot time using a FIDO2 token (YubiKey, Nitrokey, ...).
5
6 `fido2luks` is designed for scenarios where a FIDO2 token has been
7 enrolled into a LUKS volume using `systemd-cryptenroll --fido2-device`,
8 but systemd itself is not used in the initramfs.
9
10 This has been successfully tested with Debian bookworm and trixie.
11
12 ## How to use it
13
14 - ⚠️ **Warning**: this can render your system unbootable, so make sure
15 that you have a backup of your files or a working initramfs that you
16 can use as a fallback in case things go wrong.
17
18 - Dependencies: you need `initramfs-tools`, `fido2-tools` and `jq` on
19 your system.
20
21 - Install `fido2luks` using one of the Debian packages available on
22 the GitHub [releases page](https://github.com/bertogg/fido2luks/releases).
23 If you prefer, you can also build your own package using the provided
24 scripts by running `fakeroot debian/rules binary` and installing the
25 resulting `.deb` file. Alternatively, you can skip the Debian
26 package and install `fido2luks` directly with `make install`.
27
28 - Make sure that the LUKS volume has been set up, e.g.:
29 `systemd-cryptenroll --fido2-device=auto --fido2-with-client-pin=true --fido2-with-user-presence=true /dev/XXX`.
30 You should be able to see the `systemd-fido2` token data if you run
31 `cryptsetup luksDump /dev/XXX`.
32
33 - Edit `/etc/crypttab` and add `keyscript=/lib/fido2luks/keyscript.sh`
34 to the options of the volume that you want to unlock.
35
36 - Generate a new initramfs with `update-initramfs -u`.
37
38 That's it. Next time you boot the system `fido2luks` should detect if
39 your FIDO2 token is inserted and use it to unlock the LUKS volume. If
40 the token is not detected then it will fall back to using a regular
41 passphrase as usual.
42
43 If you have multiple tokens you can enroll all of them, and
44 `fido2luks` will detect which one to use at boot time.
45
46 ## How this works
47
48 If you are not interested in the technical details you can skip this
49 section.
50
51 When systemd enrolls a FIDO2 token into a LUKS volume it uses an
52 extension called hmac-secret, supported by many hardware tokens.
53
54 In a nutshell, the token calculates an HMAC using a secret that never
55 leaves the device and a salt provided by the user. The result is sent
56 back to the user and is used to unlock the LUKS volume.
57
58 Since nothing is stored on the hardware token itself the user needs to
59 provide some data that is kept on the LUKS header:
60
61 - A credential ID (previously generated during the enrollment process).
62 - A _relying party_ ID (`io.systemd.cryptsetup` in this case).
63 - The aforementioned salt (which should be random and different for
64 each LUKS volume).
65 - Some settings such as whether to require a PIN or presence
66 verification (usually physically touching the USB key).
67
68 Check out the scripts in the examples/ directory to see how to
69 generate your own credentials and secrets. See also the
70 `fido2-cred(1)` and `fido2-assert(1)` manpages for more details.
71
72 ## Credits and license
73
74 fido2luks was written by Alberto Garcia and is distributed under the
75 GNU GPL.