Adding debian version 2:2.6.1-4~deb12u2.debian/2%2.6.1-4_deb12u2debian

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 344 insertions, 0 deletions

diff --git a/debian/README.Debian b/debian/README.Debian
new file mode 100644
index 0000000..99633bf
--- /dev/null
+++ b/debian/README.Debian
@@ -0,0 +1,344 @@
+Cryptsetup for Debian
+=====================
+
+Table of Contents
+-----------------
+
+*  1. Introduction into Cryptsetup for Debian
+*  2. Encrypted swap partition(s)
+*  3. Insecure mode/owner for keys
+*  4. Cryptsetup and udev
+*  5. Useful keyscripts: askpass and passdev
+*  6. The `check` option
+*  7. Cryptsetup and Splashy
+*  8. Remotely unlock encrypted rootfs
+*  9. Backup the LUKS header
+* 10. Changing the boot order of cryptdisks init scripts
+* 11. Unlocking LUKS devices from GRUB
+* 12. Suspend LUKS devices on system suspend
+* 13. Credits
+
+
+1. Introduction into Cryptsetup for Debian
+------------------------------------------
+
+ Cryptsetup is a command-line interface for configuring encrypted block
+devices via dm-crypt, a kernel device-mapper target. For documentation about
+the cryptsetup tool, see manpage of cryptsetup(8) and the frequently asked
+questions at `/usr/share/doc/cryptsetup/FAQ.gz`.
+
+ The Debian cryptsetup package provides the initscript `/etc/init.d/cryptdisks`
+and a configuration file `/etc/crypttab` for automatically configuring encrypted
+devices at boot time. The applications cryptdisks_start and cryptdisks_stop
+are provided to process crypttab configured devices manually. See the manpages
+of crypttab(5), cryptdisks_start(8) and cryptdisks_stop(8) for more information.
+The systemd init system masks our initscripts as it has native
+cryptsetup support; use cryptdisks_start(8) or systemd-cryptsetup@.service(8) to
+manually unlock devices on such systems.
+
+ The luksformat script provides a simple interface for creating an encrypted
+device that follows the LUKS standard and for putting a file system onto the
+encrypted device. See man luksformat(8) for more information.
+
+ If you wish to perform a Debian installation to an encrypted root, you might
+be interested in using a version of Debian Installer with partman-crypto,
+which will install the system and setup cryptsetup and initramfs-tools.
+
+ For instructions about how to encrypt your root filesystem and integrate
+cryptsetup into initramfs on a running system, see
+`/usr/share/doc/cryptsetup-initramfs/README.initramfs.gz`.
+
+
+2. Encrypted swap partition(s)
+------------------------------
+
+ An encrypted swap partition prevents spying on plaintext secrets (passwords)
+that may be written to disk when memory is swapped to disk.
+
+ To encrypt your swap partitions, you'll first have to deactivate your swap:
+
+    swapoff -a
+
+ You'll have to add an entry for every swap partition in `/etc/crypttab`. Be
+sure to place the source device (here `/dev/sde9`) with your swap devices:
+
+    # <target name> <source device> <key file>      <options>
+    cswap1          /dev/sde9       /dev/urandom    plain,cipher=aes-xts-plain64,size=256,swap
+
+ Now you need to change the swap devices in `/etc/fstab` to the encrypted swap
+device names (`/dev/mapper/cswap1` in this example).
+
+    # <file system> <mount point>   <type>  <options>     <dump>  <pass>
+    /dev/sde9        none           swap    sw            0       0
+
+becomes
+
+    # <file system> <mount point>   <type>  <options>     <dump>  <pass>
+    /dev/mapper/cswap1  none        swap    sw            0       0
+
+ Then, you need to start the cryptsetup swap devices and reactivate swap:
+
+    cryptdisks_start cswap1
+    swapon -a
+
+ And finally, if `/dev/sde9` was previously used as resume device, you should
+disable it (the new swap partition is mapped with a non-persistent key hence
+can't be used for resuming after suspend to disk).  With initramfs-tools 0.130
+and later, this can be done with
+
+    echo "RESUME=none" >/etc/initramfs-tools/conf.d/resume
+    update-initramfs -u
+
+ That's it! You have a crypted swap device. Note that `/dev/urandom` provides
+only pseudo-random entropy. So if you're paranoid rather use `/dev/random` as
+source for random data. Be aware though that `/dev/random` might not provide
+enough random bytes for your key, causing your system to hang at boot, waiting
+for more entropy. Moving mouse and keyboard typing might help in this case.
+
+ Read the crypttab(5) manpage for more information, for example options to use
+a different encryption algorithm than the default.
+
+
+3. Insecure mode/owner for keys
+-------------------------------
+
+ Any key that is stored somewhere to be used with cryptsetup should have the
+mode 400 (`-r--------`) and root as owner/group. `chown root.root keyfile` and
+`chmod 400 keyfile` will do the trick for you.
+
+ If a key is stored on a vfat filesystem (very common for removable media),
+chmod and chown will not work. The vfat filesystem (and several others too)
+does not support file permissions and ownership. Instead, you should use the
+uid, gid and umask options in `/etc/fstab` to ensure secure permissions for
+the key.
+
+ As an example, assume that `/dev/sdg8` is the removable media containing
+keyfiles on a vfat filesystem and that it is going to be mounted on
+`/media/flash0`. The configuration in `/etc/fstab` should then be something
+like this:
+
+    # <file system> <mount point>   <type>  <options>               <dump>  <pass>
+    /dev/sdg8       /media/flash0   vfat    uid=0,gid=0,umask=277   0       0
+
+ If you are using udev, it might be a good idea to use the `/dev/disk/by-label`
+links instead of `/dev/sdg8` as the link will work no matter in which order the
+media is inserted and detected.
+
+
+4. Cryptsetup and udev
+----------------------
+
+ As a workaround for some yet-to-be-fixed race condition in kernel,
+device-mapper or udev, cryptsetup currently runs udevsettle.
+
+ This leads to problems if you invoke cryptsetup as part of a udev rule.
+udevsettle waits until queued kernel/udev events are processed and the
+"run programs" have finished. Due to cryptsetup itself being a "run
+program" in this case, this ends in a deadlock.
+
+ Therefore cryptsetup should be detached directly after invocation in this
+case, so that it runs asynchronously.
+
+
+5. Useful keyscripts: askpass and passdev
+-----------------------------------------
+
+ The cryptsetup package ships with several keyscripts. Keyscripts may be
+configured in `/etc/crypttab` in order to provide the key required to unlock
+the device. The shipped keyscripts are located at `/lib/cryptsetup/scripts`.
+
+ Some keyscripts have an own README file at `/usr/share/doc/cryptsetup/`.
+
+ Two special keyscripts, worth being mentioned here, are askpass and passdev.
+
+ Askpass is located at `/lib/cryptsetup/askpass`. It's a simple helper program
+that supports different methods (console, fifo, splashy, ...) to prompt for a
+passphrase, and prints the result to stdout. The syntax is:
+
+    /lib/cryptsetup/askpass PROMPT
+
+ Passdev will wait for a given device to appear, mount it read-only, read the
+key, and unmount the device. See `/usr/share/doc/cryptsetup-initramfs/README.initramfs.gz`
+for more information about passdev.
+
+
+6. The `check` option
+---------------------
+
+ The `check` option in crypttab allows one to configure checks to be run
+against the target device after cryptsetup has been invoked.
+The default check `blkid` can check for any known filesystem type, as it uses
+blkid from util-linux. you can check for a particular filesystem by giving for
+example `checkargs=ext4` or `checkargs=swap` as an option in `/etc/crypttab`.
+
+ Please send us your checks, if you write new ones. If they are generally
+useful, we will include them in the package.
+
+ See man crypttab(5) for more information about the checksystem.
+
+
+7. Cryptsetup and Splashy
+-------------------------
+
+ Splashy support in cryptsetup is currently somehow limited. Splashy is known
+to freeze at the password dialog for encrypted non-root filesystems. Only the
+password dialog for the encrypted root filesystem works.
+
+ It seems like splashy freezes for any input dialog in initscripts while
+input dialogs at initramfs stage seem to work. This leads to the assumption
+that the bug is somewhere in splashy and neither in cryptsetups initscripts
+nor in askpass.
+
+
+8. Remotely unlock encrypted rootfs
+-----------------------------------
+
+ Thanks to Chris <debian@x.ray.net> it's possible to install a dropbear SSH
+server into the initramfs, connect to this SSH server during execution of
+initramfs early in the boot process, and unlock encrypted devices - even
+the root device - before the boot process continues. (Note that in order
+to force an arbitrary device to be processed at initramfs stage you
+might need to set the `initramfs` option in its crypttab entry; see
+crypttab(5) for details.)
+
+ This way it is possible to use an encrypted root filesystem on headless
+systems where no physical access is available during boot process.
+
+ Dropbear 0.52-1 or later is required for this to work. (Since 2015.68-1 the
+functionality has its own binary package `dropbear-initramfs`.) Consult
+`/usr/share/doc/dropbear-initramfs/README.initramfs` from the dropbear-initramfs
+package for information how to install and configure the dropbear SSH server
+into the initramfs.
+
+ You can then unlock the disk remotely via SSH with
+
+    ssh -tF ~/.luks/ssh.conf root@remote.system.com cryptroot-unlock
+
+ Or, using a local gpg-encrypted key file:
+
+    gpg --decrypt ~/.luks/remote.key.gpg | ssh -TF ~/.luks/ssh.conf root@remote.system.com cryptroot-unlock
+
+ When its standard input is a TTY, `cryptroot-unlock` keeps prompting for
+passphrases until there are no more devices to unlock; otherwise you'll
+need to invoke it as many times as there are devices to unlock.
+
+ That's it. Now that all required encrypted devices are unlocked, the
+remote system should continue with the boot process.
+
+ You can also use the following authorized_keys(5) options in
+`/etc/dropbear-initramfs/authorized_keys` to restrict access and avoid
+users poking around:
+
+    no-port-forwarding,no-agent-forwarding,no-X11-forwarding,command="/bin/cryptroot-unlock" ssh-rsa ...
+
+(Be sure to rebuild the initrd afterwards: `update-initramfs -u -k all`)
+
+
+9. Backup the LUKS header
+-------------------------
+
+ WARNING: This information might be outdated. Please read the cryptsetup FAQ
+at `/usr/share/doc/cryptsetup/FAQ.gz` for up-to-date information on how to
+backup the LUKS header.
+
+ The LUKS header is located at the beginning of every LUKS encrypted device.
+It stores information such as used cipher, hash, etc. But most importantly,
+the header contains eight keyslots, which do keep an encrypted version of the
+LUKS masterkey. the data on an encrypted LUKS partition is encrypted with this
+masterkey. thus, there's no way to restore the data once the masterkey is
+lost. For that reason, one might want to backup the LUKS header in order to
+prevent accidental data loss.
+
+ On the other hand keeping a backup of the LUKS header isn't recommended for
+security reasons. The reason is, that LUKS was designed with key revocation in
+mind. Once the LUKS header is copied to a backup, revoking a (possibly
+compromised) passphrase or keyfile from the keyslot isn't enough anymore. the
+revoked passphrase/keyfile can easily be reactived by writing back the header
+backup to the device.
+
+ Beginning with version 1.1.0, cryptsetup has support for the commands
+luksHeaderBackup and luksHeaderRestore. If you want to store a backup of your
+LUKS header with the mentioned drawbacks in mind, do the following:
+
+ Prepare a ramdisk to store the backup temporarely. You should do that in order
+to prevent any hardware caching functions or filesystem jounals to copy the
+backup around to places you cannot control. If you want to store the backup
+permanently, write it to a read-only medium like CD immediately from ramdisk,
+without your burning program writing an intermediate image to some temp dir.
+
+ To actually backup the header, use the following command:
+
+    cryptsetup luksHeaderBackup <luks-device> --header-backup-file <destination-on-ramdisk>
+
+ That's it. But once again, keep in mind all the security implications when
+doing LUKS header backups. In general it's better to backup the data from
+encrypted LUKS devices to another encrypted LUKS device. That way you can
+manage the keyslots for both original and backup device independently.
+
+
+10. Changing the boot order of cryptdisks init scripts
+-----------------------------------------------------
+
+ In order to support non-standard setups, it might be necessary to change the
+order of init scripts in the boot process. Cryptsetup already installs two
+init scripts, cryptdisks-early and cryptdisks, in order to support some complex
+setups. For example, both "lvm on luks" and "luks on lvm" are supported that
+way.
+
+ If your system isn't supported by the default order of init scripts in the
+boot process, you need to change the boot process on your own. In some cases
+it might be enough to change the LSB dependency headers at initscripts, see
+`/etc/init.d/README` for more information about that. For more complex setups,
+more intrusive changes are required. For example, adding a third cryptdisks
+init script might help. See the log of bugreport [#576646] and [discussion on
+debian-devel] for further information.
+
+[#576646]: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=576646
+[discussion on debian-devel]: https://lists.debian.org/debian-devel/2010/06/msg00021.html
+
+
+11. Unlocking LUKS devices from GRUB
+------------------------------------
+
+ GRUB has been able to unlock LUKS1 devices since early in Jessie's
+release cycle.  This feature removes the need for a separate cleartext
+`/boot` partition, hence enables "real" full disk encryption.  However
+cryptsetup >=2.1 uses LUKS version 2 by default, which GRUB 2.02 doesn't
+support.  In other words, as of Buster it is not possible to unlock from
+GRUB new LUKS devices formatted with the default parameters.
+
+ Neither Jessie nor Stretch's installers natively support unlocking from
+GRUB, hence users already had to implement various workarounds to enable
+it.  **Former workarounds won't work anymore with LUKS2**.  Integration
+between LUKS and GRUB is documented at
+<https://cryptsetup-team.pages.debian.net/cryptsetup/encrypted-boot.html>,
+including recipes to enable the feature starting from the usual
+"encrypted LVM" partitioning method of the Debian Installer -- both with
+LUKS1 (pre-Buster) and LUKS2 (Buster and later) devices.
+
+
+12. Suspend LUKS devices on system suspend
+------------------------------------------
+
+ The 'cryptsetup-suspend' package brings support to suspend encrypted
+LUKS devices before the system goes to sleep (via ACPI S3 system suspend).
+In other words, the encryption keys for LUKS devices are removed
+automatically from system memory before system suspend. After system
+resume, LUKS devices will be unlocked again and the user may be asked
+to provide a passphrase if required.
+
+ See the cryptsetup-suspend(7) manpage for more information.
+
+
+13. Credits
+-----------
+
+ People who contributed to the Debian cryptsetup package:
+
+* Guilhem Moulin <guilhem@debian.org>
+* Jonas Meurer <jonas@freesources.org>
+* David Härdeman <david@hardeman.nu>
+* Bastian Kleineidam <calvin@debian.org>
+* Michael Gebetsroither <michael.geb@gmx.at>
+
+ -- Jonas Meurer <jonas@freesources.org>, Sun, 09 Jun 2019 15:01:09 +0200