oracular (7) cryptsetup-suspend.7.gz

Provided by: cryptsetup-suspend_2.7.2-2ubuntu1_amd64 bug

NAME
       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)


AUTHOR
       This manual page was written by Jonas Meurer <jonas@freesources.org> in December 2019.