From 4b5e5da6061983964a85d1671bd1c97c48ee76f1 Mon Sep 17 00:00:00 2001 From: jbash aka John Bashinski Date: Thu, 1 Aug 2019 13:21:35 -0400 Subject: [PATCH] Documentation: add systemd warning for rd.luks.key, clean up related text --- dracut.cmdline.7.asc | 78 ++++++++++++++++++++++++++++++-------------- 1 file changed, 53 insertions(+), 25 deletions(-) diff --git a/dracut.cmdline.7.asc b/dracut.cmdline.7.asc index c45cdf57c..551c5e8b0 100644 --- a/dracut.cmdline.7.asc +++ b/dracut.cmdline.7.asc @@ -318,22 +318,37 @@ crypto LUKS crypto LUKS - key on removable device support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**rd.luks.key=**____:____:____:: - _keypath_ is a path to key file to look for. It's REQUIRED. When _keypath_ - ends with '.gpg' it's considered to be key encrypted symmetrically with GPG. - You will be prompted for password on boot. GPG support comes with - 'crypt-gpg' module which needs to be added explicitly. -+ -_keydev_ is a device on which key file resides. It might be kernel name of -devices (should start with "/dev/"), UUID (prefixed with "UUID=") or label -(prefix with "LABEL="). You don't have to specify full UUID. Just its beginning -will suffice, even if its ambiguous. All matching devices will be probed. -This parameter is recommended, but not required. If not present, all block -devices will be probed, which may significantly increase boot time. -+ -If _luksdev_ is given, the specified key will only be applied for that LUKS -device. Possible values are the same as for _keydev_. Unless you have several -LUKS devices, you don't have to specify this parameter. The simplest usage is: + +NB: If systemd is included in the dracut initrd, dracut's built in +removable device keying support won't work. systemd will prompt for +a password from the console even if you've supplied **rd.luks.key**. +You may be able to use standard systemd *fstab*(5) syntax to +get the same effect. If you do need **rd.luks.key** to work, +you will have to exclude the "systemd" dracut module and any modules +that depend on it. See *dracut.conf*(5) and +https://bugzilla.redhat.com/show_bug.cgi?id=905683 for more +information. + +**rd.luks.key=**_[:[:]]_:: + __ is the pathname of a key file, relative to the root + of the filesystem on some device. It's REQUIRED. When + __ ends with '.gpg' it's considered to be key encrypted + symmetrically with GPG. You will be prompted for the GPG password on + boot. GPG support comes with the 'crypt-gpg' module, which needs to be + added explicitly. ++ +__ identifies the device on which the key file resides. It may +be the kernel name of the device (should start with "/dev/"), a UUID +(prefixed with "UUID=") or a label (prefix with "LABEL="). You don't +have to specify a full UUID. Just its beginning will suffice, even if +its ambiguous. All matching devices will be probed. This parameter is +recommended, but not required. If it's not present, all block devices will +be probed, which may significantly increase boot time. ++ +If __ is given, the specified key will only be used for +the specified LUKS device. Possible values are the same as for +__. Unless you have several LUKS devices, you don't have to +specify this parameter. The simplest usage is: + [listing] .Example @@ -342,27 +357,40 @@ rd.luks.key=/foo/bar.key -- + As you see, you can skip colons in such a case. -+ + [NOTE] =============================== -dracut pipes key to cryptsetup with _-d -_ argument, therefore you need to pipe -to crypsetup luksFormat with _-d -_, too! +Your LUKS partition must match your key file. + +dracut provides keys to cryptsetup with _-d_ (an older alias for +_--key-file_). This uses the entire binary +content of the key file as part of the secret. If +you pipe a password into cryptsetup *without* _-d_ or _--key-file_, +it will be treated as text user input, and only characters before +the first newline will be used. Therefore, when you're creating +an encrypted partition for dracut to mount, and you pipe a key into +_cryptsetup luksFormat_,you must use _-d -_. -Here follows example for key encrypted with GPG: +Here is an example for a key encrypted with GPG (warning: +_--batch-mode_ will overwrite the device without asking for +confirmation): [listing] -- gpg --quiet --decrypt rootkey.gpg | \ -cryptsetup -d - -v --cipher serpent-cbc-essiv:sha256 \ ---key-size 256 luksFormat /dev/sda3 +cryptsetup --batch-mode --key-file - \ + luksFormat /dev/sda47 -- -If you use plain keys, just add path to _-d_ option: +If you use unencrypted key files, just use the key file pathname +instead of the standard input. For a random key with 256 bits of +entropy, you might use: [listing] -- -cryptsetup -d rootkey.key -v --cipher serpent-cbc-essiv:sha256 \ - --key-size 256 luksFormat /dev/sda3 +head -32c /dev/urandom > rootkey.key +cryptsetup --batch-mode --key-file rootkey.key \ + luksFormat /dev/sda47 -- =============================== -- 2.47.2