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 TPM2 PCRs and policies
48 PCRs allow binding of the encryption of secrets to specific software
49 versions and system state, so that the enrolled key is only accessible
50 (may be "unsealed") if specific trusted software and/or configuration
51 is used. Such bindings may be created with the option --tpm2-pcrs=
52 described below.
53 Secrets may also be bound indirectly: a signed policy for a state of
55 some combination of PCR values is provided, and the secret is bound to
56 the public part of the key used to sign this policy. This means that
57 the owner of a key can generate a sequence of signed policies, for
58 specific software versions and system states, and the secret can be
59 decrypted as long as the machine state matches one of those policies.
60 For example, a vendor may provide such a policy for each kernel+initrd
61 update, allowing users to encrypt secrets so that they can be decrypted
62 when running any kernel+initrd signed by the vendor. Such bindings may
63 be created with the options --tpm2-public-key=,
64 --tpm2-public-key-pcrs=, --tpm2-signature= described below.
65 See Linux TPM PCR Registry[1] for an authoritative list of PCRs and how
67 they are updated. The table below contains a quick reference,
68 describing in particular the PCRs modified by systemd.
69 Table 1. Well-known PCR Definitions
71 ┌────┬─────────────────────┬───────────────────────┐
72 │PCR │ name │ Explanation │
73 ├────┼─────────────────────┼───────────────────────┤
74 │0 │ platform-code │ Core system │
75 │ │ │ firmware executable │
76 │ │ │ code; changes on │
77 │ │ │ firmware updates │
78 ├────┼─────────────────────┼───────────────────────┤
79 │1 │ platform-config │ Core system │
80 │ │ │ firmware data/host │
81 │ │ │ platform │
82 │ │ │ configuration; │
83 │ │ │ typically contains │
84 │ │ │ serial and model │
85 │ │ │ numbers, changes on │
86 │ │ │ basic │
87 │ │ │ hardware/CPU/RAM │
88 │ │ │ replacements │
89 ├────┼─────────────────────┼───────────────────────┤
90 │2 │ external-code │ Extended or │
91 │ │ │ pluggable │
92 │ │ │ executable code; │
93 │ │ │ includes option │
94 │ │ │ ROMs on pluggable │
95 │ │ │ hardware │
96 ├────┼─────────────────────┼───────────────────────┤
97 │3 │ external-config │ Extended or │
98 │ │ │ pluggable firmware │
99 │ │ │ data; includes │
100 │ │ │ information about │
101 │ │ │ pluggable hardware │
102 ├────┼─────────────────────┼───────────────────────┤
103 │4 │ boot-loader-code │ Boot loader and │
104 │ │ │ additional drivers, │
105 │ │ │ PE binaries invoked │
106 │ │ │ by the boot loader; │
107 │ │ │ changes on boot │
108 │ │ │ loader updates. sd- │
109 │ │ │ stub(7) measures │
110 │ │ │ system extension │
111 │ │ │ images read from │
112 │ │ │ the ESP here too │
113 │ │ │ (see systemd- │
114 │ │ │ sysext(8)). │
115 ├────┼─────────────────────┼───────────────────────┤
116 │5 │ boot-loader-config │ GPT/Partition │
117 │ │ │ table; changes when │
118 │ │ │ the partitions are │
119 │ │ │ added, modified, or │
120 │ │ │ removed │
121 ├────┼─────────────────────┼───────────────────────┤
122 │7 │ secure-boot-policy │ Secure Boot state; │
123 │ │ │ changes when UEFI │
124 │ │ │ SecureBoot mode is │
125 │ │ │ enabled/disabled, │
126 │ │ │ or firmware │
127 │ │ │ certificates (PK, │
128 │ │ │ KEK, db, dbx, ...) │
129 │ │ │ changes. │
130 ├────┼─────────────────────┼───────────────────────┤
131 │9 │ kernel-initrd │ The Linux kernel │
132 │ │ │ measures all │
133 │ │ │ initrds it receives │
134 │ │ │ into this PCR. │
135 ├────┼─────────────────────┼───────────────────────┤
136 │10 │ ima │ The IMA project │
137 │ │ │ measures its │
138 │ │ │ runtime state into │
139 │ │ │ this PCR. │
140 ├────┼─────────────────────┼───────────────────────┤
141 │11 │ kernel-boot │ systemd-stub(7) │
142 │ │ │ measures the ELF │
143 │ │ │ kernel image, │
144 │ │ │ embedded initrd and │
145 │ │ │ other payload of │
146 │ │ │ the PE image it is │
147 │ │ │ placed in into this │
148 │ │ │ PCR. systemd- │
149 │ │ │ pcrphase.service(8) │
150 │ │ │ measures boot phase │
151 │ │ │ strings into this │
152 │ │ │ PCR at various │
153 │ │ │ milestones of the │
154 │ │ │ boot process. │
155 ├────┼─────────────────────┼───────────────────────┤
156 │12 │ kernel-config │ systemd-boot(7) │
157 │ │ │ measures the kernel │
158 │ │ │ command line into │
159 │ │ │ this PCR. systemd- │
160 │ │ │ stub(7) measures │
161 │ │ │ any manually │
162 │ │ │ specified kernel │
163 │ │ │ command line (i.e. │
164 │ │ │ a kernel command │
165 │ │ │ line that overrides │
166 │ │ │ the one embedded in │
167 │ │ │ the unified PE │
168 │ │ │ image) and loaded │
169 │ │ │ credentials into │
170 │ │ │ this PCR. │
171 ├────┼─────────────────────┼───────────────────────┤
172 │13 │ sysexts │ systemd-stub(7) │
173 │ │ │ measures any │
174 │ │ │ systemd-sysext(8) │
175 │ │ │ images it passes to │
176 │ │ │ the booted kernel │
177 │ │ │ into this PCR. │
178 ├────┼─────────────────────┼───────────────────────┤
179 │14 │ shim-policy │ The shim project │
180 │ │ │ measures its "MOK" │
181 │ │ │ certificates and │
182 │ │ │ hashes into this │
183 │ │ │ PCR. │
184 ├────┼─────────────────────┼───────────────────────┤
185 │15 │ system-identity │ systemd- │
186 │ │ │ cryptsetup(8) │
187 │ │ │ optionally measures │
188 │ │ │ the volume key of │
189 │ │ │ activated LUKS │
190 │ │ │ volumes into this │
191 │ │ │ PCR. systemd- │
192 │ │ │ pcrmachine.service(8) │
193 │ │ │ measures the │
194 │ │ │ machine-id(5) into │
195 │ │ │ this PCR. systemd- │
196 │ │ │ pcrfs@.service(8) │
197 │ │ │ measures mount │
198 │ │ │ points, file system │
199 │ │ │ UUIDs, labels, │
200 │ │ │ partition UUIDs of │
201 │ │ │ the root and /var/ │
202 │ │ │ filesystems into │
203 │ │ │ this PCR. │
204 ├────┼─────────────────────┼───────────────────────┤
205 │16 │ debug │ Debug │
206 ├────┼─────────────────────┼───────────────────────┤
207 │23 │ application-support │ Application Support │
208 └────┴─────────────────────┴───────────────────────┘
209 In general, encrypted volumes would be bound to some combination of
211 PCRs 7, 11, and 14 (if shim/MOK is used). In order to allow firmware
212 and OS version updates, it is typically not advisable to use PCRs such
213 as 0 and 2, since the program code they cover should already be covered
214 indirectly through the certificates measured into PCR 7. Validation
215 through certificates hashes is typically preferable over validation
216 through direct measurements as it is less brittle in context of
217 OS/firmware updates: the measurements will change on every update, but
218 signatures should remain unchanged. See the Linux TPM PCR Registry[1]
219 for more discussion.
220
222 Note that currently when enrolling a new key of one of the five
223 supported types listed above, it is required to first provide a
224 passphrase, a recovery key or a FIDO2 token. It's currently not
225 supported to unlock a device with a TPM2/PKCS#11 key in order to enroll
226 a new TPM2/PKCS#11 key. Thus, if in future key roll-over is desired
227 it's generally recommended to ensure a passphrase, a recovery key or a
228 FIDO2 token is always enrolled.
229 Also note that support for enrolling multiple FIDO2 tokens is currently
231 limited. When multiple FIDO2 tokens are enrolled, systemd-cryptseup
232 will perform pre-flight requests to attempt to identify which of the
233 enrolled tokens are currently plugged in. However, this is not possible
234 for FIDO2 tokens with user verification (UV, usually via biometrics),
235 in which case it will fall back to attempting each enrolled token one
236 by one. This will result in multiple prompts for PIN and user
237 verification. This limitation does not apply to PKCS#11 tokens.
238
240 Security technology both in systemd and in the general industry
241 constantly evolves. In order to provide best security guarantees, the
242 way TPM2, FIDO2, PKCS#11 devices are enrolled is regularly updated in
243 newer versions of systemd. Whenever this happens the following
244 compatibility guarantees are given:
245 • Old enrollments continue to be supported and may be unlocked with
247 newer versions of systemd-cryptsetup@.service(8).
248 • The opposite is not guaranteed however: it might not be possible to
250 unlock volumes with enrollments done with a newer version of
251 systemd-cryptenroll with an older version of systemd-cryptsetup.
252 That said, it is generally recommended to use matching versions of
254 systemd-cryptenroll and systemd-cryptsetup, since this is best tested
255 and supported.
256 It might be advisable to re-enroll existing enrollments to take benefit
258 of newer security features, as they are added to systemd.
259
261 The following options are understood:
262 --password
264 Enroll a regular password/passphrase. This command is mostly
265 equivalent to cryptsetup luksAddKey, however may be combined with
266 --wipe-slot= in one call, see below.
267 --recovery-key
269 Enroll a recovery key. Recovery keys are mostly identical to
270 passphrases, but are computer-generated instead of being chosen by
271 a human, and thus have a guaranteed high entropy. The key uses a
272 character set that is easy to type in, and may be scanned off
273 screen via a QR code.
274 --unlock-key-file=PATH
276 Use a file instead of a password/passphrase read from stdin to
277 unlock the volume. Expects the PATH to the file containing your key
278 to unlock the volume. Currently there is nothing like
279 --key-file-offset= or --key-file-size= so this file has to only
280 contain the full key.
281 --unlock-fido2-device=PATH
283 Use a FIDO2 device instead of a password/passphrase read from stdin
284 to unlock the volume. Expects a hidraw device referring to the
285 FIDO2 device (e.g. /dev/hidraw1). Alternatively the special value
286 "auto" may be specified, in order to automatically determine the
287 device node of a currently plugged in security token (of which
288 there must be exactly one). This automatic discovery is unsupported
289 if --fido2-device= option is also specified.
290 --pkcs11-token-uri=URI
292 Enroll a PKCS#11 security token or smartcard (e.g. a YubiKey).
293 Expects a PKCS#11 smartcard URI referring to the token.
294 Alternatively the special value "auto" may be specified, in order
295 to automatically determine the URI of a currently plugged in
296 security token (of which there must be exactly one). The special
297 value "list" may be used to enumerate all suitable PKCS#11 tokens
298 currently plugged in. The security token must contain an RSA key
299 pair which is used to encrypt the randomly generated key that is
300 used to unlock the LUKS2 volume. The encrypted key is then stored
301 in the LUKS2 JSON token header area.
302 In order to unlock a LUKS2 volume with an enrolled PKCS#11 security
304 token, specify the pkcs11-uri= option in the respective
305 /etc/crypttab line:
306 myvolume /dev/sda1 - pkcs11-uri=auto
308 See crypttab(5) for a more comprehensive example of a
310 systemd-cryptenroll invocation and its matching /etc/crypttab line.
311 --fido2-credential-algorithm=STRING
313 Specify COSE algorithm used in credential generation. The default
314 value is "es256". Supported values are "es256", "rs256" and
315 "eddsa".
316 "es256" denotes ECDSA over NIST P-256 with SHA-256. "rs256"
318 denotes 2048-bit RSA with PKCS#1.5 padding and SHA-256. "eddsa"
319 denotes EDDSA over Curve25519 with SHA-512.
320 Note that your authenticator may not support some algorithms.
322 --fido2-device=PATH
324 Enroll a FIDO2 security token that implements the "hmac-secret"
325 extension (e.g. a YubiKey). Expects a hidraw device referring to
326 the FIDO2 device (e.g. /dev/hidraw1). Alternatively the special
327 value "auto" may be specified, in order to automatically determine
328 the device node of a currently plugged in security token (of which
329 there must be exactly one). This automatic discovery is unsupported
330 if --unlock-fido2-device= option is also specified. The special
331 value "list" may be used to enumerate all suitable FIDO2 tokens
332 currently plugged in. Note that many hardware security tokens that
333 implement FIDO2 also implement the older PKCS#11 standard.
334 Typically FIDO2 is preferable, given it's simpler to use and more
335 modern.
336 In order to unlock a LUKS2 volume with an enrolled FIDO2 security
338 token, specify the fido2-device= option in the respective
339 /etc/crypttab line:
340 myvolume /dev/sda1 - fido2-device=auto
342 See crypttab(5) for a more comprehensive example of a
344 systemd-cryptenroll invocation and its matching /etc/crypttab line.
345 --fido2-with-client-pin=BOOL
347 When enrolling a FIDO2 security token, controls whether to require
348 the user to enter a PIN when unlocking the volume (the FIDO2
349 "clientPin" feature). Defaults to "yes". (Note: this setting is
350 without effect if the security token does not support the
351 "clientPin" feature at all, or does not allow enabling or disabling
352 it.)
353 --fido2-with-user-presence=BOOL
355 When enrolling a FIDO2 security token, controls whether to require
356 the user to verify presence (tap the token, the FIDO2 "up" feature)
357 when unlocking the volume. Defaults to "yes". (Note: this setting
358 is without effect if the security token does not support the "up"
359 feature at all, or does not allow enabling or disabling it.)
360 --fido2-with-user-verification=BOOL
362 When enrolling a FIDO2 security token, controls whether to require
363 user verification when unlocking the volume (the FIDO2 "uv"
364 feature). Defaults to "no". (Note: this setting is without effect
365 if the security token does not support the "uv" feature at all, or
366 does not allow enabling or disabling it.)
367 --tpm2-device=PATH
369 Enroll a TPM2 security chip. Expects a device node path referring
370 to the TPM2 chip (e.g. /dev/tpmrm0). Alternatively the special
371 value "auto" may be specified, in order to automatically determine
372 the device node of a currently discovered TPM2 device (of which
373 there must be exactly one). The special value "list" may be used to
374 enumerate all suitable TPM2 devices currently discovered.
375 In order to unlock a LUKS2 volume with an enrolled TPM2 security
377 chip, specify the tpm2-device= option in the respective
378 /etc/crypttab line:
379 myvolume /dev/sda1 - tpm2-device=auto
381 See crypttab(5) for a more comprehensive example of a
383 systemd-cryptenroll invocation and its matching /etc/crypttab line.
384 Use --tpm2-pcrs= (see below) to configure which TPM2 PCR indexes to
386 bind the enrollment to.
387 --tpm2-pcrs= [PCR...]
389 Configures the TPM2 PCRs (Platform Configuration Registers) to bind
390 to when enrollment is requested via --tpm2-device=. Takes a list of
391 PCR names or numeric indices in the range 0...23. Multiple PCR
392 indexes are separated by "+". If not specified, the default is to
393 use PCR 7 only. If an empty string is specified, binds the
394 enrollment to no PCRs at all. See the table above for a list of
395 available PCRs.
396 Example:
398 --tpm2-pcrs=boot-loader-code+platform-config+boot-loader-config
399 specifies that PCR registers 4, 1, and 5 should be used.
400 --tpm2-with-pin=BOOL
402 When enrolling a TPM2 device, controls whether to require the user
403 to enter a PIN when unlocking the volume in addition to PCR
404 binding, based on TPM2 policy authentication. Defaults to "no".
405 Despite being called PIN, any character can be used, not just
406 numbers.
407 Note that incorrect PIN entry when unlocking increments the TPM
409 dictionary attack lockout mechanism, and may lock out users for a
410 prolonged time, depending on its configuration. The lockout
411 mechanism is a global property of the TPM, systemd-cryptenroll does
412 not control or configure the lockout mechanism. You may use
413 tpm2-tss tools to inspect or configure the dictionary attack
414 lockout, with tpm2_getcap(1) and tpm2_dictionarylockout(1)
415 commands, respectively.
416 --tpm2-public-key= [PATH], --tpm2-public-key-pcrs= [PCR...],
418 --tpm2-signature= [PATH]
419 Configures a TPM2 signed PCR policy to bind encryption to. The
420 --tpm2-public-key= option accepts a path to a PEM encoded RSA
421 public key, to bind the encryption to. If this is not specified
422 explicitly, but a file tpm2-pcr-public-key.pem exists in one of the
423 directories /etc/systemd/, /run/systemd/, /usr/lib/systemd/
424 (searched in this order), it is automatically used. The
425 --tpm2-public-key-pcrs= option takes a list of TPM2 PCR indexes to
426 bind to (same syntax as --tpm2-pcrs= described above). If not
427 specified defaults to 11 (i.e. this binds the policy to any unified
428 kernel image for which a PCR signature can be provided).
429 Note the difference between --tpm2-pcrs= and
431 --tpm2-public-key-pcrs=: the former binds decryption to the
432 current, specific PCR values; the latter binds decryption to any
433 set of PCR values for which a signature by the specified public key
434 can be provided. The latter is hence more useful in scenarios where
435 software updates shell be possible without losing access to all
436 previously encrypted LUKS2 volumes. Like with --tpm2-pcrs=, names
437 defined in the table above can also be used to specify the
438 registers, for instance
439 --tpm2-public-key-pcrs=boot-loader-code+system-identity.
440 The --tpm2-signature= option takes a path to a TPM2 PCR signature
442 file as generated by the systemd-measure(1) tool. If this is not
443 specified explicitly, a suitable signature file
444 tpm2-pcr-signature.json is searched for in /etc/systemd/,
445 /run/systemd/, /usr/lib/systemd/ (in this order) and used. If a
446 signature file is specified or found it is used to verify if the
447 volume can be unlocked with it given the current PCR state, before
448 the new slot is written to disk. This is intended as safety net to
449 ensure that access to a volume is not lost if a public key is
450 enrolled for which no valid signature for the current PCR state is
451 available. If the supplied signature does not unlock the current
452 PCR state and public key combination, no slot is enrolled and the
453 operation will fail. If no signature file is specified or found no
454 such safety verification is done.
455 --wipe-slot= [SLOT...]
457 Wipes one or more LUKS2 key slots. Takes a comma separated list of
458 numeric slot indexes, or the special strings "all" (for wiping all
459 key slots), "empty" (for wiping all key slots that are unlocked by
460 an empty passphrase), "password" (for wiping all key slots that are
461 unlocked by a traditional passphrase), "recovery" (for wiping all
462 key slots that are unlocked by a recovery key), "pkcs11" (for
463 wiping all key slots that are unlocked by a PKCS#11 token), "fido2"
464 (for wiping all key slots that are unlocked by a FIDO2 token),
465 "tpm2" (for wiping all key slots that are unlocked by a TPM2 chip),
466 or any combination of these strings or numeric indexes, in which
467 case all slots matching either are wiped. As safety precaution an
468 operation that wipes all slots without exception (so that the
469 volume cannot be unlocked at all anymore, unless the volume key is
470 known) is refused.
471 This switch may be used alone, in which case only the requested
473 wipe operation is executed. It may also be used in combination with
474 any of the enrollment options listed above, in which case the
475 enrollment is completed first, and only when successful the wipe
476 operation executed — and the newly added slot is always excluded
477 from the wiping. Combining enrollment and slot wiping may thus be
478 used to update existing enrollments:
479 systemd-cryptenroll /dev/sda1 --wipe-slot=tpm2 --tpm2-device=auto
481 The above command will enroll the TPM2 chip, and then wipe all
483 previously created TPM2 enrollments on the LUKS2 volume, leaving
484 only the newly created one. Combining wiping and enrollment may
485 also be used to replace enrollments of different types, for example
486 for changing from a PKCS#11 enrollment to a FIDO2 one:
487 systemd-cryptenroll /dev/sda1 --wipe-slot=pkcs11 --fido2-device=auto
489 Or for replacing an enrolled empty password by TPM2:
491 systemd-cryptenroll /dev/sda1 --wipe-slot=empty --tpm2-device=auto
493 -h, --help
495 Print a short help text and exit.
496 --version
498 Print a short version string and exit.
499
501 On success, 0 is returned, a non-zero failure code otherwise.
502
504 crypttab(5) and systemd-measure(1) contain various examples employing
505 systemd-cryptenroll.
506
508 systemd(1), systemd-cryptsetup@.service(8), crypttab(5), cryptsetup(8),
509 systemd-measure(1)
510
512 1. Linux TPM PCR Registry
513 https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/
514systemd 254 SYSTEMD-CRYPTENROLL(1)