From: jbash aka John Bashinski Date: Wed, 23 Oct 2019 12:46:46 +0000 (+0200) Subject: Documentation: add systemd warning for rd.luks.key, clean up related text X-Git-Tag: 050~137 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=7f0b48627a8cfdaba7263a35c827ff73e956a65c;p=thirdparty%2Fdracut.git Documentation: add systemd warning for rd.luks.key, clean up related text Harald Hoyer : Squashed commit of the following: commit 4b5e5da6061983964a85d1671bd1c97c48ee76f1 Author: jbash aka John Bashinski Date: Thu Aug 1 13:21:35 2019 -0400 Documentation: add systemd warning for rd.luks.key, clean up related text --- diff --git a/dracut.cmdline.7.asc b/dracut.cmdline.7.asc index bf52dd4eb..e91f967dd 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 cryptsetup 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 -- ===============================