Debian Codegraph @

upstream/debian-unstable/man8/systemd-cryptsetup.8

raw
1 '\" t
2 .TH "SYSTEMD\-CRYPTSETUP" "8" "" "systemd 261~rc3" "systemd-cryptsetup"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-cryptsetup, [email protected] \- Full disk decryption logic
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-cryptsetup\fR\ 'u
26 \fBsystemd\-cryptsetup\fR [OPTIONS...] attach VOLUME SOURCE\-DEVICE [KEY\-FILE] [CRYPTTAB\-OPTIONS]
27 .HP \w'\fBsystemd\-cryptsetup\fR\ 'u
28 \fBsystemd\-cryptsetup\fR [OPTIONS...] detach VOLUME
29 .PP
30 systemd\-cryptsetup@\&.service
31 .PP
32 system\-systemd\ex2dcryptsetup\&.slice
33 .SH "DESCRIPTION"
34 .PP
35 \fBsystemd\-cryptsetup\fR
36 is used to set up (with
37 \fBattach\fR) and tear down (with
38 \fBdetach\fR) access to an encrypted block device\&. It is primarily used via
39 systemd\-cryptsetup@\&.service
40 during early boot, but may also be called manually\&. The positional arguments
41 \fIVOLUME\fR,
42 \fISOURCE\-DEVICE\fR,
43 \fIKEY\-FILE\fR, and
44 \fICRYPTTAB\-OPTIONS\fR
45 have the same meaning as the fields in
46 \fBcrypttab\fR(5)\&.
47 .PP
48 systemd\-cryptsetup@\&.service
49 is a service responsible for providing access to encrypted block devices\&. It is instantiated for each device that requires decryption\&.
50 .PP
51 systemd\-cryptsetup@\&.service
52 instances are part of the
53 system\-systemd\ex2dcryptsetup\&.slice
54 slice, which is destroyed only very late in the shutdown procedure\&. This allows the encrypted devices to remain up until filesystems have been unmounted\&.
55 .PP
56 systemd\-cryptsetup@\&.service
57 will ask for hard disk passwords via the
58 \m[blue]\fBpassword agent logic\fR\m[]\&\s-2\u[1]\d\s+2, in order to query the user for the password using the right mechanism at boot and during runtime\&.
59 .PP
60 At early boot and when the system manager configuration is reloaded,
61 /etc/crypttab
62 is translated into
63 systemd\-cryptsetup@\&.service
64 units by
65 \fBsystemd-cryptsetup-generator\fR(8)\&.
66 .PP
67 In order to unlock a volume a password or binary key is required\&.
68 systemd\-cryptsetup@\&.service
69 tries to acquire a suitable password or binary key via the following mechanisms, tried in order:
70 .sp
71 .RS 4
72 .ie n \{\
73 \h'-04' 1.\h'+01'\c
74 .\}
75 .el \{\
76 .sp -1
77 .IP " 1." 4.2
78 .\}
79 If a key file is explicitly configured (via the third column in
80 /etc/crypttab), a key read from it is used\&. If a PKCS#11 token, FIDO2 token or TPM2 device is configured (using the
81 \fIpkcs11\-uri=\fR,
82 \fIfido2\-device=\fR,
83 \fItpm2\-device=\fR
84 options) the key is decrypted before use\&.
85 .RE
86 .sp
87 .RS 4
88 .ie n \{\
89 \h'-04' 2.\h'+01'\c
90 .\}
91 .el \{\
92 .sp -1
93 .IP " 2." 4.2
94 .\}
95 If no key file is configured explicitly this way, a key file is automatically loaded from
96 /etc/cryptsetup\-keys\&.d/\fIvolume\fR\&.key
97 and
98 /run/cryptsetup\-keys\&.d/\fIvolume\fR\&.key, if present\&. Here too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before use\&.
99 .RE
100 .sp
101 .RS 4
102 .ie n \{\
103 \h'-04' 3.\h'+01'\c
104 .\}
105 .el \{\
106 .sp -1
107 .IP " 3." 4.2
108 .\}
109 If the
110 \fItry\-empty\-password\fR
111 option is specified then unlocking the volume with an empty password is attempted\&.
112 .RE
113 .sp
114 .RS 4
115 .ie n \{\
116 \h'-04' 4.\h'+01'\c
117 .\}
118 .el \{\
119 .sp -1
120 .IP " 4." 4.2
121 .\}
122 If the
123 \fIpassword\-cache=\fR
124 option is set to
125 "yes"
126 or
127 "read\-only", the kernel keyring is then checked for a suitable cached password from previous attempts\&.
128 .RE
129 .sp
130 .RS 4
131 .ie n \{\
132 \h'-04' 5.\h'+01'\c
133 .\}
134 .el \{\
135 .sp -1
136 .IP " 5." 4.2
137 .\}
138 Finally, the user is queried for a password, possibly multiple times, unless the
139 \fIheadless\fR
140 option is set\&.
141 .RE
142 .PP
143 If no suitable key may be acquired via any of the mechanisms describes above, volume activation fails\&.
144 .SH "CREDENTIALS"
145 .PP
146 \fBsystemd\-cryptsetup\fR
147 supports the service credentials logic as implemented by
148 \fIImportCredential=\fR/\fILoadCredential=\fR/\fISetCredential=\fR
149 (see
150 \fBsystemd.exec\fR(5)
151 for details)\&. The following credentials are used by
152 "systemd\-crypsetup@root\&.service"
153 (generated by
154 \fBsystemd\-gpt\-auto\-generator\fR) when passed in:
155 .PP
156 \fIcryptsetup\&.passphrase\fR
157 .RS 4
158 This credential specifies the passphrase of the LUKS volume\&.
159 .sp
160 Added in version 256\&.
161 .RE
162 .PP
163 \fIcryptsetup\&.tpm2\-pin\fR
164 .RS 4
165 This credential specifies the TPM pin\&.
166 .sp
167 Added in version 256\&.
168 .RE
169 .PP
170 \fIcryptsetup\&.fido2\-pin\fR
171 .RS 4
172 This credential specifies the FIDO2 token pin\&.
173 .sp
174 Added in version 256\&.
175 .RE
176 .PP
177 \fIcryptsetup\&.pkcs11\-pin\fR
178 .RS 4
179 This credential specifies the PKCS11 token pin\&.
180 .sp
181 Added in version 256\&.
182 .RE
183 .PP
184 \fIcryptsetup\&.luks2\-pin\fR
185 .RS 4
186 This credential specifies the pin requested by generic LUKS2 token modules\&.
187 .sp
188 Added in version 256\&.
189 .RE
190 .SH "SEE ALSO"
191 .PP
192 \fBsystemd\fR(1), \fBsystemd-cryptsetup-generator\fR(8), \fBcrypttab\fR(5), \fBsystemd-cryptenroll\fR(1), \fBcryptsetup\fR(8), \m[blue]\fBTPM2 PCR Measurements Made by systemd\fR\m[]\&\s-2\u[2]\d\s+2
193 .SH "NOTES"
194 .IP " 1." 4
195 password agent logic
196 .RS 4
197 \%https://systemd.io/PASSWORD_AGENTS/
198 .RE
199 .IP " 2." 4
200 TPM2 PCR Measurements Made by systemd
201 .RS 4
202 \%https://systemd.io/TPM2_PCR_MEASUREMENTS
203 .RE