120 lines
4.6 KiB
XML
120 lines
4.6 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd">
|
|
|
|
<refentry id="overview.cryptsetup-suspend">
|
|
|
|
<xi:include href="variables.xml"
|
|
xpointer="xpointer(/refentry/refentryinfo)"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
|
|
|
<refmeta>
|
|
<refentrytitle>cryptsetup-suspend</refentrytitle>
|
|
<manvolnum>7</manvolnum>
|
|
<xi:include href="variables.xml"
|
|
xpointer="xpointer(/refentry/refmeta/*)"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>cryptsetup-suspend</refname>
|
|
<refpurpose>automatically suspend LUKS devices on system suspend</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 id="cryptsetup-suspend.description">
|
|
<title>DESCRIPTION</title>
|
|
<simpara>
|
|
<emphasis>cryptsetup-suspend</emphasis> 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
|
|
<emphasis>cryptsetup-suspend</emphasis> package. No further configuration
|
|
is required.
|
|
</simpara>
|
|
<simpara>
|
|
<emphasis>cryptsetup-suspend</emphasis> supports all setups of LUKS
|
|
devices that are supported by the <emphasis>cryptsetup</emphasis>
|
|
packages. To do so, it depends on scripts from the Debian package
|
|
<emphasis>cryptsetup-initramfs</emphasis>. See the
|
|
<reference>INTERNALS</reference> section about details on how it works.
|
|
</simpara>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cryptsetup-suspend.security-aspects">
|
|
<title>SECURITY ASPECTS</title>
|
|
<simpara>
|
|
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.
|
|
</simpara>
|
|
<simpara>
|
|
<emphasis>cryptsetup-suspend</emphasis> protects <emphasis>only</emphasis>
|
|
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.
|
|
</simpara>
|
|
<simpara>
|
|
The initramfs image is extracted in memory and left unencrypted (see the
|
|
<reference>INTERNALS</reference> section) so all key material it might
|
|
include, for instance key files copied using the hooks'
|
|
<emphasis>KEYFILE_PATTERN=</emphasis> option, will remain unprotected.
|
|
</simpara>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1 id="cryptsetup-suspend.limitations">
|
|
<title>LIMITATIONS</title>
|
|
<simpara>
|
|
The <emphasis>cryptsetup-suspend</emphasis> feature is limited to LUKS
|
|
devices and doesn't work with <emphasis>plain dm-crypt</emphasis> or
|
|
<emphasis>tcrypt</emphasis> devices.
|
|
</simpara>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cryptsetup-suspend.internals">
|
|
<title>INTERNALS</title>
|
|
<simpara>
|
|
<emphasis>cryptsetup-suspend</emphasis> consists of three parts:
|
|
<simplelist type="inline">
|
|
<member>
|
|
<command>cryptsetup-suspend</command>: A c program that takes a list
|
|
of LUKS devices as arguments, suspends them via
|
|
<emphasis>luksSuspend</emphasis> and suspends the system afterwards.
|
|
</member>
|
|
<member>
|
|
<command>cryptsetup-suspend-wrapper</command>: A shell wrapper script
|
|
which works the following way:
|
|
<simplelist type="inline">
|
|
<member>1. Disable swap and extract the initramfs into a tmpfs (the chroot)</member>
|
|
<member>2. Run (systemd) pre-suspend scripts, stop udev, freeze cgroups</member>
|
|
<member>3. run cryptsetup-suspend in chroot</member>
|
|
<member>4. resume initramfs devices inside chroot after resume</member>
|
|
<member>5. resume non-initramfs devices outside chroot</member>
|
|
<member>6. thaw groups, start udev, run (systemd) post-suspend scripts</member>
|
|
<member>7. Unmount the tmpfs and re-enable swap</member>
|
|
</simplelist>
|
|
</member>
|
|
<member>
|
|
A systemd unit drop-in file that overrides the Exec property of
|
|
<filename class="devicefile">systemd-suspend.service</filename> so that
|
|
it invokes the script <command>cryptsetup-suspend-wrapper</command>.
|
|
</member>
|
|
</simplelist>
|
|
</simpara>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cryptsetup-suspend.see_also">
|
|
<title>SEE ALSO</title>
|
|
<simpara>
|
|
<emphasis>cryptsetup</emphasis>(8), <emphasis>crypttab</emphasis>(5)
|
|
</simpara>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cryptsetup-suspend.author">
|
|
<title>AUTHOR</title><simpara>This manual page was written by Jonas Meurer
|
|
<jonas@freesources.org> in December 2019.
|
|
</simpara>
|
|
</refsect1>
|
|
|
|
</refentry>
|