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.