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/crypttab.xml | 717 | ||||
| -rw-r--r-- | debian/doc/manpages.xml | 9 | ||||
| -rw-r--r-- | debian/doc/pandoc/encrypted-boot.md | 353 | ||||
| -rw-r--r-- | debian/doc/pandoc/index.md | 24 | ||||
| -rw-r--r-- | debian/doc/pandoc/pandoc.css | 74 | ||||
| -rw-r--r-- | debian/doc/variables.xml.in | 16 |
8 files changed, 1308 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..429493f --- /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>cryptdisk_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/crypttab.xml b/debian/doc/crypttab.xml new file mode 100644 index 0000000..5f8c961 --- /dev/null +++ b/debian/doc/crypttab.xml @@ -0,0 +1,717 @@ +<?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 filesystems. <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. Each filesystem is + described on a separate line; fields on each line are separated by tabs or + spaces. Lines starting with <quote>#</quote> are comments, empty lines are + ignored. The order of records in <filename>crypttab</filename> is important + because the init scripts sequentially iterate through + <filename>crypttab</filename> doing their thing. + </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. Values with spaces and special + characters need to be escaped using octal sequences, like for + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + 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>, describes the cryptsetup + options associated with the encryption process. At minimum, the field should + contain either the string <emphasis>luks</emphasis> respectively + <emphasis>tcrypt</emphasis> or the <emphasis>cipher</emphasis>, + <emphasis>hash</emphasis> and <emphasis>size</emphasis> options. + Some options can be changed on active devices using + <command>cryptsetup refresh [<options>] <name></command>. + Moreover some options can be permanently written to the metada of LUKS2 + headers using the <command>--persistent</command> option flag. + </simpara> + <simpara> + Options are in the format: <emphasis>key</emphasis>=<emphasis>value</emphasis> + [,<emphasis>key</emphasis>=<emphasis>value</emphasis> …]. The + supported options are described below. + </simpara> + <simpara> + Note that all four fields are mandatory 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>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>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> on the created device. Default is ext4. + </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 removed. If a program is provided as an + argument, it is run, giving the decrypted volume (target device) as + first argument, and the value of the checkargs option as second argument. + Cryptdisks/cryptroot searches for the given program in + <filename class="directory">/lib/cryptsetup/checks/</filename> first, but + full path to program is supported as well. + </simpara> + <simpara> + Default is set in <filename>/etc/default/cryptdisks</filename> + (<filename>blkid</filename>). + </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 overwrites 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>quiet</emphasis></term> + <listitem> + <simpara>Be quiet. Don't print warnings if a device does not exist. + This option overwrites 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 output + is passed to cryptsetup as decyption key. + When used in initramfs, the executable either needs to be self-contained + (i.e. does'nt 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. + </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</term> + <listitem><para> + The target name + </para></listitem> + </varlistentry> + <varlistentry> + <term>CRYPTTAB_SOURCE</term> + <listitem><para> + The source device + </para></listitem> + </varlistentry> + <varlistentry> + <term>CRYPTTAB_KEY</term> + <listitem><para> + The key file + </para></listitem> + </varlistentry> + <varlistentry> + <term>CRYPTTAB_OPTIONS</term> + <listitem><para> + A list of exported crypttab options + </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 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 discard,cipher=aes-xts-plain64,size=256,hash=sha1,checkargs=ext4,tries=5 + +# Encrypted disk with interactive password, discard enabled +# - use a nondefault check script +# - no retries +cdisk2 /dev/sdc1 none discard,cipher=aes-xts-plain64,size=256,hash=sha1,check=customscript,tries=1 + +# Encrypted disk with interactive password, discard enabled +# - Twofish as the cipher, RIPEMD-160 as the hash +cdisk3 /dev/sda3 none dscard,cipher=twofish,size=256,hash=ripemd160 + </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> + </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..6cd361e --- /dev/null +++ b/debian/doc/manpages.xml @@ -0,0 +1,9 @@ +<?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="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..219e6ef --- /dev/null +++ b/debian/doc/pandoc/encrypted-boot.md @@ -0,0 +1,353 @@ +% 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. + +Since Jessie GRUB2 has been able to unlock LUKS devices with a new +[`cryptomount`](https://www.gnu.org/software/grub/manual/grub/html_node/cryptomount.html) +command, hence enabling encryption of the `/boot` partition as well. +(As unlocking happens before booting the kernel, that feature is not +compatible with remote unlocking.) + +Enabling unlocking LUKS devices from GRUB [isn't exposed to the d-i +interface](https://bugs.debian.org/814798) (as of Buster), hence people +have come up with various custom work-arounds. But since the Buster +release [`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. +(There is a [ticket open](https://savannah.gnu.org/bugs/?55093) in +GRUB's upstream bug tracker.) _Hence the old custom work-around won't +work anymore_. Until LUKS _version 2_ support is added to GRUB2, the +devices holding `/boot` need to be in _LUKS 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 if desired. + +These two alternatives are described in the two following sub-sections. + + +Formatting the existing `/boot` partition to LUKS1 +-------------------------------------------------- + +Since the installer creates a separate (cleartext) `/boot` partition by +default in its “encrypted LVM” partitioning method, the simplest solution +is arguably to re-format it as LUKS1. + +That way other partitions, including the one holding the root file +system, can remain in LUKS2 format and benefit from the stronger +security guaranties of the newer version: more secure (memory-hard) Key +Derivation Function, backup header, ability to offload the volume key +offload 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 in the main +system, no need to run anything from a live CD or an initramfs shell. + +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 + +Then 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 -cf /tmp/boot.tar . + root@debian:~$ umount /boot + +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 + dd: error writing '/dev/sda1': No space left on device + 244+0 records in + 243+0 records out + 254803968 bytes (255 MB, 243 MiB) copied, 1.70967 s, 149 MB/s + +Format the underlying block device to LUKS1 (note the `--type luks1` +in the command below, as Buster's [`cryptsetup`(8)] defaults to LUKS2): + + 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: + +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. + +Now 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 + […] + +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 -xf /tmp/boot.tar + +You can skip the next sub-section and go directly to [Enabling +`cryptomount` in GRUB2]. + + +Moving `/boot` to the root file system +-------------------------------------- + +The [above 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 boot from a live CD +to recover). Moreover increasing the number of partitions increases +usage pattern visibility: a separate `/boot` partitions, although +encrypted, will likely leak the fact that a kernel update took place to +an attacker with access to pre- and post-update snapshots. + +On the other hand, the inconvenient of that method is that the root file +system can't benefit from the nice LUKS2 improvements over LUKS1, as +listed above. Another minor inconvenient is that space that was +occupied by the former `/boot` partition 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/sda3` in the rest of this sub-section): + + root@debian:~$ cryptsetup luksDump /dev/sda3 | 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 remaining +of this document, the conversion can't be done on an open device, so +you'll need to use a live CD, or append `break` to the kernel +command-line to break to an initramfs shell. + +Run `cryptsetup convert --type luks1 DEVICE` to downgrade. However if +the device was created with the default parameters the in-place +conversion will fail: + + root@debian:~$ cryptsetup convert --type luks1 /dev/sda3 + + WARNING! + ======== + This operation will convert /dev/sda3 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: + + root@debian:~$ cryptsetup luksDump /dev/sda3 | 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, but +LUKS1's only supported PBKDF algorithm is PKBDF2. Hence the key slot +has to be converted to PKBDF2 prior to LUKS format version downgrade. + + root@debian:~$ cryptsetup luksChangeKey --key-slot 0 --pbkdf pbkdf2 /dev/sda3 + Enter passphrase to be changed: + Enter new passphrase: + Verify passphrase: + +(You can reuse the existing passphrase in the above prompts.) Now that +all keyslots use the PBKDF2 algorithm, the device shouldn't have any +remaining LUKS2-only features, and can be converted to LUKS1. + + root@debian:~$ cryptsetup luksDump /dev/sda3 | grep PBKDF: + PBKDF: pbkdf2 + root@debian:~$ cryptsetup convert --type luks1 /dev/sda3 + + WARNING! + ======== + This operation will convert /dev/sda3 to LUKS1 format. + + + Are you sure? (Type uppercase yes): YES + root@debian:~$ cryptsetup luksDump /dev/sda3 | grep -A1 ^LUKS + LUKS header information + +### Moving `/boot` to the root file system ### + +(The moving itself can be done from the normal system, no need to use a +live CD or an initramfs shell.) + +To ensure data is not modified while it's being copied, remount `/boot` +read-only: + + root@debian:~$ mount -oremount,ro /boot + +Then recursively copy the directory to the root file system, and replace +the old `/boot` mountpoint with the new directory. + + root@debian:~$ cp -aT /boot /boot.tmp + root@debian:~$ umount /boot + root@debian:~$ rmdir /boot + root@debian:~$ mv -T /boot.tmp /boot + +Comment out the fstab(5) entry for the `/boot` mountpoint, otherwise +at reboot `init`(1) will mount it hence shadow data in the new `/boot` +directory with data from the 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:~$ echo "GRUB_PRELOAD_MODULES=\"luks cryptodisk\"" >>/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). + + +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 currently +is 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 work around is +to unlock via key files stored into the initramfs image. Since the +initramfs image itself now resides on an encrypted device, this still +provides protection for data at rest. With LUKS1 the volume key can +already be found by userspace in the Device Mapper table, so including +key files to the initramfs image -- created with restrictive permissions -- +doesn't change the threat model. (However for LUKS2 the volume key is +offloaded to the kernel keyring by default, thus no longer accessible to +userspace, and having keyfiles readable by root slightly changes the +threat model.) + +To enable unlocking via key files for the root file system, first +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 ) + 64+0 records in + 64+0 records out + 64 bytes copied, 0.000698363 s, 91.6 kB/s + +Now create a new key slot with that key file: + + root@debian:~$ cryptsetup luksAddKey /dev/sda3 /etc/keys/root.key + Enter any existing passphrase: + + root@debian:~$ cryptsetup luksDump /dev/sda3 | 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 + +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 keyslot +sequentially until a match is found. Since the key file is explicitly +targeting the second key slot, its index can be specified with +`key-slot=1` in the [`crypttab`(5)] to save some expensive PBKDF +computations and reduce boot time.) + +In `/etc/cryptsetup-initramfs/conf-hook`, set `KEYFILE_PATTERN` to a +`glob`(7) expanding to the key files to include to the initramfs image. + + root@debian:~$ echo "KEYFILE_PATTERN=\"/etc/keys/*.key\"" >>/etc/cryptsetup-initramfs/conf-hook + +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 + +Finally re-generate the initramfs image, and double-check that it has +restrictive permissions and 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 keyfile name.) + +Should be safe to reboot now :-) If all went well you should see a +single passphrase prompt. + +[`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 + + -- Guilhem Moulin <guilhem@debian.org>, Mon, 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..b2289e7 --- /dev/null +++ b/debian/doc/pandoc/pandoc.css @@ -0,0 +1,74 @@ +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; +} + +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> |