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 or recovery key (i.e. one of the latter two key types). For
51 example, it's currently not possible to unlock a device with a FIDO2
52 key in order to enroll a new FIDO2 key. Instead, in order to enroll a
53 new FIDO2 key, it is necessary to provide an already enrolled regular
54 passphrase or recovery key. Thus, if in future key roll-over is desired
55 it's generally recommended to combine TPM2, FIDO2, PKCS#11 key
56 enrollment with enrolling a regular passphrase or recovery key.
57 Also note that support for enrolling multiple FIDO2 tokens is currently
59 not too useful, as while unlocking systemd-cryptsetup cannot identify
60 which token is currently plugged in and thus does not know which
61 authentication request to send to the device. This limitation does not
62 apply to tokens enrolled via PKCS#11 — because tokens of this type may
63 be identified immediately, before authentication.
64
66 The following options are understood:
67 --password
69 Enroll a regular password/passphrase. This command is mostly
70 equivalent to cryptsetup luksAddKey, however may be combined with
71 --wipe-slot= in one call, see below.
72 --recovery-key
74 Enroll a recovery key. Recovery keys are mostly identical to
75 passphrases, but are computer-generated instead of being chosen by
76 a human, and thus have a guaranteed high entropy. The key uses a
77 character set that is easy to type in, and may be scanned off
78 screen via a QR code.
79 --pkcs11-token-uri=URI
81 Enroll a PKCS#11 security token or smartcard (e.g. a YubiKey).
82 Expects a PKCS#11 smartcard URI referring to the token.
83 Alternatively the special value "auto" may be specified, in order
84 to automatically determine the URI of a currently plugged in
85 security token (of which there must be exactly one). The special
86 value "list" may be used to enumerate all suitable PKCS#11 tokens
87 currently plugged in. The security token must contain an RSA key
88 pair which is used to encrypt the randomly generated key that is
89 used to unlock the LUKS2 volume. The encrypted key is then stored
90 in the LUKS2 JSON token header area.
91 In order to unlock a LUKS2 volume with an enrolled PKCS#11 security
93 token, specify the pkcs11-uri= option in the respective
94 /etc/crypttab line:
95 myvolume /dev/sda1 - pkcs11-uri=auto
97 See crypttab(5) for a more comprehensive example of a
99 systemd-cryptenroll invocation and its matching /etc/crypttab line.
100 --fido2-credential-algorithm=STRING
102 Specify COSE algorithm used in credential generation. The default
103 value is "es256". Supported values are "es256", "rs256" and
104 "eddsa".
105 "es256" denotes ECDSA over NIST P-256 with SHA-256. "rs256"
107 denotes 2048-bit RSA with PKCS#1.5 padding and SHA-256. "eddsa"
108 denotes EDDSA over Curve25519 with SHA-512.
109 Note that your authenticator may not support some algorithms.
111 --fido2-device=PATH
113 Enroll a FIDO2 security token that implements the "hmac-secret"
114 extension (e.g. a YubiKey). Expects a hidraw device referring to
115 the FIDO2 device (e.g. /dev/hidraw1). Alternatively the special
116 value "auto" may be specified, in order to automatically determine
117 the device node of a currently plugged in security token (of which
118 there must be exactly one). The special value "list" may be used to
119 enumerate all suitable FIDO2 tokens currently plugged in. Note that
120 many hardware security tokens that implement FIDO2 also implement
121 the older PKCS#11 standard. Typically FIDO2 is preferable, given
122 it's simpler to use and more modern.
123 In order to unlock a LUKS2 volume with an enrolled FIDO2 security
125 token, specify the fido2-device= option in the respective
126 /etc/crypttab line:
127 myvolume /dev/sda1 - fido2-device=auto
129 See crypttab(5) for a more comprehensive example of a
131 systemd-cryptenroll invocation and its matching /etc/crypttab line.
132 --fido2-with-client-pin=BOOL
134 When enrolling a FIDO2 security token, controls whether to require
135 the user to enter a PIN when unlocking the volume (the FIDO2
136 "clientPin" feature). Defaults to "yes". (Note: this setting is
137 without effect if the security token does not support the
138 "clientPin" feature at all, or does not allow enabling or disabling
139 it.)
140 --fido2-with-user-presence=BOOL
142 When enrolling a FIDO2 security token, controls whether to require
143 the user to verify presence (tap the token, the FIDO2 "up" feature)
144 when unlocking the volume. Defaults to "yes". (Note: this setting
145 is without effect if the security token does not support the "up"
146 feature at all, or does not allow enabling or disabling it.)
147 --fido2-with-user-verification=BOOL
149 When enrolling a FIDO2 security token, controls whether to require
150 user verification when unlocking the volume (the FIDO2 "uv"
151 feature). Defaults to "no". (Note: this setting is without effect
152 if the security token does not support the "uv" feature at all, or
153 does not allow enabling or disabling it.)
154 --tpm2-device=PATH
156 Enroll a TPM2 security chip. Expects a device node path referring
157 to the TPM2 chip (e.g. /dev/tpmrm0). Alternatively the special
158 value "auto" may be specified, in order to automatically determine
159 the device node of a currently discovered TPM2 device (of which
160 there must be exactly one). The special value "list" may be used to
161 enumerate all suitable TPM2 devices currently discovered.
162 In order to unlock a LUKS2 volume with an enrolled TPM2 security
164 chip, specify the tpm2-device= option in the respective
165 /etc/crypttab line:
166 myvolume /dev/sda1 - tpm2-device=auto
168 See crypttab(5) for a more comprehensive example of a
170 systemd-cryptenroll invocation and its matching /etc/crypttab line.
171 Use --tpm2-pcrs= (see below) to configure which TPM2 PCR indexes to
173 bind the enrollment to.
174 --tpm2-pcrs= [PCR...]
176 Configures the TPM2 PCRs (Platform Configuration Registers) to bind
177 the enrollment requested via --tpm2-device= to. Takes a "+"
178 separated list of numeric PCR indexes in the range 0...23. If not
179 used, defaults to PCR 7 only. If an empty string is specified,
180 binds the enrollment to no PCRs at all. PCRs allow binding the
181 enrollment to specific software versions and system state, so that
182 the enrolled unlocking key is only accessible (may be "unsealed")
183 if specific trusted software and/or configuration is used.
184 Table 1. Well-known PCR Definitions
186 ┌────┬────────────────────────────┐
187 │PCR │ Explanation │
188 ├────┼────────────────────────────┤
189 │0 │ Core system firmware │
190 │ │ executable code; changes │
191 │ │ on firmware updates │
192 ├────┼────────────────────────────┤
193 │1 │ Core system firmware │
194 │ │ data/host platform │
195 │ │ configuration; typically │
196 │ │ contains serial and model │
197 │ │ numbers, changes on basic │
198 │ │ hardware/CPU/RAM │
199 │ │ replacements │
200 ├────┼────────────────────────────┤
201 │2 │ Extended or pluggable │
202 │ │ executable code; includes │
203 │ │ option ROMs on pluggable │
204 │ │ hardware │
205 ├────┼────────────────────────────┤
206 │3 │ Extended or pluggable │
207 │ │ firmware data; includes │
208 │ │ information about │
209 │ │ pluggable hardware │
210 ├────┼────────────────────────────┤
211 │4 │ Boot loader and additional │
212 │ │ drivers; changes on boot │
213 │ │ loader updates. The shim │
214 │ │ project will measure the │
215 │ │ PE binary it chain loads │
216 │ │ into this PCR. If the │
217 │ │ Linux kernel is invoked as │
218 │ │ UEFI PE binary, it is │
219 │ │ measured here, too. sd- │
220 │ │ stub(7) measures system │
221 │ │ extension images read from │
222 │ │ the ESP here too (see │
223 │ │ systemd-sysext(8)). │
224 ├────┼────────────────────────────┤
225 │5 │ GPT/Partition table; │
226 │ │ changes when the │
227 │ │ partitions are added, │
228 │ │ modified or removed │
229 ├────┼────────────────────────────┤
230 │6 │ Power state events; │
231 │ │ changes on system │
232 │ │ suspend/sleep │
233 ├────┼────────────────────────────┤
234 │7 │ Secure boot state; changes │
235 │ │ when UEFI SecureBoot mode │
236 │ │ is enabled/disabled, or │
237 │ │ firmware certificates (PK, │
238 │ │ KEK, db, dbx, ...) │
239 │ │ changes. The shim project │
240 │ │ will measure most of its │
241 │ │ (non-MOK) certificates and │
242 │ │ SBAT data into this PCR. │
243 ├────┼────────────────────────────┤
244 │9 │ The Linux kernel measures │
245 │ │ all initial RAM file │
246 │ │ systems it receives into │
247 │ │ this PCR. │
248 ├────┼────────────────────────────┤
249 │10 │ The IMA project measures │
250 │ │ its runtime state into │
251 │ │ this PCR. │
252 ├────┼────────────────────────────┤
253 │12 │ systemd-boot(7) measures │
254 │ │ any specified kernel │
255 │ │ command line into this │
256 │ │ PCR. systemd-stub(7) │
257 │ │ measures any manually │
258 │ │ specified kernel command │
259 │ │ line (i.e. a kernel │
260 │ │ command line that │
261 │ │ overrides the one embedded │
262 │ │ in the unified PE image) │
263 │ │ and loaded credentials │
264 │ │ into this PCR. (Note that │
265 │ │ if sytemd-boot and │
266 │ │ systemd-stub are used in │
267 │ │ combination the command │
268 │ │ line might be measured │
269 │ │ twice!) │
270 ├────┼────────────────────────────┤
271 │14 │ The shim project measures │
272 │ │ its "MOK" certificates and │
273 │ │ hashes into this PCR. │
274 └────┴────────────────────────────┘
275 For most applications it should be sufficient to bind against PCR 7
276 (and possibly PCR 14, if shim/MOK is desired), as this includes
277 measurements of the trusted certificates (and possibly hashes) that
278 are used to validate all components of the boot process up to and
279 including the OS kernel. In order to simplify firmware and OS
280 version updates it's typically not advisable to include PCRs such
281 as 0 and 2 in the binding of the enrollment, since the program code
282 they cover should already be protected indirectly through the
283 certificates measured into PCR 7. Validation through these
284 certificates is typically preferable over validation through direct
285 measurements as it is less brittle in context of OS/firmware
286 updates: the measurements will change on every update, but code
287 signatures likely will validate against pre-existing certificates.
288 --tpm2-with-pin=BOOL
290 When enrolling a TPM2 device, controls whether to require the user
291 to enter a PIN when unlocking the volume in addition to PCR
292 binding, based on TPM2 policy authentication. Defaults to "no".
293 Despite being called PIN, any character can be used, not just
294 numbers.
295 Note that incorrect PIN entry when unlocking increments the TPM
297 dictionary attack lockout mechanism, and may lock out users for a
298 prolonged time, depending on its configuration. The lockout
299 mechanism is a global property of the TPM, systemd-cryptenroll does
300 not control or configure the lockout mechanism. You may use
301 tpm2-tss tools to inspect or configure the dictionary attack
302 lockout, with tpm2_getcap(1) and tpm2_dictionarylockout(1)
303 commands, respectively.
304 --wipe-slot= [SLOT...]
306 Wipes one or more LUKS2 key slots. Takes a comma separated list of
307 numeric slot indexes, or the special strings "all" (for wiping all
308 key slots), "empty" (for wiping all key slots that are unlocked by
309 an empty passphrase), "password" (for wiping all key slots that are
310 unlocked by a traditional passphrase), "recovery" (for wiping all
311 key slots that are unlocked by a recovery key), "pkcs11" (for
312 wiping all key slots that are unlocked by a PKCS#11 token), "fido2"
313 (for wiping all key slots that are unlocked by a FIDO2 token),
314 "tpm2" (for wiping all key slots that are unlocked by a TPM2 chip),
315 or any combination of these strings or numeric indexes, in which
316 case all slots matching either are wiped. As safety precaution an
317 operation that wipes all slots without exception (so that the
318 volume cannot be unlocked at all anymore, unless the volume key is
319 known) is refused.
320 This switch may be used alone, in which case only the requested
322 wipe operation is executed. It may also be used in combination with
323 any of the enrollment options listed above, in which case the
324 enrollment is completed first, and only when successful the wipe
325 operation executed — and the newly added slot is always excluded
326 from the wiping. Combining enrollment and slot wiping may thus be
327 used to update existing enrollments:
328 systemd-cryptenroll /dev/sda1 --wipe-slot=tpm2 --tpm2-device=auto
330 The above command will enroll the TPM2 chip, and then wipe all
332 previously created TPM2 enrollments on the LUKS2 volume, leaving
333 only the newly created one. Combining wiping and enrollment may
334 also be used to replace enrollments of different types, for example
335 for changing from a PKCS#11 enrollment to a FIDO2 one:
336 systemd-cryptenroll /dev/sda1 --wipe-slot=pkcs11 --fido2-device=auto
338 Or for replacing an enrolled empty password by TPM2:
340 systemd-cryptenroll /dev/sda1 --wipe-slot=empty --tpm2-device=auto
342 -h, --help
344 Print a short help text and exit.
345 --version
347 Print a short version string and exit.
348
350 On success, 0 is returned, a non-zero failure code otherwise.
351
353 systemd(1), systemd-cryptsetup@.service(8), crypttab(5), cryptsetup(8)
354systemd 251 SYSTEMD-CRYPTENROLL(1)