kernel
/
dracut
mirror of https://git.kernel.org/pub/scm/boot/dracut/dracut.git/
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Documentation: add systemd warning for rd.luks.key, clean up related text 

Harald Hoyer <harald@redhat.com>: Squashed commit of the following:

commit 4b5e5da6061983964a85d1671bd1c97c48ee76f1
Author: jbash aka John Bashinski <jbash@velvet.com>
Date:   Thu Aug 1 13:21:35 2019 -0400

    Documentation: add systemd warning for rd.luks.key, clean up related text
master
jbash aka John Bashinski 2019-10-23 14:46:46 +02:00 committed by Harald Hoyer
parent 5d88809319
commit 7f0b48627a
No known key found for this signature in database
GPG Key ID: 340F12141EA0994D
1 changed files with 51 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
dracut.cmdline.7.asc
View File

@ -318,22 +318,37 @@ crypto LUKS

crypto LUKS - key on removable device support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**rd.luks.key=**__<keypath>__:__<keydev>__:__<luksdev>__::
_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.

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=**_<keypath>[:<keydev>[:<luksdev>]]_::
_<keypath>_ is the pathname of a key file, relative to the root
of the filesystem on some device. It's REQUIRED. When
_<keypath>_ 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.
+
_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.
_<keydev>_ 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 _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:
If _<luksdev>_ is given, the specified key will only be used for
the specified 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:
+
[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.

Here follows example for key encrypted with GPG:
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 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
--
===============================