| 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. |