1SYSTEMD-CRYPTENROLL(1) systemd-cryptenroll SYSTEMD-CRYPTENROLL(1)
2
6 systemd-cryptenroll - Enroll PKCS#11, FIDO2, TPM2 token/devices to
7 LUKS2 encrypted volumes
8
10 systemd-cryptenroll [OPTIONS...] [DEVICE]
11
13 systemd-cryptenroll is a tool for enrolling hardware security tokens
14 and devices into a LUKS2 encrypted volume, which may then be used to
15 unlock the volume during boot. Specifically, it supports tokens and
16 credentials of the following kind to be enrolled:
17 1. PKCS#11 security tokens and smartcards that may carry an RSA key
19 pair (e.g. various YubiKeys)
20 2. FIDO2 security tokens that implement the "hmac-secret" extension
22 (most FIDO2 keys, including YubiKeys)
23 3. TPM2 security devices
25 4. Regular passphrases
27 5. Recovery keys. These are similar to regular passphrases, however
29 are randomly generated on the computer and thus generally have
30 higher entropy than user-chosen passphrases. Their character set
31 has been designed to ensure they are easy to type in, while having
32 high entropy. They may also be scanned off screen using QR codes.
33 Recovery keys may be used for unlocking LUKS2 volumes wherever
34 passphrases are accepted. They are intended to be used in
35 combination with an enrolled hardware security token, as a recovery
36 option when the token is lost.
37 In addition, the tool may be used to enumerate currently enrolled
39 security tokens and wipe a subset of them. The latter may be combined
40 with the enrollment operation of a new security token, in order to
41 update or replace enrollments.
42 The tool supports only LUKS2 volumes, as it stores token
44 meta-information in the LUKS2 JSON token area, which is not available
45 in other encryption formats.
46
48 Note that currently when enrolling a new key of one of the five
49 supported types listed above, it is required to first provide a
50 passphrase, a recovery key or a FIDO2 token. It's currently not
51 supported to unlock a device with a TPM2/PKCS#11 key in order to enroll
52 a new TPM2/PKCS#11 key. Thus, if in future key roll-over is desired
53 it's generally recommended to ensure a passphrase, a recovery key or a
54 FIDO2 token is always enrolled.
55 Also note that support for enrolling multiple FIDO2 tokens is currently
57 limited. When multiple FIDO2 tokens are enrolled, systemd-cryptseup
58 will perform pre-flight requests to attempt to identify which of the
59 enrolled tokens are currently plugged in. However, this is not possible
60 for FIDO2 tokens with user verification (UV, usually via biometrics),
61 in which case it will fall back to attempting each enrolled token one
62 by one. This will result in multiple prompts for PIN and user
63 verification. This limitation does not apply to PKCS#11 tokens.
64
66 Security technology both in systemd and in the general industry
67 constantly evolves. In order to provide best security guarantees, the
68 way TPM2, FIDO2, PKCS#11 devices are enrolled is regularly updated in
69 newer versions of systemd. Whenever this happens the following
70 compatibility guarantees are given:
71 • Old enrollments continue to be supported and may be unlocked with
73 newer versions of systemd-cryptsetup@.service(8).
74 • The opposite is not guaranteed however: it might not be possible to
76 unlock volumes with enrollments done with a newer version of
77 systemd-cryptenroll with an older version of systemd-cryptsetup.
78 That said, it is generally recommended to use matching versions of
80 systemd-cryptenroll and systemd-cryptsetup, since this is best tested
81 and supported.
82 It might be advisable to re-enroll existing enrollments to take benefit
84 of newer security features, as they are added to systemd.
85
87 The following options are understood:
88 --password
90 Enroll a regular password/passphrase. This command is mostly
91 equivalent to cryptsetup luksAddKey, however may be combined with
92 --wipe-slot= in one call, see below.
93 --recovery-key
95 Enroll a recovery key. Recovery keys are mostly identical to
96 passphrases, but are computer-generated instead of being chosen by
97 a human, and thus have a guaranteed high entropy. The key uses a
98 character set that is easy to type in, and may be scanned off
99 screen via a QR code.
100 --unlock-key-file=PATH
102 Use a file instead of a password/passphrase read from stdin to
103 unlock the volume. Expects the PATH to the file containing your key
104 to unlock the volume. Currently there is nothing like
105 --key-file-offset= or --key-file-size= so this file has to only
106 contain the full key.
107 --unlock-fido2-device=PATH
109 Use a FIDO2 device instead of a password/passphrase read from stdin
110 to unlock the volume. Expects a hidraw device referring to the
111 FIDO2 device (e.g. /dev/hidraw1). Alternatively the special value
112 "auto" may be specified, in order to automatically determine the
113 device node of a currently plugged in security token (of which
114 there must be exactly one). This automatic discovery is unsupported
115 if --fido2-device= option is also specified.
116 --pkcs11-token-uri=URI
118 Enroll a PKCS#11 security token or smartcard (e.g. a YubiKey).
119 Expects a PKCS#11 smartcard URI referring to the token.
120 Alternatively the special value "auto" may be specified, in order
121 to automatically determine the URI of a currently plugged in
122 security token (of which there must be exactly one). The special
123 value "list" may be used to enumerate all suitable PKCS#11 tokens
124 currently plugged in. The security token must contain an RSA key
125 pair which is used to encrypt the randomly generated key that is
126 used to unlock the LUKS2 volume. The encrypted key is then stored
127 in the LUKS2 JSON token header area.
128 In order to unlock a LUKS2 volume with an enrolled PKCS#11 security
130 token, specify the pkcs11-uri= option in the respective
131 /etc/crypttab line:
132 myvolume /dev/sda1 - pkcs11-uri=auto
134 See crypttab(5) for a more comprehensive example of a
136 systemd-cryptenroll invocation and its matching /etc/crypttab line.
137 --fido2-credential-algorithm=STRING
139 Specify COSE algorithm used in credential generation. The default
140 value is "es256". Supported values are "es256", "rs256" and
141 "eddsa".
142 "es256" denotes ECDSA over NIST P-256 with SHA-256. "rs256"
144 denotes 2048-bit RSA with PKCS#1.5 padding and SHA-256. "eddsa"
145 denotes EDDSA over Curve25519 with SHA-512.
146 Note that your authenticator may not support some algorithms.
148 --fido2-device=PATH
150 Enroll a FIDO2 security token that implements the "hmac-secret"
151 extension (e.g. a YubiKey). Expects a hidraw device referring to
152 the FIDO2 device (e.g. /dev/hidraw1). Alternatively the special
153 value "auto" may be specified, in order to automatically determine
154 the device node of a currently plugged in security token (of which
155 there must be exactly one). This automatic discovery is unsupported
156 if --unlock-fido2-device= option is also specified. The special
157 value "list" may be used to enumerate all suitable FIDO2 tokens
158 currently plugged in. Note that many hardware security tokens that
159 implement FIDO2 also implement the older PKCS#11 standard.
160 Typically FIDO2 is preferable, given it's simpler to use and more
161 modern.
162 In order to unlock a LUKS2 volume with an enrolled FIDO2 security
164 token, specify the fido2-device= option in the respective
165 /etc/crypttab line:
166 myvolume /dev/sda1 - fido2-device=auto
168 See crypttab(5) for a more comprehensive example of a
170 systemd-cryptenroll invocation and its matching /etc/crypttab line.
171 --fido2-with-client-pin=BOOL
173 When enrolling a FIDO2 security token, controls whether to require
174 the user to enter a PIN when unlocking the volume (the FIDO2
175 "clientPin" feature). Defaults to "yes". (Note: this setting is
176 without effect if the security token does not support the
177 "clientPin" feature at all, or does not allow enabling or disabling
178 it.)
179 --fido2-with-user-presence=BOOL
181 When enrolling a FIDO2 security token, controls whether to require
182 the user to verify presence (tap the token, the FIDO2 "up" feature)
183 when unlocking the volume. Defaults to "yes". (Note: this setting
184 is without effect if the security token does not support the "up"
185 feature at all, or does not allow enabling or disabling it.)
186 --fido2-with-user-verification=BOOL
188 When enrolling a FIDO2 security token, controls whether to require
189 user verification when unlocking the volume (the FIDO2 "uv"
190 feature). Defaults to "no". (Note: this setting is without effect
191 if the security token does not support the "uv" feature at all, or
192 does not allow enabling or disabling it.)
193 --tpm2-device=PATH
195 Enroll a TPM2 security chip. Expects a device node path referring
196 to the TPM2 chip (e.g. /dev/tpmrm0). Alternatively the special
197 value "auto" may be specified, in order to automatically determine
198 the device node of a currently discovered TPM2 device (of which
199 there must be exactly one). The special value "list" may be used to
200 enumerate all suitable TPM2 devices currently discovered.
201 In order to unlock a LUKS2 volume with an enrolled TPM2 security
203 chip, specify the tpm2-device= option in the respective
204 /etc/crypttab line:
205 myvolume /dev/sda1 - tpm2-device=auto
207 See crypttab(5) for a more comprehensive example of a
209 systemd-cryptenroll invocation and its matching /etc/crypttab line.
210 Use --tpm2-pcrs= (see below) to configure which TPM2 PCR indexes to
212 bind the enrollment to.
213 --tpm2-pcrs= [PCR...]
215 Configures the TPM2 PCRs (Platform Configuration Registers) to bind
216 the enrollment requested via --tpm2-device= to. Takes a "+"
217 separated list of numeric PCR indexes in the range 0...23. If not
218 used, defaults to PCR 7 only. If an empty string is specified,
219 binds the enrollment to no PCRs at all. PCRs allow binding the
220 enrollment to specific software versions and system state, so that
221 the enrolled unlocking key is only accessible (may be "unsealed")
222 if specific trusted software and/or configuration is used.
223 Table 1. Well-known PCR Definitions
225 ┌────┬────────────────────────────┐
226 │PCR │ Explanation │
227 ├────┼────────────────────────────┤
228 │0 │ Core system firmware │
229 │ │ executable code; changes │
230 │ │ on firmware updates │
231 ├────┼────────────────────────────┤
232 │1 │ Core system firmware │
233 │ │ data/host platform │
234 │ │ configuration; typically │
235 │ │ contains serial and model │
236 │ │ numbers, changes on basic │
237 │ │ hardware/CPU/RAM │
238 │ │ replacements │
239 ├────┼────────────────────────────┤
240 │2 │ Extended or pluggable │
241 │ │ executable code; includes │
242 │ │ option ROMs on pluggable │
243 │ │ hardware │
244 ├────┼────────────────────────────┤
245 │3 │ Extended or pluggable │
246 │ │ firmware data; includes │
247 │ │ information about │
248 │ │ pluggable hardware │
249 ├────┼────────────────────────────┤
250 │4 │ Boot loader and additional │
251 │ │ drivers; changes on boot │
252 │ │ loader updates. The shim │
253 │ │ project will measure the │
254 │ │ PE binary it chain loads │
255 │ │ into this PCR. If the │
256 │ │ Linux kernel is invoked as │
257 │ │ UEFI PE binary, it is │
258 │ │ measured here, too. sd- │
259 │ │ stub(7) measures system │
260 │ │ extension images read from │
261 │ │ the ESP here too (see │
262 │ │ systemd-sysext(8)). │
263 ├────┼────────────────────────────┤
264 │5 │ GPT/Partition table; │
265 │ │ changes when the │
266 │ │ partitions are added, │
267 │ │ modified or removed │
268 ├────┼────────────────────────────┤
269 │6 │ Power state events; │
270 │ │ changes on system │
271 │ │ suspend/sleep │
272 ├────┼────────────────────────────┤
273 │7 │ Secure Boot state; changes │
274 │ │ when UEFI SecureBoot mode │
275 │ │ is enabled/disabled, or │
276 │ │ firmware certificates (PK, │
277 │ │ KEK, db, dbx, ...) │
278 │ │ changes. The shim project │
279 │ │ will measure most of its │
280 │ │ (non-MOK) certificates and │
281 │ │ SBAT data into this PCR. │
282 ├────┼────────────────────────────┤
283 │9 │ The Linux kernel measures │
284 │ │ all initrds it receives │
285 │ │ into this PCR. │
286 ├────┼────────────────────────────┤
287 │10 │ The IMA project measures │
288 │ │ its runtime state into │
289 │ │ this PCR. │
290 ├────┼────────────────────────────┤
291 │11 │ systemd-stub(7) measures │
292 │ │ the ELF kernel image, │
293 │ │ embedded initrd and other │
294 │ │ payload of the PE image it │
295 │ │ is placed in into this │
296 │ │ PCR. Unlike PCR 4 (where │
297 │ │ the same data should be │
298 │ │ measured into), this PCR │
299 │ │ value should be easy to │
300 │ │ pre-calculate, as this │
301 │ │ only contains static parts │
302 │ │ of the PE binary. Use this │
303 │ │ PCR to bind TPM policies │
304 │ │ to a specific kernel │
305 │ │ image, possibly with an │
306 │ │ embedded initrd. systemd- │
307 │ │ pcrphase.service(8) │
308 │ │ measures boot phase │
309 │ │ strings into this PCR at │
310 │ │ various milestones of the │
311 │ │ boot process. │
312 ├────┼────────────────────────────┤
313 │12 │ systemd-boot(7) measures │
314 │ │ the kernel command line │
315 │ │ into this PCR. systemd- │
316 │ │ stub(7) measures any │
317 │ │ manually specified kernel │
318 │ │ command line (i.e. a │
319 │ │ kernel command line that │
320 │ │ overrides the one embedded │
321 │ │ in the unified PE image) │
322 │ │ and loaded credentials │
323 │ │ into this PCR. (Note that │
324 │ │ if systemd-boot and │
325 │ │ systemd-stub are used in │
326 │ │ combination the command │
327 │ │ line might be measured │
328 │ │ twice!) │
329 ├────┼────────────────────────────┤
330 │13 │ systemd-stub(7) measures │
331 │ │ any systemd-sysext(8) │
332 │ │ images it loads and passed │
333 │ │ to the booted kernel into │
334 │ │ this PCR. │
335 ├────┼────────────────────────────┤
336 │14 │ The shim project measures │
337 │ │ its "MOK" certificates and │
338 │ │ hashes into this PCR. │
339 ├────┼────────────────────────────┤
340 │15 │ systemd-cryptsetup(7) │
341 │ │ optionally measures the │
342 │ │ volume key of activated │
343 │ │ LUKS volumes into this │
344 │ │ PCR. │
345 └────┴────────────────────────────┘
346 For most applications it should be sufficient to bind against PCR 7
347 (and possibly PCR 14, if shim/MOK is desired), as this includes
348 measurements of the trusted certificates (and possibly hashes) that
349 are used to validate all components of the boot process up to and
350 including the OS kernel. In order to simplify firmware and OS
351 version updates it's typically not advisable to include PCRs such
352 as 0 and 2 in the binding of the enrollment, since the program code
353 they cover should already be protected indirectly through the
354 certificates measured into PCR 7. Validation through these
355 certificates is typically preferable over validation through direct
356 measurements as it is less brittle in context of OS/firmware
357 updates: the measurements will change on every update, but code
358 signatures likely will validate against pre-existing certificates.
359 --tpm2-with-pin=BOOL
361 When enrolling a TPM2 device, controls whether to require the user
362 to enter a PIN when unlocking the volume in addition to PCR
363 binding, based on TPM2 policy authentication. Defaults to "no".
364 Despite being called PIN, any character can be used, not just
365 numbers.
366 Note that incorrect PIN entry when unlocking increments the TPM
368 dictionary attack lockout mechanism, and may lock out users for a
369 prolonged time, depending on its configuration. The lockout
370 mechanism is a global property of the TPM, systemd-cryptenroll does
371 not control or configure the lockout mechanism. You may use
372 tpm2-tss tools to inspect or configure the dictionary attack
373 lockout, with tpm2_getcap(1) and tpm2_dictionarylockout(1)
374 commands, respectively.
375 --tpm2-public-key= [PATH], --tpm2-public-key-pcrs= [PCR...],
377 --tpm2-signature= [PATH]
378 Configures a TPM2 signed PCR policy to bind encryption to. The
379 --tpm2-public-key= option accepts a path to a PEM encoded RSA
380 public key, to bind the encryption to. If this is not specified
381 explicitly, but a file tpm2-pcr-public-key.pem exists in one of the
382 directories /etc/systemd/, /run/systemd/, /usr/lib/systemd/
383 (searched in this order), it is automatically used. The
384 --tpm2-public-key-pcrs= option takes a list of TPM2 PCR indexes to
385 bind to (same syntax as --tpm2-pcrs= described above). If not
386 specified defaults to 11 (i.e. this binds the policy to any unified
387 kernel image for which a PCR signature can be provided).
388 Note the difference between --tpm2-pcrs= and
390 --tpm2-public-key-pcrs=: the former binds decryption to the
391 current, specific PCR values; the latter binds decryption to any
392 set of PCR values for which a signature by the specified public key
393 can be provided. The latter is hence more useful in scenarios where
394 software updates shell be possible without losing access to all
395 previously encrypted LUKS2 volumes.
396 The --tpm2-signature= option takes a path to a TPM2 PCR signature
398 file as generated by the systemd-measure(1) tool. If this is not
399 specified explicitly a suitable signature file
400 tpm2-pcr-signature.json is searched for in /etc/systemd/,
401 /run/systemd/, /usr/lib/systemd/ (in this order) and used. If a
402 signature file is specified or found it is used to verify if the
403 volume can be unlocked with it given the current PCR state, before
404 the new slot is written to disk. This is intended as safety net to
405 ensure that access to a volume is not lost if a public key is
406 enrolled for which no valid signature for the current PCR state is
407 available. If the supplied signature does not unlock the current
408 PCR state and public key combination, no slot is enrolled and the
409 operation will fail. If no signature file is specified or found no
410 such safety verification is done.
411 --wipe-slot= [SLOT...]
413 Wipes one or more LUKS2 key slots. Takes a comma separated list of
414 numeric slot indexes, or the special strings "all" (for wiping all
415 key slots), "empty" (for wiping all key slots that are unlocked by
416 an empty passphrase), "password" (for wiping all key slots that are
417 unlocked by a traditional passphrase), "recovery" (for wiping all
418 key slots that are unlocked by a recovery key), "pkcs11" (for
419 wiping all key slots that are unlocked by a PKCS#11 token), "fido2"
420 (for wiping all key slots that are unlocked by a FIDO2 token),
421 "tpm2" (for wiping all key slots that are unlocked by a TPM2 chip),
422 or any combination of these strings or numeric indexes, in which
423 case all slots matching either are wiped. As safety precaution an
424 operation that wipes all slots without exception (so that the
425 volume cannot be unlocked at all anymore, unless the volume key is
426 known) is refused.
427 This switch may be used alone, in which case only the requested
429 wipe operation is executed. It may also be used in combination with
430 any of the enrollment options listed above, in which case the
431 enrollment is completed first, and only when successful the wipe
432 operation executed — and the newly added slot is always excluded
433 from the wiping. Combining enrollment and slot wiping may thus be
434 used to update existing enrollments:
435 systemd-cryptenroll /dev/sda1 --wipe-slot=tpm2 --tpm2-device=auto
437 The above command will enroll the TPM2 chip, and then wipe all
439 previously created TPM2 enrollments on the LUKS2 volume, leaving
440 only the newly created one. Combining wiping and enrollment may
441 also be used to replace enrollments of different types, for example
442 for changing from a PKCS#11 enrollment to a FIDO2 one:
443 systemd-cryptenroll /dev/sda1 --wipe-slot=pkcs11 --fido2-device=auto
445 Or for replacing an enrolled empty password by TPM2:
447 systemd-cryptenroll /dev/sda1 --wipe-slot=empty --tpm2-device=auto
449 -h, --help
451 Print a short help text and exit.
452 --version
454 Print a short version string and exit.
455
457 On success, 0 is returned, a non-zero failure code otherwise.
458
460 crypttab(5) and systemd-measure(1) contain various examples employing
461 systemd-cryptenroll.
462
464 systemd(1), systemd-cryptsetup@.service(8), crypttab(5), cryptsetup(8),
465 systemd-measure(1)
466systemd 253 SYSTEMD-CRYPTENROLL(1)