'\" t
.\"     Title: cryptsetup-suspend
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024-04-14
.\"    Manual: cryptsetup manual
.\"    Source: cryptsetup 2:2.7.2-2
.\"  Language: English
.\"
.TH "CRYPTSETUP\-SUSPEND" "7" "2024\-04\-14" "cryptsetup 2:2\&.7\&.2\-2" "cryptsetup manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
cryptsetup-suspend \- automatically suspend LUKS devices on system suspend
.SH "DESCRIPTION"
.sp
\fIcryptsetup\-suspend\fR 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 \fIcryptsetup\-suspend\fR package\&. No further configuration is required\&.
.sp
\fIcryptsetup\-suspend\fR supports all setups of LUKS devices that are supported by the \fIcryptsetup\fR packages\&. To do so, it depends on scripts from the Debian package \fIcryptsetup\-initramfs\fR\&. See the INTERNALS section about details on how it works\&.
.SH "SECURITY ASPECTS"
.sp
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\&.
.sp
\fIcryptsetup\-suspend\fR protects \fIonly\fR the encryption keys of your LUKS devices against being read from the memory\&. Most likely there\*(Aqs 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\&.
.sp
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\*(Aq \fIKEYFILE_PATTERN=\fR option, will remain unprotected\&.
.SH "LIMITATIONS"
.sp
The \fIcryptsetup\-suspend\fR feature is limited to LUKS devices and doesn\*(Aqt work with \fIplain dm\-crypt\fR or \fItcrypt\fR devices\&.
.SH "INTERNALS"
.sp
\fIcryptsetup\-suspend\fR consists of three parts: \fBcryptsetup\-suspend\fR: A c program that takes a list of LUKS devices as arguments, suspends them via \fIluksSuspend\fR and suspends the system afterwards\&. , \fBcryptsetup\-suspend\-wrapper\fR: 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 \fBcryptsetup\-suspend\-wrapper\fR\&.
.SH "SEE ALSO"
.sp
\fIcryptsetup\fR(8), \fIcrypttab\fR(5)
.SH "AUTHOR"
.sp
This manual page was written by Jonas Meurer <jonas@freesources\&.org> in December 2019\&.