Merge pull request #259773 from dadada/dadada/luks-fido2-systemd

1 files changed, 40 insertions, 2 deletions

diff --git a/nixos/doc/manual/configuration/luks-file-systems.section.md b/nixos/doc/manual/configuration/luks-file-systems.section.md
index b5d0407d1659..7615b95aef42 100644
--- a/nixos/doc/manual/configuration/luks-file-systems.section.md
+++ b/nixos/doc/manual/configuration/luks-file-systems.section.md
@@ -42,8 +42,12 @@ boot.loader.grub.enableCryptodisk = true;
 
 ## FIDO2 {#sec-luks-file-systems-fido2}
 
-NixOS also supports unlocking your LUKS-Encrypted file system using a
-FIDO2 compatible token. In the following example, we will create a new
+NixOS also supports unlocking your LUKS-Encrypted file system using a FIDO2
+compatible token.
+
+### Without systemd in initrd {#sec-luks-file-systems-fido2-legacy}
+
+In the following example, we will create a new
 FIDO2 credential and add it as a new key to our existing device
 `/dev/sda2`:
 
@@ -75,3 +79,37 @@ as [Trezor](https://trezor.io/).
 ```nix
 boot.initrd.luks.devices."/dev/sda2".fido2.passwordLess = true;
 ```
+
+### systemd Stage 1 {#sec-luks-file-systems-fido2-systemd}
+
+If systemd stage 1 is enabled, it handles unlocking of LUKS-enrypted volumes
+during boot. The following example enables systemd stage1 and adds support for
+unlocking the existing LUKS2 volume `root` using any enrolled FIDO2 compatible
+tokens.
+
+```nix
+boot.initrd = {
+  luks.devices.root = {
+    crypttabExtraOpts = [ "fido2-device=auto" ];
+    device = "/dev/sda2";
+  };
+  systemd.enable = true;
+};
+```
+
+All tokens that should be used for unlocking the LUKS2-encrypted volume must
+first be enrolled using [systemd-cryptenroll](https://www.freedesktop.org/software/systemd/man/systemd-cryptenroll.html).
+In the following example, a new key slot for the first discovered token is
+added to the LUKS volume.
+
+```ShellSession
+# systemd-cryptenroll --fido2-device=auto /dev/sda2
+```
+
+Existing key slots are left intact, unless `--wipe-slot=` is specified. It is
+recommened to add a recovery key that should be stored in a secure physical
+location and can be entered wherever a password would be entered.
+
+```ShellSession
+# systemd-cryptenroll --recovery-key /dev/sda2
+```