diff options
Diffstat (limited to 'debian/doc')
| -rw-r--r-- | debian/doc/cryptdisks_start.xml | 60 | ||||
| -rw-r--r-- | debian/doc/cryptdisks_stop.xml | 55 | ||||
| -rw-r--r-- | debian/doc/cryptsetup-suspend.xml | 120 | ||||
| -rw-r--r-- | debian/doc/crypttab.xml | 772 | ||||
| -rw-r--r-- | debian/doc/manpages.xml | 10 | ||||
| -rw-r--r-- | debian/doc/pandoc/encrypted-boot.md | 536 | ||||
| -rw-r--r-- | debian/doc/pandoc/index.md | 24 | ||||
| -rw-r--r-- | debian/doc/pandoc/pandoc.css | 77 | ||||
| -rw-r--r-- | debian/doc/variables.xml.in | 16 |
9 files changed, 1670 insertions, 0 deletions
diff --git a/debian/doc/cryptdisks_start.xml b/debian/doc/cryptdisks_start.xml new file mode 100644 index 0000000..fd8269d --- /dev/null +++ b/debian/doc/cryptdisks_start.xml @@ -0,0 +1,60 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd"> + +<refentry id="command.cryptdisks_start"> + + <xi:include href="variables.xml" + xpointer="xpointer(/refentry/refentryinfo)" + xmlns:xi="http://www.w3.org/2001/XInclude"/> + + <refmeta> + <refentrytitle>cryptdisks_start</refentrytitle> + <manvolnum>8</manvolnum> + <xi:include href="variables.xml" + xpointer="xpointer(/refentry/refmeta/*)" + xmlns:xi="http://www.w3.org/2001/XInclude"/> + </refmeta> + + <refnamediv> + <refname>cryptdisks_start</refname> + <refpurpose>wrapper around cryptsetup that parses /etc/crypttab.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <simpara> + <emphasis role="strong">cryptdisks_start</emphasis> + <emphasis><name></emphasis> + </simpara> + </refsynopsisdiv> + + <refsect1 id="cryptdisks_start.description"> + <title>DESCRIPTION</title> + <simpara> + <emphasis role="strong">cryptdisks_start</emphasis> is a wrapper around + <emphasis role="strong">cryptsetup</emphasis> that parses + <emphasis role="strong">/etc/crypttab</emphasis> just like the initscript + /etc/init.d/cryptdisks does and starts the dm-crypt mapping that + corresponds to <emphasis><name></emphasis>. + </simpara> + <simpara> + Note that this wrapper passes <option>--key-file=-</option> to + <command moreinfo="refentry">cryptsetup</command>, so the passphrase + in any referenced key file must not be followed by a newline character. + </simpara> + </refsect1> + + <refsect1 id="cryptdisks_start.see_also"> + <title>SEE ALSO</title> + <simpara> + <emphasis>cryptdisks_stop</emphasis>(8), + <emphasis>cryptsetup</emphasis>(8), <emphasis>crypttab</emphasis>(5) + </simpara> + </refsect1> + + <refsect1 id="cryptdisks_start.author"> + <title>AUTHOR</title><simpara>This manual page was written by Jonas Meurer + <mejo@debian.org> in December 2007. + </simpara> + </refsect1> + +</refentry> diff --git a/debian/doc/cryptdisks_stop.xml b/debian/doc/cryptdisks_stop.xml new file mode 100644 index 0000000..b0ed32a --- /dev/null +++ b/debian/doc/cryptdisks_stop.xml @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd"> + +<refentry id="command.cryptdisks_stop"> + + <xi:include href="variables.xml" + xpointer="xpointer(/refentry/refentryinfo)" + xmlns:xi="http://www.w3.org/2001/XInclude"/> + + <refmeta> + <refentrytitle>cryptdisks_stop</refentrytitle> + <manvolnum>8</manvolnum> + <xi:include href="variables.xml" + xpointer="xpointer(/refentry/refmeta/*)" + xmlns:xi="http://www.w3.org/2001/XInclude"/> + </refmeta> + + <refnamediv> + <refname>cryptdisks_stop</refname> + <refpurpose>wrapper around cryptsetup that parses /etc/crypttab.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <simpara> + <emphasis role="strong">cryptdisks_stop</emphasis> + <emphasis><name></emphasis> + </simpara> + </refsynopsisdiv> + + <refsect1 id="cryptdisks_stop.description"> + <title>DESCRIPTION</title> + <simpara> + <emphasis role="strong">cryptdisks_stop</emphasis> is a wrapper around + <emphasis role="strong">cryptsetup</emphasis> that parses + <emphasis role="strong">/etc/crypttab</emphasis> just like the initscript + /etc/init.d/cryptdisks does and stops the dm-crypt mapping that corresponds + to <emphasis><name></emphasis>. + </simpara> + </refsect1> + + <refsect1 id="cryptdisks_stop.see_also"> + <title>SEE ALSO</title> + <simpara> + <emphasis>cryptdisks_start</emphasis>(8), + <emphasis>cryptsetup</emphasis>(8), <emphasis>crypttab</emphasis>(5) + </simpara> + </refsect1> + + <refsect1 id="cryptdisks_stop.author"> + <title>AUTHOR</title><simpara>This manual page was written by Jonas Meurer + <mejo@debian.org> in January 2008. + </simpara> + </refsect1> + +</refentry> diff --git a/debian/doc/cryptsetup-suspend.xml b/debian/doc/cryptsetup-suspend.xml new file mode 100644 index 0000000..c179a6c --- /dev/null +++ b/debian/doc/cryptsetup-suspend.xml @@ -0,0 +1,120 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd"> + +<refentry id="overview.cryptsetup-suspend"> + + <xi:include href="variables.xml" + xpointer="xpointer(/refentry/refentryinfo)" + xmlns:xi="http://www.w3.org/2001/XInclude"/> + + <refmeta> + <refentrytitle>cryptsetup-suspend</refentrytitle> + <manvolnum>7</manvolnum> + <xi:include href="variables.xml" + xpointer="xpointer(/refentry/refmeta/*)" + xmlns:xi="http://www.w3.org/2001/XInclude"/> + </refmeta> + + <refnamediv> + <refname>cryptsetup-suspend</refname> + <refpurpose>automatically suspend LUKS devices on system suspend</refpurpose> + </refnamediv> + + <refsect1 id="cryptsetup-suspend.description"> + <title>DESCRIPTION</title> + <simpara> + <emphasis>cryptsetup-suspend</emphasis> brings support to automatically + suspend LUKS devices before entering system suspend mode. Devices will be + unlocked at system resume time, asking for passwords if required. + The feature is enabled automatically by installing the + <emphasis>cryptsetup-suspend</emphasis> package. No further configuration + is required. + </simpara> + <simpara> + <emphasis>cryptsetup-suspend</emphasis> supports all setups of LUKS + devices that are supported by the <emphasis>cryptsetup</emphasis> + packages. To do so, it depends on scripts from the Debian package + <emphasis>cryptsetup-initramfs</emphasis>. See the + <reference>INTERNALS</reference> section about details on how it works. + </simpara> + </refsect1> + + <refsect1 id="cryptsetup-suspend.security-aspects"> + <title>SECURITY ASPECTS</title> + <simpara> + Suspending LUKS devices basically means to remove the corresponding + encryption keys from system memory. This protects against all sort of + attacks that try to read out the memory from a suspended system, like + for example cold-boot attacks. + </simpara> + <simpara> + <emphasis>cryptsetup-suspend</emphasis> protects <emphasis>only</emphasis> + the encryption keys of your LUKS devices against being read from the + memory. Most likely there's more sensitive data in system memory, be + it other kinds of private keys (e.g. OpenPGP, OpenSSH) or any kind + of documents with sensitive content. + </simpara> + <simpara> + The initramfs image is extracted in memory and left unencrypted (see the + <reference>INTERNALS</reference> section) so all key material it might + include, for instance key files copied using the hooks' + <emphasis>KEYFILE_PATTERN=</emphasis> option, will remain unprotected. + </simpara> + </refsect1> + + + <refsect1 id="cryptsetup-suspend.limitations"> + <title>LIMITATIONS</title> + <simpara> + The <emphasis>cryptsetup-suspend</emphasis> feature is limited to LUKS + devices and doesn't work with <emphasis>plain dm-crypt</emphasis> or + <emphasis>tcrypt</emphasis> devices. + </simpara> + </refsect1> + + <refsect1 id="cryptsetup-suspend.internals"> + <title>INTERNALS</title> + <simpara> + <emphasis>cryptsetup-suspend</emphasis> consists of three parts: + <simplelist type="inline"> + <member> + <command>cryptsetup-suspend</command>: A c program that takes a list + of LUKS devices as arguments, suspends them via + <emphasis>luksSuspend</emphasis> and suspends the system afterwards. + </member> + <member> + <command>cryptsetup-suspend-wrapper</command>: A shell wrapper script + which works the following way: + <simplelist type="inline"> + <member>1. Disable swap and extract the initramfs into a tmpfs (the chroot)</member> + <member>2. Run (systemd) pre-suspend scripts, stop udev, freeze cgroups</member> + <member>3. run cryptsetup-suspend in chroot</member> + <member>4. resume initramfs devices inside chroot after resume</member> + <member>5. resume non-initramfs devices outside chroot</member> + <member>6. thaw groups, start udev, run (systemd) post-suspend scripts</member> + <member>7. Unmount the tmpfs and re-enable swap</member> + </simplelist> + </member> + <member> + A systemd unit drop-in file that overrides the Exec property of + <filename class="devicefile">systemd-suspend.service</filename> so that + it invokes the script <command>cryptsetup-suspend-wrapper</command>. + </member> + </simplelist> + </simpara> + </refsect1> + + <refsect1 id="cryptsetup-suspend.see_also"> + <title>SEE ALSO</title> + <simpara> + <emphasis>cryptsetup</emphasis>(8), <emphasis>crypttab</emphasis>(5) + </simpara> + </refsect1> + + <refsect1 id="cryptsetup-suspend.author"> + <title>AUTHOR</title><simpara>This manual page was written by Jonas Meurer + <jonas@freesources.org> in December 2019. + </simpara> + </refsect1> + +</refentry> diff --git a/debian/doc/crypttab.xml b/debian/doc/crypttab.xml new file mode 100644 index 0000000..c6077a7 --- /dev/null +++ b/debian/doc/crypttab.xml @@ -0,0 +1,772 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd"> + +<refentry id="file.crypttab"> + + <xi:include href="variables.xml" + xpointer="xpointer(/refentry/refentryinfo)" + xmlns:xi="http://www.w3.org/2001/XInclude"/> + + <refmeta> + <refentrytitle>crypttab</refentrytitle> + <manvolnum>5</manvolnum> + <xi:include href="variables.xml" + xpointer="xpointer(/refentry/refmeta/*)" + xmlns:xi="http://www.w3.org/2001/XInclude"/> + </refmeta> + + <refnamediv> + <refname>crypttab</refname> + <refpurpose>static information about encrypted filesystems</refpurpose> + </refnamediv> + + <refsect1 id="crypttab.description"> + <title>DESCRIPTION</title> + <simpara> + The file <filename>/etc/crypttab</filename> contains descriptive + information about encrypted devices. <filename>crypttab</filename> + is only read by programs (e.g. + <command moreinfo="refentry">cryptdisks_start</command> and + <command moreinfo="refentry">cryptdisks_stop</command>), + and not written; it is the duty of the system + administrator to properly create and maintain this file. + <filename>crypttab</filename> entries are treated sequentially, so their + order matters (dependencies need to listed first). + </simpara> + <simpara> + Each encrypted device is described on a separate line. Fields on each line + are separated by tabs or spaces. Lines starting with '#' are comments, and blank + lines are ignored. + Octal sequences <code>\0</code><emphasis>num</emphasis> within a field are + decoded, which can be used for values containing spaces or special characters. + A backslash which doesn't start an octal sequence yields undefined behavior. + </simpara> + <simpara> + The first field, <emphasis>target</emphasis>, describes the mapped + device name. It must be a plain filename without any directory components. + A mapped device which encrypts/decrypts data to/from the <emphasis>source + device</emphasis> will be created at + <filename class="devicefile">/dev/mapper/target</filename> by + <command moreinfo="refentry">cryptsetup</command>. + </simpara> + <simpara> + The second field, <emphasis>source device</emphasis>, describes either the + block special device or file that contains the encrypted data. Instead of + giving the <emphasis>source device</emphasis> explicitly, the UUID + (resp. LABEL, PARTUUID and PARTLABEL) is supported as well, using <quote>UUID=<uuid></quote> + (resp. <quote>LABEL=<label></quote>, <quote>PARTUUID=<partuuid></quote> + and <quote>PARTLABEL=<partlabel></quote>). + </simpara> + <simpara> + The third field, <emphasis>key file</emphasis>, describes the file to use + as a key for decrypting the data of the <emphasis>source device</emphasis>. + In case of a <emphasis>keyscript</emphasis>, the value of this field is + given as argument to the keyscript. + Note that the <emphasis>entire</emphasis> key file will be used as the + passphrase; the passphrase must <emphasis>not</emphasis> be followed by a + newline character. + </simpara> + <simpara> + It can also be a device name (e.g. + <filename class="devicefile">/dev/urandom</filename>), note however that + LUKS requires a persistent key and therefore does <emphasis>not</emphasis> + support random data keys. + </simpara> + <simpara> + If the <emphasis>key file</emphasis> is the string + <emphasis>none</emphasis>, a passphrase will be read interactively from the + console. In this case, the options check, checkargs and tries may be + useful. + </simpara> + <simpara> + The fourth field, <emphasis>options</emphasis>, is an optional comma-separated + list of options and/or flags describing the device type (<emphasis>luks</emphasis>, + <emphasis>tcrypt</emphasis>, <emphasis>bitlk</emphasis>, <emphasis>fvault2</emphasis>, + or <emphasis>plain</emphasis> which is also the default) and cryptsetup options + associated with the encryption process. + The supported options are described below. + For plain dm-crypt devices the <emphasis>cipher</emphasis>, <emphasis>hash</emphasis> + and <emphasis>size</emphasis> options are required. + Some options can be changed on active mappings using + <command>cryptsetup refresh [<options>] <name></command>. + Furthermore some options can be permanently written into metadata of LUKS2 + headers using cryptsetup's <emphasis>--persistent</emphasis> flag. + </simpara> + <simpara> + Note that the first three fields are required and that a missing field will lead + to unspecified behaviour. + </simpara> + </refsect1> + + <refsect1 id="crypttab.implementations"> + <title>ON DIFFERENT CRYPTTAB FORMATS</title> + <simpara> + Please note that there are several independent cryptsetup wrappers with + their own <emphasis>crypttab</emphasis> format. This manpage covers + Debian's implementation for <emphasis>initramfs</emphasis> scripts and + <emphasis>SysVinit</emphasis> init scripts. <emphasis>systemd</emphasis> + brings its own <emphasis>crypttab</emphasis> implementation. + We try to cover the differences between the <emphasis>systemd</emphasis> and + our implementation in this manpage, but if in doubt, better check the + <emphasis>systemd</emphasis> + <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + manpage, e.g. online at + <ulink url="https://www.freedesktop.org/software/systemd/man/crypttab.html"/>. + </simpara> + </refsect1> + + <refsect1 id="crypttab.options"> + <title>OPTIONS</title> + <variablelist> + + <varlistentry> + <term><emphasis>cipher</emphasis>=<cipher></term> + <listitem> + <simpara> + Encryption algorithm (ignored for LUKS and TCRYPT devices). See + <command>cryptsetup -c</command>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>size</emphasis>=<size></term> + <listitem> + <simpara> + Encryption key size (ignored for LUKS and TCRYPT devices). See + <command>cryptsetup -s</command>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>sector-size</emphasis>=<bytes></term> + <listitem> + <simpara> + Sector size. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this option. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>hash</emphasis>=<hash></term> + <listitem> + <simpara> + Hash algorithm (ignored for LUKS and TCRYPT devices). See + <command>cryptsetup -h</command>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>offset</emphasis>=<offset></term> + <listitem> + <simpara> + Start offset (ignored for LUKS and TCRYPT devices). Uses + <emphasis role="strong">cryptsetup -o</emphasis>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>skip</emphasis>=<skip></term> + <listitem> + <simpara> + Skip sectors at the beginning (ignored for LUKS and TCRYPT devices). + Uses <emphasis role="strong">cryptsetup -p</emphasis>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>keyfile-offset</emphasis>=<keyfile-offset></term> + <listitem> + <simpara> + Specifies the number of bytes to skip at the start of the key file. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>keyfile-size</emphasis>=<keyfile-size></term> + <listitem> + <simpara> + Specifies the maximum number of bytes to read from the key file. + The default is to read the whole file up to the compiled-in maximum, + that can be queried with <emphasis role="strong">cryptsetup --help</emphasis>. + This option is ignored for plain dm-crypt devices, as the key file + size is then given by the encryption key size (option + <emphasis>size</emphasis>). + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>keyslot</emphasis>=<slot>, <emphasis>key-slot</emphasis>=<slot></term> + <listitem> + <simpara> + Key slot (ignored for non-LUKS devices). See <command>cryptsetup + -S</command>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>header</emphasis>=<path></term> + <listitem> + <simpara> + Detached header file (ignored for plain dm-crypt devices). See + <command>cryptsetup --header</command>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>verify</emphasis></term> + <listitem> + <simpara> + Verify password. Uses <emphasis role="strong">cryptsetup -y</emphasis>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>readonly</emphasis>, <emphasis>read-only</emphasis></term> + <listitem> + <simpara>Set up a read-only mapping.</simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>tries</emphasis>=<num></term> + <listitem> + <simpara>Try to unlock the device <num> before failing. It's + particularly useful when using a passphrase or a + <emphasis>keyscript</emphasis> that asks for interactive input. If you + want to disable retries, pass <quote>tries=1</quote>. Default is + <quote>3</quote>. Setting <quote>tries=0</quote> means infinitive + retries. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>discard</emphasis></term> + <listitem> + <simpara>Allow using of discards (TRIM) requests for device.</simpara> + <simpara>Starting with Debian 10 (Buster), this option is added per + default to new dm-crypt devices by the Debian Installer. If you + don't care about leaking access patterns (filesystem type, used + space) and don't have hidden truecrypt volumes inside this volume, + then it should be safe to enable this option. See the following + warning for further information.</simpara> + <simpara><emphasis role="strong">WARNING</emphasis>: Assess the + specific security risks carefully before enabling this option. + For example, allowing discards on encrypted devices may lead to + the leak of information about the ciphertext device (filesystem + type, used space etc.) if the discarded blocks can be located + easily on the device later.</simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>luks</emphasis></term> + <listitem> + <simpara>Force LUKS mode. When this mode is used, the following options + are ignored since they are provided by the LUKS header on the device: + <emphasis>cipher=</emphasis>, <emphasis>hash=</emphasis>, + <emphasis>size=</emphasis></simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>plain</emphasis></term> + <listitem> + <simpara>Force plain encryption mode.</simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>bitlk</emphasis></term> + <listitem> + <simpara> + Force BITLK (Windows BitLocker-compatible) mode. + WARNING: <emphasis>crypttab</emphasis> support is currently experimental. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>fvault2</emphasis></term> + <listitem> + <simpara> + Force Apple's FileVault2 mode. + Only the (legacy) FileVault2 format based on Core Storage and HFS+ + filesystem (introduced in MacOS X 10.7 Lion) is currently supported; + the new version of FileVault based on the APFS filesystem used in + recent macOS versions is not supported. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>tcrypt</emphasis></term> + <listitem> + <simpara>Use TrueCrypt encryption mode. When this mode is used, the + following options are ignored since they are provided by the TrueCrypt + header on the device or do not apply: <emphasis>cipher=</emphasis>, + <emphasis>hash=</emphasis>, <emphasis>keyfile-offset=</emphasis>, + <emphasis>keyfile-size=</emphasis>, <emphasis>size=</emphasis></simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>veracrypt</emphasis>, <emphasis>tcrypt-veracrypt</emphasis></term> + <listitem> + <simpara> + Use VeraCrypt extension to TrueCrypt device. Only useful in + conjunction with <emphasis>tcrypt</emphasis> option (ignored for + non-TrueCrypt devices). + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>tcrypthidden</emphasis>, <emphasis>tcrypt-hidden</emphasis></term> + <listitem> + <simpara> + Use hidden TCRYPT header (ignored for non-TCRYPT devices). + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>same-cpu-crypt</emphasis></term> + <listitem> + <simpara> + Perform encryption using the same cpu that IO was submitted on. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>submit-from-crypt-cpus</emphasis></term> + <listitem> + <simpara> + Disable offloading writes to a separate thread after encryption. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>no-read-workqueue</emphasis>, <emphasis>no-write-workqueue</emphasis></term> + <listitem> + <simpara> + Bypass dm-crypt internal workqueue and process read or write requests synchronously. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>swap</emphasis></term> + <listitem> + <simpara> + Run <command moreinfo="refentry">mkswap</command> on the created device. + </simpara> + <simpara> + This option is ignored for <emphasis>initramfs</emphasis> devices. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>tmp</emphasis>[=<tmpfs>]</term> + <listitem> + <simpara> + Run <command moreinfo="refentry">mkfs</command> with filesystem type + <tmpfs> (or ext4 if omitted) on the created device. + </simpara> + <simpara> + This option is ignored for <emphasis>initramfs</emphasis> devices. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>check</emphasis>[=<check>]</term> + <listitem> + <simpara>Check the content of the target device by a suitable program; if + the check fails, the device is closed immediately. The program is being + run with decrypted volume (target device) as first positional argument and, + if the <emphasis>checkargs</emphasis> option is used, its value as second + argument. See the CHECKSCRIPTS section for more information. + </simpara> + <simpara>The program is either specified by full path or relative to + <filename class="directory">/lib/cryptsetup/checks/</filename>. + If omitted, then the value of $CRYPTDISKS_CHECK set in + <filename>/etc/default/cryptdisks</filename> is used + (<filename>blkid</filename> by default). + </simpara> + <simpara> + This option is specific to the Debian <emphasis>crypttab</emphasis> + format. It's not supported by <emphasis>systemd</emphasis>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>checkargs</emphasis>=<arguments></term> + <listitem> + <simpara>Give <arguments> as the second argument to the check + script. See the CHECKSCRIPTS section for more information. + </simpara> + </listitem> + <simpara> + This option is specific to the Debian <emphasis>crypttab</emphasis> + format. It's not supported by <emphasis>systemd</emphasis>. + </simpara> + </varlistentry> + + <varlistentry> + <term><emphasis>initramfs</emphasis></term> + <listitem> + <simpara>The initramfs hook processes the root device, any resume devices + and any devices with the <emphasis>initramfs</emphasis> option set. These + devices are processed within the initramfs stage of boot. As an example, + that allows the use of remote unlocking using dropbear. + </simpara> + <simpara> + This option is specific to the Debian <emphasis>crypttab</emphasis> + format. It's not supported by <emphasis>systemd</emphasis>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>noearly</emphasis></term> + <listitem> + <simpara>The cryptsetup init scripts are invoked twice during the boot + process - once before lvm, raid, etc. are started and once again after + that. Sometimes you need to start your encrypted disks in a special + order. With this option the device is ignored during the first invocation + of the cryptsetup init scripts. + </simpara> + <simpara> + This option is ignored for <emphasis>initramfs</emphasis> devices and + specific to the Debian <emphasis>crypttab</emphasis> format. It's not + supported by <emphasis>systemd</emphasis>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>noauto</emphasis></term> + <listitem> + <simpara>Entirely ignore the device at the boot process. It's still + possible to map the device manually using cryptdisks_start. + </simpara> + <simpara> + This option is ignored for <emphasis>initramfs</emphasis> devices and + specific to the Debian <emphasis>crypttab</emphasis> format. It's not + supported by <emphasis>systemd</emphasis>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>loud</emphasis></term> + <listitem> + <simpara>Be loud. Print warnings if a device does not exist. + This option overrides the option <emphasis>quiet</emphasis>.</simpara> + <simpara> + This option is ignored for <emphasis>initramfs</emphasis> devices and + specific to the Debian <emphasis>crypttab</emphasis> format. It's not + supported by <emphasis>systemd</emphasis>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>quiet</emphasis></term> + <listitem> + <simpara>Be quiet. Don't print warnings if a device does not exist. + This option overrides the option <emphasis>loud</emphasis>.</simpara> + <simpara> + This option is ignored for <emphasis>initramfs</emphasis> devices and + specific to the Debian <emphasis>crypttab</emphasis> format. It's not + supported by <emphasis>systemd</emphasis>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>keyscript</emphasis>=<path></term> + <listitem> + <simpara> + The executable at the indicated path is executed with the value of the + <emphasis>third field</emphasis> as only argument. The keyscript's standard + output is passed to cryptsetup as decyption key. Its exit status is currently + ignored, but no assumption should be made in that regard. + When used in initramfs, the executable either needs to be self-contained + (i.e. doesn't rely on any external program which is not present in the + initramfs environment) or the dependencies have to added to the initramfs + image by other means. + The program is either specified by full path or relative to + <filename class="directory">/lib/cryptsetup/scripts/</filename>. + </simpara> + <simpara> + LIMITATIONS: All binaries and files on which the keyscript depends must + be available at the time of execution. Special care needs to be taken for + encrypted filesystems like /usr or /var. As an example, unlocking + encrypted /usr must not depend on binaries from /usr/(s)bin. + </simpara> + <simpara> + This option is specific to the Debian <emphasis>crypttab</emphasis> + format. It's not supported by <emphasis>systemd</emphasis>. + </simpara> + <simpara> + WARNING: With systemd as init system, this option might be ignored. At + the time this is written (December 2016), the systemd cryptsetup helper + doesn't support the keyscript option to /etc/crypttab. For the time + being, the only option to use keyscripts along with systemd is to force + processing of the corresponding crypto devices in the initramfs. See the + 'initramfs' option for further information. + </simpara> + <para> + All fields of the appropriate crypttab entry are available to the + keyscript as exported environment variables: + <variablelist> + + <varlistentry> + <term>CRYPTTAB_NAME, _CRYPTTAB_NAME</term> + <listitem><para> + The target name (after resp. before octal sequence decoding). + </para></listitem> + </varlistentry> + <varlistentry> + <term>CRYPTTAB_SOURCE, _CRYPTTAB_SOURCE</term> + <listitem><para> + The source device (after resp. before octal sequence decoding and device resolution). + </para></listitem> + </varlistentry> + <varlistentry> + <term>CRYPTTAB_KEY, _CRYPTTAB_KEY</term> + <listitem><para> + The value of the third field (after resp. before octal sequence decoding). + </para></listitem> + </varlistentry> + <varlistentry> + <term>CRYPTTAB_OPTIONS, _CRYPTTAB_OPTIONS</term> + <listitem><para> + A list of exported crypttab options (after resp. before octal sequence decoding). + </para></listitem> + </varlistentry> + <varlistentry> + <term>CRYPTTAB_OPTION_<option></term> + <listitem><para> + The value of the appropriate crypttab option, with value set to 'yes' + in case the option is merely a flag. + For option aliases, such as 'readonly' and 'read-only', the + variable name refers to the first alternative listed (thus + 'CRYPTTAB_OPTION_readonly' in that case). + If the crypttab option name contains '-' characters, then they + are replaced with '_' in the exported variable name. For + instance, the value of the 'CRYPTTAB_OPTION_keyfile_offset' + environment variable is set to the value of the + 'keyfile-offset' crypttab option. + </para></listitem> + </varlistentry> + <varlistentry> + <term>CRYPTTAB_TRIED</term> + <listitem><para> + Number of previous tries since start of cryptdisks (counts until + maximum number of tries is reached). + </para></listitem> + </varlistentry> + + </variablelist> + </para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1 id="crypttab.checkscripts"> + <title>CHECKSCRIPTS</title> + <variablelist> + + <varlistentry> + <term><emphasis>blkid</emphasis></term> + <listitem> + <simpara>Checks for any known filesystem. Supports a filesystem type as + argument via <checkargs>: + </simpara> + <itemizedlist> + <listitem><para> + no checkargs - succeeds if any valid filesystem is found on the device. + </para></listitem> + <listitem><para> + "none" - succeeds if no valid filesystem is found on the device. + </para></listitem> + <listitem><para> + "ext4" [or another filesystem type like xfs, swap, crypto_LUKS, ...] - + succeeds if ext4 filesystem is found on the device. + </para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>un_blkid</emphasis></term> + <listitem> + <simpara>Checks for no known filesystem. Supports a filesystem type as + argument via <checkargs>: + </simpara> + <itemizedlist> + <listitem><para> + no checkargs - succeeds if no valid filesystem is found on the device. + </para></listitem> + <listitem><para> + "ext4" [or another filesystem type like xfs, swap, crypto_LUKS, ...] - + succeeds if no ext4 filesystem is found on the device. + </para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1 id="crypttab.examples"> + <title>EXAMPLES</title> + <para> + <screen> +# Encrypted swap device +cswap /dev/sda6 /dev/urandom plain,cipher=aes-xts-plain64,size=256,hash=sha1,swap + +# Encrypted LUKS disk with interactive password, identified by its UUID, discard enabled +cdisk0 UUID=12345678-9abc-def012345-6789abcdef01 none luks,discard + +# Encrypted TCRYPT disk with interactive password, discard enabled +tdisk0 /dev/sr0 none tcrypt,discard + +# Encrypted ext4 disk with interactive password, discard enabled +# - retry 5 times if the check fails +cdisk1 /dev/sda2 none plain,cipher=aes-xts-plain64,size=256,hash=sha1,check,checkargs=ext4,tries=5,discard + +# Encrypted disk with interactive password, discard enabled +# - use a nondefault check script +# - no retries +cdisk2 /dev/sdc1 none plain,cipher=aes-xts-plain64,size=256,hash=sha1,check=customscript,tries=1,discard + +# Encrypted disk with interactive password, discard enabled +# - Twofish as the cipher, RIPEMD-160 as the hash +cdisk3 /dev/sda3 none plain,cipher=twofish,size=256,hash=ripemd160,discard + </screen> + </para> + </refsect1> + + <refsect1 id="crypttab.environment"> + <title>ENVIRONMENT</title> + <variablelist> + + <varlistentry> + <term><emphasis>CRYPTDISKS_ENABLE</emphasis></term> + <listitem> + <simpara> + Set to <emphasis>yes</emphasis> to run cryptdisks initscripts at startup. + Set to <emphasis>no</emphasis> to disable cryptdisks initscripts. Default + is <emphasis>yes</emphasis>. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>CRYPTDISKS_MOUNT</emphasis></term> + <listitem> + <simpara>Specifies the mountpoints that are mounted before cryptdisks is + invoked. Takes mountpoints configured in /etc/fstab as arguments. Separate + mountpoints by space. + This is useful for keys on removable devices, such as cdrom, usbstick, + flashcard, etc. Default is unset. + </simpara> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>CRYPTDISKS_CHECK</emphasis></term> + <listitem> + <simpara>Specifies the default checkscript to be run against the target + device, after cryptdisks has been invoked. The target device is passed as + the first and only argument to the checkscript. Takes effect if the + <emphasis>check</emphasis> option is given in crypttab with no value. See + documentation for <emphasis>check</emphasis> option above for more + information. + </simpara> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1 id="crypttab.known_upgrade_issues"> + <title>KNOWN UPGRADE ISSUES</title> + <simpara> + The upstream defaults for encryption cipher, hash and keysize have changed + several times in the past, and they're expected to change again in future, + for example if security issues arise. + + On LUKS devices, the used settings are stored in the LUKS header, and thus + don't need to be configured in <filename>/etc/crypttab</filename>. For plain + dm-crypt devices, no information about used cipher, hash and keysize are + available at all. + + Therefore we strongly suggest to configure the cipher, hash and keysize in + <filename>/etc/crypttab</filename> for plain dm-crypt devices, even if they + match the current default. + </simpara> + </refsect1> + + <refsect1 id="crypttab.see_also"> + <title>SEE ALSO</title> + <simplelist type="inline"> + <member><command moreinfo="refentry">cryptsetup</command>(8)</member> + <member><command moreinfo="refentry">cryptdisks_start</command>(8)</member> + <member><command moreinfo="refentry">cryptdisks_stop</command>(8)</member> + <member><filename>/usr/share/doc/cryptsetup-initramfs/README.initramfs.gz</filename></member> + </simplelist> + </refsect1> + + <refsect1 id="crypttab.author"> + <title>AUTHOR</title> + <simpara> + This manual page was originally written by + <author> + <firstname>Bastian</firstname> + <surname>Kleineidam</surname> + </author> + <email>calvin@debian.org</email> + for the Debian distribution of cryptsetup. It has been further improved by + <author> + <firstname>Michael</firstname> + <surname>Gebetsroither</surname> + </author> + <email>michael.geb@gmx.at</email>, + <author> + <firstname>David</firstname> + <surname>Härdeman</surname> + </author> + <email>david@hardeman.nu</email> + and + <author> + <firstname>Jonas</firstname> + <surname>Meurer</surname> + </author> + <email>jonas@freesources.org</email>. + </simpara> + </refsect1> + +</refentry> diff --git a/debian/doc/manpages.xml b/debian/doc/manpages.xml new file mode 100644 index 0000000..4bd59bc --- /dev/null +++ b/debian/doc/manpages.xml @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd"> + +<reference> + <title>Manual Pages</title> + <xi:include href="cryptdisks_start.xml" xpointer="command.cryptdisks_start" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="cryptdisks_stop.xml" xpointer="command.cryptdisks_stop" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="cryptsetup-suspend.xml" xpointer="overview.cryptsetup-suspend" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="crypttab.xml" xpointer="file.crypttab" xmlns:xi="http://www.w3.org/2001/XInclude"/> +</reference> diff --git a/debian/doc/pandoc/encrypted-boot.md b/debian/doc/pandoc/encrypted-boot.md new file mode 100644 index 0000000..27d331b --- /dev/null +++ b/debian/doc/pandoc/encrypted-boot.md @@ -0,0 +1,536 @@ +% Full disk encryption, including `/boot`: Unlocking LUKS devices from GRUB + +Introduction +============ + +So called “full disk encryption” is often a misnomer, because there is +typically a separate plaintext partition holding `/boot`. For instance +the Debian Installer does this in its “encrypted LVM” partitioning method. +Since not all bootloaders are able to unlock LUKS devices, a plaintext +`/boot` is the only solution that works for all of them. + +However, GRUB2 is (since Jessie) able to unlock LUKS devices with its +[`cryptomount`](https://www.gnu.org/software/grub/manual/grub/html_node/cryptomount.html) +command, which therefore enables encryption of the `/boot` partition as +well: using that feature reduces the amount of plaintext data written to +disk. It is especially interesting when GRUB is installed to a read-only +media, for instance as [coreboot payload](https://doc.coreboot.org/payloads.html#grub2) +flashed to a write-protected chip. On the other hand, it is *incompatible* +with some other features that only enabled later at initramfs stage, such +as splash screens or remote unlocking. + +Since enabling unlocking LUKS devices from GRUB [isn't exposed to the d-i +interface](https://bugs.debian.org/814798) (as of Buster), people have +come up with various custom workarounds. But as of Buster [`cryptsetup`(8)] +defaults to a new [LUKS header format version](https://gitlab.com/cryptsetup/LUKS2-docs), +which isn't supported by GRUB as of 2.04. **Hence the pre-Buster +workarounds won't work anymore**. Until LUKS *version 2* support is +[added to GRUB2](https://savannah.gnu.org/bugs/?55093), the device(s) +holding `/boot` needs to be in *LUKS format version 1* to be unlocked from +the boot loader. + +This document describes a generic way to unlock LUKS devices from GRUB +for Debian Buster. + + +Encrypting the device holding `/boot` +===================================== + +There are two alternatives here: + + * Either format an existing `/boot` partition to LUKS1; or + * Move `/boot` to the root file system. The root device(s) needs to + use LUKS version 1, but existing LUKS2 devices can be *converted* + (in-place) to LUKS1. + +These two alternatives are described in the two following sub-sections. + +We assume the system resides on a single drive `/dev/sda`, partitioned +with d-i's “encrypted LVM” scheme: + + root@debian:~# lsblk -o NAME,FSTYPE,MOUNTPOINT /dev/sda + NAME FSTYPE MOUNTPOINT + sda + ├─sda1 ext2 /boot + ├─sda2 + └─sda5 crypto_LUKS + └─sda5_crypt LVM2_member + ├─debian--vg-root ext4 / + └─debian--vg-swap_1 swap [SWAP] + +*Note*: The partition layout of your system may differ. + + +Formatting the existing `/boot` partition to LUKS1 +-------------------------------------------------- + +Since the installer creates a separate (plaintext) `/boot` partition by +default in its “encrypted LVM” partitioning method, the simplest +solution is arguably to re-format it as LUKS1, especially if the root +device is in LUKS2 format. + +That way other partitions, including the one holding the root file +system, can remain in LUKS2 format and benefit from the *stronger +security guaranties* and *convenience features* of the newer version: +more secure (memory-hard) Key Derivation Function, backup header, +ability to offload the volume key to the kernel keyring (thus preventing +access from userspace), custom sector size, persistent flags, unattended +unlocking via kernel keyring tokens, etc. + +Furthermore every command in this sub-section can be run from the main +system: no need to reboot into a live CD or an initramfs shell. + + 1. Before copying content of the `/boot` directory, remount it read-only + to make sure data is not modified while it's being copied. + + root@debian:~# mount -oremount,ro /boot + + 2. Archive the directory elsewhere (on another device), and unmount it + afterwards. + + root@debian:~# install -m0600 /dev/null /tmp/boot.tar + <!-- --> + root@debian:~# tar -C /boot --acls --xattrs --one-file-system -cf /tmp/boot.tar . + <!-- --> + root@debian:~# umount /boot + + (If `/boot` has sub-mountpoints, like `/boot/efi`, you'll need to + unmount them as well.) + + 3. Optionally, wipe out the underlying block device (assumed to be + `/dev/sda1` in the rest of this sub-section). + + root@debian:~# dd if=/dev/urandom of=/dev/sda1 bs=1M status=none + dd: error writing '/dev/sda1': No space left on device + + 4. Format the underlying block device to LUKS1. (Note the `--type luks1` + in the command below, as Buster's [`cryptsetup`(8)] defaults to LUKS + version 2 for `luksFormat`.) + + root@debian:~# cryptsetup luksFormat --type luks1 /dev/sda1 + + WARNING! + ======== + This will overwrite data on /dev/sda1 irrevocably. + + Are you sure? (Type uppercase yes): YES + Enter passphrase for /dev/sda1: + Verify passphrase: + + 5. Add a corresponding entry to [`crypttab`(5)] with mapped device name + `boot_crypt`, and open it afterwards. + + root@debian:~# uuid="$(blkid -o value -s UUID /dev/sda1)" + <!-- --> + root@debian:~# echo "boot_crypt UUID=$uuid none luks" | tee -a /etc/crypttab + <!-- --> + root@debian:~# cryptdisks_start boot_crypt + Starting crypto disk...boot_crypt (starting)... + Please unlock disk boot_crypt: ******** + boot_crypt (started)...done. + + 6. Create a file system on the mapped device. Assuming source device for + `/boot` is specified by its UUID in the [`fstab`(5)] -- which the + Debian Installer does by default -- reusing the old UUID avoids + editing the file. + + root@debian:~# grep /boot /etc/fstab + # /boot was on /dev/sda1 during installation + UUID=c104749f-a0fa-406c-9e9a-3fc01f8e2f78 /boot ext2 defaults 0 2 + <!-- --> + root@debian:~# mkfs.ext2 -m0 -U c104749f-a0fa-406c-9e9a-3fc01f8e2f78 /dev/mapper/boot_crypt + mke2fs 1.44.5 (15-Dec-2018) + Creating filesystem with 246784 1k blocks and 61752 inodes + Filesystem UUID: c104749f-a0fa-406c-9e9a-3fc01f8e2f78 + […] + + 7. Finally, mount `/boot` again from [`fstab`(5)], and copy the saved + tarball to the new (and now encrypted) file system. + + root@debian:~# mount -v /boot + mount: /dev/mapper/boot_crypt mounted on /boot. + <!-- --> + root@debian:~# tar -C /boot --acls --xattrs -xf /tmp/boot.tar + + (If `/boot` had sub-mountpoints, like `/boot/efi`, you'll need to + mount them back as well.) + +You can skip the next sub-section and go directly to [Enabling +`cryptomount` in GRUB2]. Note that `init`(1) needs to unlock the +`/boot` partition *again* during the boot process. See [Avoiding the +extra password prompt] for details and a proposed workaround. (You'll +need to substitute `/` resp. `sda5` with `/boot` resp. `sda1` in that +section, however only steps 1-3 are relevant here: no need to copy the +key file to the initramfs image since `/boot` can be unlocked and +mounted later during the boot process.) + + +Moving `/boot` to the root file system +-------------------------------------- + +The [previous sub-section][Formatting the existing `/boot` partition to LUKS1] +described how to to re-format the `/boot` partition as LUKS1. +Alternatively, it can be moved to the root file system, assuming the +latter is not held by any LUKS2 device. (As shown below, LUKS2 devices +created with default parameters can be “downgraded” to LUKS1.) + +The advantage of this method is that the original `/boot` partition can +be preserved and used in case of *disaster recovery* (if for some reason +the GRUB image is lacking the `cryptodisk` module and the original +plaintext `/boot` partition is lost, you'd need to reboot into a live CD +to recover). Moreover increasing the number of partitions *increases +usage pattern visibility*: a separate `/boot` partition, even encrypted, +will likely leak the fact that a kernel update took place to an attacker +with access to both pre- and post-update snapshots. + +On the other hand, the downside of that method is that the root file +system can't benefit from the nice LUKS2 improvements over LUKS1, some +of which were listed above. Another (minor) downside is that space +occupied by the former `/boot` partition (typically 256MiB) becomes +unused and can't easily be reclaimed by the root file system. + +### Downgrading LUKS2 to LUKS1 ### + +Check the LUKS format version on the root device (assumed to be +`/dev/sda5` in the rest of this sub-section): + + root@debian:~# cryptsetup luksDump /dev/sda5 | grep -A1 "^LUKS" + LUKS header information + Version: 2 + +Here the LUKS format version is 2, so the device needs to be *converted* +to LUKS *version 1* to be able to unlock from GRUB. Unlike the rest of +this document, conversion can't be done on an open device, so you'll +need reboot into a live CD or an [initramfs shell]. (The `(initramfs)` +prompt strings in this sub-section indicates commands that are executed +from an initramfs shell.) Also, if you have valuable data in the root +partition, then *make sure you have a backup* (at least of the LUKS +header)! + +[initramfs shell]: https://wiki.debian.org/InitramfsDebug#Rescue_shell_.28also_known_as_initramfs_shell.29 + +Run `cryptsetup convert --type luks1 DEVICE` to downgrade. However if +the device was created with the default parameters then in-place +conversion will fail: + + (initramfs) cryptsetup convert --type luks1 /dev/sda5 + + WARNING! + ======== + This operation will convert /dev/sda5 to LUKS1 format. + + + Are you sure? (Type uppercase yes): YES + Cannot convert to LUKS1 format - keyslot 0 is not LUKS1 compatible. + +This is because its first key slot uses Argon2 as Password-Based Key +Derivation Function (PBKDF) algorithm: + + (initramfs) cryptsetup luksDump /dev/sda5 | grep "PBKDF:" + PBKDF: argon2i + +Argon2 is a *memory-hard* function that was selected as the winner of +the Password-Hashing Competition; LUKS2 devices use it by default for +key slots, but LUKS1's only supported PBKDF algorithm is PBKDF2. Hence +the key slot has to be converted to PBKDF2 prior to LUKS format version +downgrade. + + (initramfs) cryptsetup luksConvertKey --pbkdf pbkdf2 /dev/sda5 + Enter passphrase for keyslot to be converted: + +Now that all key slots use the PBKDF2 algorithm, the device shouldn't +have any LUKS2-only features left, and can be converted to LUKS1. + + (initramfs) cryptsetup luksDump /dev/sda5 | grep "PBKDF:" + PBKDF: pbkdf2 +<!-- --> + (initramfs) cryptsetup convert --type luks1 /dev/sda5 + + WARNING! + ======== + This operation will convert /dev/sda5 to LUKS1 format. + + + Are you sure? (Type uppercase yes): YES +<!-- --> + (initramfs) cryptsetup luksDump /dev/sda5 | grep -A1 "^LUKS" + LUKS header information + +### Moving `/boot` to the root file system ### + +(The moving operation can be done from the normal system. No need to +reboot into a live CD or an initramfs shell if the root file system +resides in a LUKS1 device.) + + 1. To ensure data is not modified while it's being copied, remount + `/boot` read-only. + + root@debian:~# mount -oremount,ro /boot + + 2. Recursively copy the directory to the root file system, and replace + the old `/boot` mountpoint with the new directory. + + <!-- --> + root@debian:~# cp -axT /boot /boot.tmp + <!-- --> + root@debian:~# umount /boot + <!-- --> + root@debian:~# rmdir /boot + <!-- --> + root@debian:~# mv -T /boot.tmp /boot + + (If `/boot` has sub-mountpoints, like `/boot/efi`, you'll need to + unmount them first, and then remount them once `/boot` has been + moved to the root file system.) + + 3. Comment out the [`fstab`(5)] entry for the `/boot` mountpoint. + Otherwise at reboot `init`(1) will mount it and therefore shadow data + in the new `/boot` directory with data from the old plaintext + partition. + + root@debian:~# grep /boot /etc/fstab + ## /boot was on /dev/sda1 during installation + #UUID=c104749f-a0fa-406c-9e9a-3fc01f8e2f78 /boot ext2 defaults 0 2 + + +Enabling `cryptomount` in GRUB2 +=============================== + +Enable the feature and update the GRUB image: + + root@debian:~# echo "GRUB_ENABLE_CRYPTODISK=y" >>/etc/default/grub +<!-- --> + root@debian:~# update-grub +<!-- --> + root@debian:~# grub-install /dev/sda + +If everything went well, `/boot/grub/grub.cfg` should contain `insmod +cryptodisk` (and also `insmod lvm` if `/boot` is on a Logical Volume). + +*Note*: The PBKDF parameters are determined via benchmark upon key slot +creation (or update). Thus they only makes sense if the environment in +which the LUKS device is open matches (same CPU, same RAM size, etc.) +the one in which it's been formatted. Unlocking from GRUB does count as +an environment mismatch, because GRUB operates under tighter memory +constraints and doesn't take advantage of all crypto-related CPU +instructions. Concretely, that means unlocking a LUKS device from GRUB +might take *a lot* longer than doing it from the normal system. Since +GRUB's LUKS implementation isn't able to benchmark, you'll need to do it +manually. It's easier for PBKDF2 as there is a single parameter to play +with (iteration count) — while Argon2 has two (iteration count and +memory) — and changing it affects the unlocking time linearly: for +instance halving the iteration count would speed up unlocking by a +factor of two. (And of course, making low entropy passphrases twice as +easy to brute-force. There is a trade-off to be made here. Balancing +convenience and security is the whole point of running PBKDF +benchmarks.) + + root@debian:~# cryptsetup luksDump /dev/sda1 | grep -B1 "Iterations:" + Key Slot 0: ENABLED + Iterations: 1000000 +<!-- --> + root@debian:~# cryptsetup luksChangeKey --pbkdf-force-iterations 500000 /dev/sda1 + Enter passphrase to be changed: + Enter new passphrase: + Verify passphrase: + +(You can reuse the existing passphrase in the above prompts. Replace +`/dev/sda1` with the LUKS1 volume holding `/boot`; in this document +that's `/dev/sda1` if `/boot` resides on a separated encrypted +partition, or `/dev/sda5` if `/boot` was moved to the root file system.) + +*Note*: `cryptomount` lacks an option to specify the key slot index to +open. All active key slots are tried sequentially until a match is +found. Running the PBKDF algorithm is a slow operation, so to speed up +things you'll want the key slot to unlock at GRUB stage to be the first +active one. Run the following command to discover its index. + + root@debian:~# cryptsetup luksOpen --test-passphrase --verbose /dev/sda5 + Enter passphrase for /dev/sda5: + Key slot 0 unlocked. + Command successful. + + +Avoiding the extra password prompt +================================== + +The device holding the kernel (and the initramfs image) is unlocked by +GRUB, but the root device needs to be *unlocked again* at initramfs +stage, regardless whether it's the same device or not. This is because +GRUB boots with the given `vmlinuz` and initramfs images, but there is +currently no way to securely pass cryptographic material (or Device +Mapper information) to the kernel. Hence the Device Mapper table is +initially empty at initramfs stage; in other words, all devices are +locked, and the root device needs to be unlocked again. + +To avoid extra passphrase prompts at initramfs stage, a workaround is +to *unlock via key files stored into the initramfs image*. Since the +initramfs image now resides on an encrypted device, this still provides +protection for data at rest. After all for LUK1 the volume key can +already be found by userspace in the Device Mapper table, so one could +argue that including key files to the initramfs image -- created with +restrictive permissions -- doesn't change the threat model for LUKS1 +devices. Please note however that for LUKS2 the volume key is normally +*offloaded to the kernel keyring* (hence no longer readable by +userspace), while key files lying on disk are of course readable by +userspace. + + 1. Generate the shared secret (here with 512 bits of entropy as it's also + the size of the volume key) inside a new file. + + root@debian:~# mkdir -m0700 /etc/keys + <!-- --> + root@debian:~# ( umask 0077 && dd if=/dev/urandom bs=1 count=64 of=/etc/keys/root.key conv=excl,fsync ) + 64+0 records in + 64+0 records out + 64 bytes copied, 0.000698363 s, 91.6 kB/s + + 2. Create a new key slot with that key file. + + root@debian:~# cryptsetup luksAddKey /dev/sda5 /etc/keys/root.key + Enter any existing passphrase: + <!-- --> + root@debian:~# cryptsetup luksDump /dev/sda5 | grep "^Key Slot" + Key Slot 0: ENABLED + Key Slot 1: ENABLED + Key Slot 2: DISABLED + Key Slot 3: DISABLED + Key Slot 4: DISABLED + Key Slot 5: DISABLED + Key Slot 6: DISABLED + Key Slot 7: DISABLED + + 3. Edit the [`crypttab`(5)] and set the third column to the key file path + for the root device entry. + + root@debian:~# cat /etc/crypttab + root_crypt UUID=… /etc/keys/root.key luks,discard,key-slot=1 + + The unlock logic normally runs the PBKDF algorithm through each key + slot sequentially until a match is found. Since the key file is + explicitly targeting the second key slot, its index is specified with + `key-slot=1` in the [`crypttab`(5)] to save useless expensive PBKDF + computations and *reduce boot time*. + + 4. In `/etc/cryptsetup-initramfs/conf-hook`, set `KEYFILE_PATTERN` to a + `glob`(7) expanding to the key path names to include to the initramfs + image. + + root@debian:~# echo "KEYFILE_PATTERN=\"/etc/keys/*.key\"" >>/etc/cryptsetup-initramfs/conf-hook + + 5. In `/etc/initramfs-tools/initramfs.conf`, set `UMASK` to a restrictive + value to avoid leaking key material. See [`initramfs.conf`(5)] for + details. + + root@debian:~# echo UMASK=0077 >>/etc/initramfs-tools/initramfs.conf + + 6. Finally re-generate the initramfs image, and double-check that it + 1/ has restrictive permissions; and 2/ includes the key. + + root@debian:~# update-initramfs -u + update-initramfs: Generating /boot/initrd.img-4.19.0-4-amd64 + <!-- --> + root@debian:~# stat -L -c "%A %n" /initrd.img + -rw------- /initrd.img + <!-- --> + root@debian:~# lsinitramfs /initrd.img | grep "^cryptroot/keyfiles/" + cryptroot/keyfiles/root_crypt.key + + (`cryptsetup-initramfs` normalises and renames key files inside the + initramfs, hence the new file name.) + +Should be safe to reboot now :-) If all went well you should see a +single passphrase prompt. + + +Using a custom keyboard layout +============================== + +GRUB uses the US keyboard layout by default. Alternative layouts for +the LUKS passphrase prompts can't be loaded from `/boot` or the root +file system, as the underlying devices haven't been mapped yet at that +stage. If you require another layout to type in your passphrase, then +you'll need to manually generate the core image using +[`grub-mkimage`(1)]. A possible solution is to embed a memdisk +containing the keymap inside the core image. + + 1. Create a memdisk (in GNU tar format) with the desired keymap, for + instance dvorak's. (The XKB keyboard layout and variant passed to + `grub-kbdcomp`(1) are described in the [`setxkbmap`(1)] manual.) + + root@debian:~# memdisk="$(mktemp --tmpdir --directory)" + <!-- --> + root@debian:~# grub-kbdcomp -o "$memdisk/keymap.gkb" us dvorak + <!-- --> + root@debian:~# tar -C "$memdisk" -cf /boot/grub/memdisk.tar . + + 2. Generate an early configuration file to embed inside the image. + + root@debian:~# uuid="$(blkid -o value -s UUID /dev/sda1)" + <!-- --> + root@debian:~# cat >/etc/early-grub.cfg <<-EOF + terminal_input --append at_keyboard + keymap (memdisk)/keymap.gkb + cryptomount -u ${uuid//-/} + + set root=(cryptouuid/${uuid//-/}) + set prefix=/grub + configfile grub.cfg + EOF + + *Note*: This is for the case of a separate `/boot` partition. If + `/boot` resides on the root file system, then replace `/dev/sda1` + with `/dev/sda5` (the LUKS device holding the root file system) and + set `prefix=/boot/grub`; if it's in a logical volume you'll also + [need to set][GRUB device syntax] `root=(lvm/DMNAME)`. + + *Note*: You might need to remove the first line if you use a USB + keyboard, or tweak it if GRUB doesn't see any PC/AT keyboard among its + available terminal input devices. Start by specifing `terminal_input` + in an interactive GRUB shell in order to determine the suitable input + device. (Choosing an incorrect device might prevent unlocking if no + input can be be entered.) + + 3. Finally, manually create and install the GRUB image. Don't use + `grub-install`(1) here, as we need to pass an early configuration + and a ramdisk. Instead, use [`grub-mkimage`(1)] with suitable image + file name, format, and module list. + + root@debian:~# grub-mkimage \ + -c /etc/early-grub.cfg -m /boot/grub/memdisk.tar \ + -o "$IMAGE" -O "$FORMAT" \ + diskfilter cryptodisk luks gcry_rijndael gcry_sha256 \ + memdisk tar keylayouts configfile \ + at_keyboard usb_keyboard uhci ehci \ + ahci part_msdos part_gpt lvm ext2 + + (Replace with `ahci` with a suitable module if the drive holding + `/boot` isn't a SATA drive supporting AHCI. Also, replace `ext2` + with a file system driver suitable for `/boot` if the file system + isn't ext2, ext3 or ext4.) + + The value of `IMAGE` and `FORMAT` depend on whether GRUB is in EFI + or BIOS mode. + + a. For EFI mode: `IMAGE="/boot/efi/EFI/debian/grubx64.efi"` and + `FORMAT="x86_64-efi"`. + + b. For BIOS mode: `IMAGE="/boot/grub/i386-pc/core.img"`, + `FORMAT="i386-pc"` and set up the image as follows: + + root@debian:~# grub-bios-setup -d /boot/grub/i386-pc /dev/sda + + You can now delete the memdisk and the early GRUB configuration + file, but note that subquent runs of `grub-install`(1) will override + these changes. + + +[`cryptsetup`(8)]: https://manpages.debian.org/cryptsetup.8.en.html +[`crypttab`(5)]: https://manpages.debian.org/crypttab.5.en.html +[`fstab`(5)]: https://manpages.debian.org/fstab.5.en.html +[`initramfs.conf`(5)]: https://manpages.debian.org/initramfs.conf.5.en.html +[`grub-mkimage`(1)]: https://manpages.debian.org/grub-mkimage.1.en.html +[`setxkbmap`(1)]: https://manpages.debian.org/setxkbmap.1.en.html +[GRUB device syntax]: https://www.gnu.org/software/grub/manual/grub/grub.html#Device-syntax + + -- Guilhem Moulin <guilhem@debian.org>, Sun, 09 Jun 2019 16:35:20 +0200 diff --git a/debian/doc/pandoc/index.md b/debian/doc/pandoc/index.md new file mode 100644 index 0000000..bd750c4 --- /dev/null +++ b/debian/doc/pandoc/index.md @@ -0,0 +1,24 @@ +Cryptsetup for Debian +===================== + +The main documentation: + +* [Debian Cryptsetup README](README.Debian.html) +* [Debian Cryptsetup Debugging README](README.debug.html) +* [Cryptsetup Initramfs intregration README](README.initramfs.html) + +Detailed documentation of specific setups: + +* [Debian encrypted boot documentation](encrypted-boot.html) + +Documentation of some particular keyscripts: + +* [Cryptsetup GnuPG keyscript README](README.gnupg.html) +* [Cryptsetup GnuPG smartcard keyscript README](README.gnupg-sc.html) +* [Cryptsetup keyctl keyscript README](README.keyctl.html) +* [Cryptsetup smartcard keyscript README](README.opensc.html) + + +**Please note**: Some of the documentation might be outdated. We +recommend to look at the date of the page footer. It gives an idea +about when the docs last got written and/or updated. diff --git a/debian/doc/pandoc/pandoc.css b/debian/doc/pandoc/pandoc.css new file mode 100644 index 0000000..bb66ac5 --- /dev/null +++ b/debian/doc/pandoc/pandoc.css @@ -0,0 +1,77 @@ +body { + margin: auto; + padding-right: 1em; + padding-left: 1em; + margin-left: 2em; + border-left: 1px solid black; + color: black; + font-size: 100%; + line-height: 140%; + color: #333; +} + +pre { + border: 1px dotted gray; + background-color: #ececec; + color: #1111111; + padding: 0.5em; + line-height: 1.42857143; + tab-size: 4; + -moz-tab-size: 4; +} + +code { + font-family: monospace; +} + +h1 a, h2 a, h3 a, h4 a, h5 a { + text-decoration: none; + color: #7a5ada; +} +h1, h2, h3, h4, h5 { + font-family: sans-serif; + font-weight: bold; + text-decoration: underline; + color: #7a5ada; +} +h1 { + font-size: 130%; +} +h2 { + font-size: 110%; +} +h3 { + font-size: 95%; +} +h4 { + font-size: 90%; + font-style: italic; +} +h5 { + font-size: 90%; + font-style: italic; +} +h1.title { + font-size: 200%; + font-weight: bold; + padding-top: 0.2em; + padding-bottom: 0.2em; + text-align: left; + border: none; +} + +dt code { + font-weight: bold; +} +dd p { + margin-top: 0; +} + +#TOC { + float: right; + width: 40%; + background: #eee; + font-size: 0.8em; + padding: 1em 2em; + margin: 0.0 0.5em 0.5em; +} diff --git a/debian/doc/variables.xml.in b/debian/doc/variables.xml.in new file mode 100644 index 0000000..8ca89f2 --- /dev/null +++ b/debian/doc/variables.xml.in @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd"> + +<refentry> + + <refmeta> + <refmiscinfo class="version">VERSION</refmiscinfo> + <refmiscinfo class="source">cryptsetup</refmiscinfo> + <refmiscinfo class="manual">cryptsetup manual</refmiscinfo> + </refmeta> + + <refentryinfo> + <date>DATE</date> + </refentryinfo> + +</refentry> |