summaryrefslogtreecommitdiffstats
path: root/debian/doc
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 08:06:26 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 08:06:26 +0000
commitfd888e850cf413955483bfb993aeeea5ea611289 (patch)
tree6148fed3d1f30272c48403f4cdefa59c2b7e1513 /debian/doc
parentAdding upstream version 2:2.6.1. (diff)
downloadcryptsetup-fd888e850cf413955483bfb993aeeea5ea611289.tar.xz
cryptsetup-fd888e850cf413955483bfb993aeeea5ea611289.zip
Adding debian version 2:2.6.1-4~deb12u2.debian/2%2.6.1-4_deb12u2debian
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'debian/doc')
-rw-r--r--debian/doc/cryptdisks_start.xml60
-rw-r--r--debian/doc/cryptdisks_stop.xml55
-rw-r--r--debian/doc/cryptsetup-suspend.xml120
-rw-r--r--debian/doc/crypttab.xml772
-rw-r--r--debian/doc/manpages.xml10
-rw-r--r--debian/doc/pandoc/encrypted-boot.md536
-rw-r--r--debian/doc/pandoc/index.md24
-rw-r--r--debian/doc/pandoc/pandoc.css77
-rw-r--r--debian/doc/variables.xml.in16
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>&lt;name&gt;</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>&lt;name&gt;</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
+ &lt;mejo@debian.org&gt; 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>&lt;name&gt;</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>&lt;name&gt;</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
+ &lt;mejo@debian.org&gt; 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
+ &lt;jonas@freesources.org&gt; 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=&lt;uuid&gt;</quote>
+ (resp. <quote>LABEL=&lt;label&gt;</quote>, <quote>PARTUUID=&lt;partuuid&gt;</quote>
+ and <quote>PARTLABEL=&lt;partlabel&gt;</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 [&lt;options&gt;] &lt;name&gt;</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>=&lt;cipher&gt;</term>
+ <listitem>
+ <simpara>
+ Encryption algorithm (ignored for LUKS and TCRYPT devices). See
+ <command>cryptsetup -c</command>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>size</emphasis>=&lt;size&gt;</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>=&lt;bytes&gt;</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>=&lt;hash&gt;</term>
+ <listitem>
+ <simpara>
+ Hash algorithm (ignored for LUKS and TCRYPT devices). See
+ <command>cryptsetup -h</command>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>offset</emphasis>=&lt;offset&gt;</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>=&lt;skip&gt;</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>=&lt;keyfile-offset&gt;</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>=&lt;keyfile-size&gt;</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>=&lt;slot&gt;, <emphasis>key-slot</emphasis>=&lt;slot&gt;</term>
+ <listitem>
+ <simpara>
+ Key slot (ignored for non-LUKS devices). See <command>cryptsetup
+ -S</command>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>header</emphasis>=&lt;path&gt;</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>=&lt;num&gt;</term>
+ <listitem>
+ <simpara>Try to unlock the device &lt;num&gt; 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>[=&lt;tmpfs&gt;]</term>
+ <listitem>
+ <simpara>
+ Run <command moreinfo="refentry">mkfs</command> with filesystem type
+ &lt;tmpfs&gt; (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>[=&lt;check&gt;]</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>=&lt;arguments&gt;</term>
+ <listitem>
+ <simpara>Give &lt;arguments&gt; 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>=&lt;path&gt;</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_&lt;option&gt;</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 &lt;checkargs&gt;:
+ </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 &lt;checkargs&gt;:
+ </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>