genkernel: add keyctl support for loading LUKS passphrase into a keyring

cryptsetup LUKS2 format comes with an ability to automatically unlock
multiple devices (root, swap, etc.) sharing the same passphrase, without
retyping it for each of them, by loading it into the user keyring.

This commit adds such (optional) genkernel support for loading LUKS
passphrase into the user keyring on boot.

In the default mode of operation the newly added key is (possibly) used
only to unlock root and swap devices and is removed soon after that.
By providing appropriate kernel command line parameter the key can be left
in the keyring instead (with an optional timeout) for unlocking other LUKS
devices post-initramfs time.

Because one of the most common use cases of this functionality will be
having an encrypted swap for doing suspend to disk (hibernation) let's also
make sure that we don't unlock the root device when doing so is unnecessary
(when we are resuming the system from hibernation).

Since the security of a FDE passphrase is of paramount importance in this
solution significant care has been taken not to leak it accidentally:
* The passphrase is read directly by keyctl to avoid storing it in the
shell,

* If the passphrase is used only to unlock root and swap devices (which is
the default mode of operation) the init script will check whether its
removal from keyring has actually succeeded and, if not, reboot the system
rather than continue while leaving it exposed,

* keyutils includes a patch (already upstreamed) to wipe the passphrase
from memory when no longer needed.

Signed-off-by: Maciej S. Szmigiero <mail@maciej.szmigiero.name>

1 files changed, 24 insertions, 0 deletions

diff --git a/doc/genkernel.8.txt b/doc/genkernel.8.txt
index ba8fd0a..a5c0b92 100644
--- a/doc/genkernel.8.txt
+++ b/doc/genkernel.8.txt
@@ -468,6 +468,12 @@ system is able to load multiple initramfs.
     `gpg --symmetric -o /path/to/LUKS-key.gpg /path/to/LUKS-key` .
     After that, re-point the *root_key* argument to the new .gpg file.
 
+*--*[*no-*]*keyctl*::
+    Includes or excludes support for keyutils keyctl.
+    This way a LUKS passphrase can be loaded into a keyring at boot time
+    to unlock multiple devices (root, swap, etc.) without retyping it for each
+    one.
+
 *--*[*no-*]*b2sum*::
     Includes or excludes b2sum in the initramfs.
     When enabled, this will compile coreutils' b2sum for you.
@@ -737,6 +743,24 @@ recognized by the kernel itself.
 *swap_keydev_fstype*=<...>::
     Used filesystem for *swap_keydev*. See *rootfstype* for more details.
 
+*keyctl_keydesc*=<...>::
+    Load a passphrase into a keyring at boot time under the key name provided
+    as an argument to this option.
+    This way multiple devices (root, swap, etc.) can be unlocked without
+    retyping the passphrase for each one.
+    You'll need to add this key name as a keyring token to every LUKS device
+    that it is supposed to unlock - have a look at cryptsetup 'token add'
+    operation.
+
+*keyctl_keykeep*::
+    Don't remove the newly added key before starting the real init.
+    Useful if you want to utilize it to unlock LUKS devices post-initramfs.
+
+*keyctl_keytimeout*=<...>::
+    Enable a timeout (in seconds) for the newly added key.
+    This option normally only makes sense when used together with the
+    *keyctl_keykeep* option.
+
 *crypt_silent*::
     Set this to silent all the output related to the cryptographic
     software,  and in case your encrypted device isn't open with the