From fd888e850cf413955483bfb993aeeea5ea611289 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 17 Apr 2024 10:06:26 +0200 Subject: Adding debian version 2:2.6.1-4~deb12u2. Signed-off-by: Daniel Baumann --- debian/doc/cryptdisks_start.xml | 60 +++ debian/doc/cryptdisks_stop.xml | 55 +++ debian/doc/cryptsetup-suspend.xml | 120 ++++++ debian/doc/crypttab.xml | 772 ++++++++++++++++++++++++++++++++++++ debian/doc/manpages.xml | 10 + debian/doc/pandoc/encrypted-boot.md | 536 +++++++++++++++++++++++++ debian/doc/pandoc/index.md | 24 ++ debian/doc/pandoc/pandoc.css | 77 ++++ debian/doc/variables.xml.in | 16 + 9 files changed, 1670 insertions(+) create mode 100644 debian/doc/cryptdisks_start.xml create mode 100644 debian/doc/cryptdisks_stop.xml create mode 100644 debian/doc/cryptsetup-suspend.xml create mode 100644 debian/doc/crypttab.xml create mode 100644 debian/doc/manpages.xml create mode 100644 debian/doc/pandoc/encrypted-boot.md create mode 100644 debian/doc/pandoc/index.md create mode 100644 debian/doc/pandoc/pandoc.css create mode 100644 debian/doc/variables.xml.in (limited to 'debian/doc') 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 @@ + + + + + + + + + cryptdisks_start + 8 + + + + + cryptdisks_start + wrapper around cryptsetup that parses /etc/crypttab. + + + + + cryptdisks_start + <name> + + + + + DESCRIPTION + + cryptdisks_start is a wrapper around + cryptsetup that parses + /etc/crypttab just like the initscript + /etc/init.d/cryptdisks does and starts the dm-crypt mapping that + corresponds to <name>. + + + Note that this wrapper passes to + cryptsetup, so the passphrase + in any referenced key file must not be followed by a newline character. + + + + + SEE ALSO + + cryptdisks_stop(8), + cryptsetup(8), crypttab(5) + + + + + AUTHORThis manual page was written by Jonas Meurer + <mejo@debian.org> in December 2007. + + + + 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 @@ + + + + + + + + + cryptdisks_stop + 8 + + + + + cryptdisks_stop + wrapper around cryptsetup that parses /etc/crypttab. + + + + + cryptdisks_stop + <name> + + + + + DESCRIPTION + + cryptdisks_stop is a wrapper around + cryptsetup that parses + /etc/crypttab just like the initscript + /etc/init.d/cryptdisks does and stops the dm-crypt mapping that corresponds + to <name>. + + + + + SEE ALSO + + cryptdisks_start(8), + cryptsetup(8), crypttab(5) + + + + + AUTHORThis manual page was written by Jonas Meurer + <mejo@debian.org> in January 2008. + + + + 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 @@ + + + + + + + + + cryptsetup-suspend + 7 + + + + + cryptsetup-suspend + automatically suspend LUKS devices on system suspend + + + + DESCRIPTION + + cryptsetup-suspend 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 + cryptsetup-suspend package. No further configuration + is required. + + + cryptsetup-suspend supports all setups of LUKS + devices that are supported by the cryptsetup + packages. To do so, it depends on scripts from the Debian package + cryptsetup-initramfs. See the + INTERNALS section about details on how it works. + + + + + SECURITY ASPECTS + + 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. + + + cryptsetup-suspend protects only + 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. + + + The initramfs image is extracted in memory and left unencrypted (see the + INTERNALS section) so all key material it might + include, for instance key files copied using the hooks' + KEYFILE_PATTERN= option, will remain unprotected. + + + + + + LIMITATIONS + + The cryptsetup-suspend feature is limited to LUKS + devices and doesn't work with plain dm-crypt or + tcrypt devices. + + + + + INTERNALS + + cryptsetup-suspend consists of three parts: + + + cryptsetup-suspend: A c program that takes a list + of LUKS devices as arguments, suspends them via + luksSuspend and suspends the system afterwards. + + + cryptsetup-suspend-wrapper: A shell wrapper script + which works the following way: + + 1. Disable swap and extract the initramfs into a tmpfs (the chroot) + 2. Run (systemd) pre-suspend scripts, stop udev, freeze cgroups + 3. run cryptsetup-suspend in chroot + 4. resume initramfs devices inside chroot after resume + 5. resume non-initramfs devices outside chroot + 6. thaw groups, start udev, run (systemd) post-suspend scripts + 7. Unmount the tmpfs and re-enable swap + + + + A systemd unit drop-in file that overrides the Exec property of + systemd-suspend.service so that + it invokes the script cryptsetup-suspend-wrapper. + + + + + + + SEE ALSO + + cryptsetup(8), crypttab(5) + + + + + AUTHORThis manual page was written by Jonas Meurer + <jonas@freesources.org> in December 2019. + + + + 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 @@ + + + + + + + + + crypttab + 5 + + + + + crypttab + static information about encrypted filesystems + + + + DESCRIPTION + + The file /etc/crypttab contains descriptive + information about encrypted devices. crypttab + is only read by programs (e.g. + cryptdisks_start and + cryptdisks_stop), + and not written; it is the duty of the system + administrator to properly create and maintain this file. + crypttab entries are treated sequentially, so their + order matters (dependencies need to listed first). + + + 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 \0num 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. + + + The first field, target, 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 source + device will be created at + /dev/mapper/target by + cryptsetup. + + + The second field, source device, describes either the + block special device or file that contains the encrypted data. Instead of + giving the source device explicitly, the UUID + (resp. LABEL, PARTUUID and PARTLABEL) is supported as well, using UUID=<uuid> + (resp. LABEL=<label>, PARTUUID=<partuuid> + and PARTLABEL=<partlabel>). + + + The third field, key file, describes the file to use + as a key for decrypting the data of the source device. + In case of a keyscript, the value of this field is + given as argument to the keyscript. + Note that the entire key file will be used as the + passphrase; the passphrase must not be followed by a + newline character. + + + It can also be a device name (e.g. + /dev/urandom), note however that + LUKS requires a persistent key and therefore does not + support random data keys. + + + If the key file is the string + none, a passphrase will be read interactively from the + console. In this case, the options check, checkargs and tries may be + useful. + + + The fourth field, options, is an optional comma-separated + list of options and/or flags describing the device type (luks, + tcrypt, bitlk, fvault2, + or plain 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 cipher, hash + and size options are required. + Some options can be changed on active mappings using + cryptsetup refresh [<options>] <name>. + Furthermore some options can be permanently written into metadata of LUKS2 + headers using cryptsetup's --persistent flag. + + + Note that the first three fields are required and that a missing field will lead + to unspecified behaviour. + + + + + ON DIFFERENT CRYPTTAB FORMATS + + Please note that there are several independent cryptsetup wrappers with + their own crypttab format. This manpage covers + Debian's implementation for initramfs scripts and + SysVinit init scripts. systemd + brings its own crypttab implementation. + We try to cover the differences between the systemd and + our implementation in this manpage, but if in doubt, better check the + systemd + crypttab5 + manpage, e.g. online at + . + + + + + OPTIONS + + + + cipher=<cipher> + + + Encryption algorithm (ignored for LUKS and TCRYPT devices). See + cryptsetup -c. + + + + + + size=<size> + + + Encryption key size (ignored for LUKS and TCRYPT devices). See + cryptsetup -s. + + + + + + sector-size=<bytes> + + + Sector size. See + cryptsetup8 + for possible values and the default value of this option. + + + + + + hash=<hash> + + + Hash algorithm (ignored for LUKS and TCRYPT devices). See + cryptsetup -h. + + + + + + offset=<offset> + + + Start offset (ignored for LUKS and TCRYPT devices). Uses + cryptsetup -o. + + + + + + skip=<skip> + + + Skip sectors at the beginning (ignored for LUKS and TCRYPT devices). + Uses cryptsetup -p. + + + + + + keyfile-offset=<keyfile-offset> + + + Specifies the number of bytes to skip at the start of the key file. + + + + + + keyfile-size=<keyfile-size> + + + 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 cryptsetup --help. + This option is ignored for plain dm-crypt devices, as the key file + size is then given by the encryption key size (option + size). + + + + + + keyslot=<slot>, key-slot=<slot> + + + Key slot (ignored for non-LUKS devices). See cryptsetup + -S. + + + + + + header=<path> + + + Detached header file (ignored for plain dm-crypt devices). See + cryptsetup --header. + + + + + + verify + + + Verify password. Uses cryptsetup -y. + + + + + + readonly, read-only + + Set up a read-only mapping. + + + + + tries=<num> + + Try to unlock the device <num> before failing. It's + particularly useful when using a passphrase or a + keyscript that asks for interactive input. If you + want to disable retries, pass tries=1. Default is + 3. Setting tries=0 means infinitive + retries. + + + + + + discard + + Allow using of discards (TRIM) requests for device. + 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. + WARNING: 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. + + + + + luks + + Force LUKS mode. When this mode is used, the following options + are ignored since they are provided by the LUKS header on the device: + cipher=, hash=, + size= + + + + + plain + + Force plain encryption mode. + + + + + bitlk + + + Force BITLK (Windows BitLocker-compatible) mode. + WARNING: crypttab support is currently experimental. + + + + + + fvault2 + + + 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. + + + + + + tcrypt + + 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: cipher=, + hash=, keyfile-offset=, + keyfile-size=, size= + + + + + veracrypt, tcrypt-veracrypt + + + Use VeraCrypt extension to TrueCrypt device. Only useful in + conjunction with tcrypt option (ignored for + non-TrueCrypt devices). + + + + + + tcrypthidden, tcrypt-hidden + + + Use hidden TCRYPT header (ignored for non-TCRYPT devices). + + + + + + same-cpu-crypt + + + Perform encryption using the same cpu that IO was submitted on. + + + + + + submit-from-crypt-cpus + + + Disable offloading writes to a separate thread after encryption. + + + + + + no-read-workqueue, no-write-workqueue + + + Bypass dm-crypt internal workqueue and process read or write requests synchronously. + + + + + + swap + + + Run mkswap on the created device. + + + This option is ignored for initramfs devices. + + + + + + tmp[=<tmpfs>] + + + Run mkfs with filesystem type + <tmpfs> (or ext4 if omitted) on the created device. + + + This option is ignored for initramfs devices. + + + + + + check[=<check>] + + 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 checkargs option is used, its value as second + argument. See the CHECKSCRIPTS section for more information. + + The program is either specified by full path or relative to + /lib/cryptsetup/checks/. + If omitted, then the value of $CRYPTDISKS_CHECK set in + /etc/default/cryptdisks is used + (blkid by default). + + + This option is specific to the Debian crypttab + format. It's not supported by systemd. + + + + + + checkargs=<arguments> + + Give <arguments> as the second argument to the check + script. See the CHECKSCRIPTS section for more information. + + + + This option is specific to the Debian crypttab + format. It's not supported by systemd. + + + + + initramfs + + The initramfs hook processes the root device, any resume devices + and any devices with the initramfs option set. These + devices are processed within the initramfs stage of boot. As an example, + that allows the use of remote unlocking using dropbear. + + + This option is specific to the Debian crypttab + format. It's not supported by systemd. + + + + + + noearly + + 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. + + + This option is ignored for initramfs devices and + specific to the Debian crypttab format. It's not + supported by systemd. + + + + + + noauto + + Entirely ignore the device at the boot process. It's still + possible to map the device manually using cryptdisks_start. + + + This option is ignored for initramfs devices and + specific to the Debian crypttab format. It's not + supported by systemd. + + + + + + loud + + Be loud. Print warnings if a device does not exist. + This option overrides the option quiet. + + This option is ignored for initramfs devices and + specific to the Debian crypttab format. It's not + supported by systemd. + + + + + + quiet + + Be quiet. Don't print warnings if a device does not exist. + This option overrides the option loud. + + This option is ignored for initramfs devices and + specific to the Debian crypttab format. It's not + supported by systemd. + + + + + + keyscript=<path> + + + The executable at the indicated path is executed with the value of the + third field 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 + /lib/cryptsetup/scripts/. + + + 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. + + + This option is specific to the Debian crypttab + format. It's not supported by systemd. + + + 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. + + + All fields of the appropriate crypttab entry are available to the + keyscript as exported environment variables: + + + + CRYPTTAB_NAME, _CRYPTTAB_NAME + + The target name (after resp. before octal sequence decoding). + + + + CRYPTTAB_SOURCE, _CRYPTTAB_SOURCE + + The source device (after resp. before octal sequence decoding and device resolution). + + + + CRYPTTAB_KEY, _CRYPTTAB_KEY + + The value of the third field (after resp. before octal sequence decoding). + + + + CRYPTTAB_OPTIONS, _CRYPTTAB_OPTIONS + + A list of exported crypttab options (after resp. before octal sequence decoding). + + + + CRYPTTAB_OPTION_<option> + + 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. + + + + CRYPTTAB_TRIED + + Number of previous tries since start of cryptdisks (counts until + maximum number of tries is reached). + + + + + + + + + + + + + CHECKSCRIPTS + + + + blkid + + Checks for any known filesystem. Supports a filesystem type as + argument via <checkargs>: + + + + no checkargs - succeeds if any valid filesystem is found on the device. + + + "none" - succeeds if no valid filesystem is found on the device. + + + "ext4" [or another filesystem type like xfs, swap, crypto_LUKS, ...] - + succeeds if ext4 filesystem is found on the device. + + + + + + + un_blkid + + Checks for no known filesystem. Supports a filesystem type as + argument via <checkargs>: + + + + no checkargs - succeeds if no valid filesystem is found on the device. + + + "ext4" [or another filesystem type like xfs, swap, crypto_LUKS, ...] - + succeeds if no ext4 filesystem is found on the device. + + + + + + + + + + EXAMPLES + + +# 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 + + + + + + ENVIRONMENT + + + + CRYPTDISKS_ENABLE + + + Set to yes to run cryptdisks initscripts at startup. + Set to no to disable cryptdisks initscripts. Default + is yes. + + + + + + CRYPTDISKS_MOUNT + + 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. + + + + + + CRYPTDISKS_CHECK + + 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 + check option is given in crypttab with no value. See + documentation for check option above for more + information. + + + + + + + + + KNOWN UPGRADE ISSUES + + 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 /etc/crypttab. 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 + /etc/crypttab for plain dm-crypt devices, even if they + match the current default. + + + + + SEE ALSO + + cryptsetup(8) + cryptdisks_start(8) + cryptdisks_stop(8) + /usr/share/doc/cryptsetup-initramfs/README.initramfs.gz + + + + + AUTHOR + + This manual page was originally written by + + Bastian + Kleineidam + + calvin@debian.org + for the Debian distribution of cryptsetup. It has been further improved by + + Michael + Gebetsroither + + michael.geb@gmx.at, + + David + Härdeman + + david@hardeman.nu + and + + Jonas + Meurer + + jonas@freesources.org. + + + + 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 @@ + + + + + Manual Pages + + + + + 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 , 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 @@ + + + + + + + VERSION + cryptsetup + cryptsetup manual + + + + DATE + + + -- cgit v1.2.3