1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
<?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>
|
