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-device=PATH
102 Enroll a FIDO2 security token that implements the "hmac-secret"
103 extension (e.g. a YubiKey). Expects a hidraw device referring to
104 the FIDO2 device (e.g. /dev/hidraw1). Alternatively the special
105 value "auto" may be specified, in order to automatically determine
106 the device node of a currently plugged in security token (of which
107 there must be exactly one). The special value "list" may be used to
108 enumerate all suitable FIDO2 tokens currently plugged in. Note that
109 many hardware security tokens that implement FIDO2 also implement
110 the older PKCS#11 standard. Typically FIDO2 is preferable, given
111 it's simpler to use and more modern.
112 In order to unlock a LUKS2 volume with an enrolled FIDO2 security
114 token, specify the fido2-device= option in the respective
115 /etc/crypttab line:
116 myvolume /dev/sda1 - fido2-device=auto
118 See crypttab(5) for a more comprehensive example of a
120 systemd-cryptenroll invocation and its matching /etc/crypttab line.
121 --fido2-with-client-pin=BOOL
123 When enrolling a FIDO2 security token, controls whether to require
124 the user to enter a PIN when unlocking the volume (the FIDO2
125 "clientPin" feature). Defaults to "yes". (Note: this setting is
126 without effect if the security token does not support the
127 "clientPin" feature at all, or does not allow enabling or disabling
128 it.)
129 --fido2-with-user-presence=BOOL
131 When enrolling a FIDO2 security token, controls whether to require
132 the user to verify presence (tap the token, the FIDO2 "up" feature)
133 when unlocking the volume. Defaults to "yes". (Note: this setting
134 is without effect if the security token does not support the "up"
135 feature at all, or does not allow enabling or disabling it.)
136 --fido2-with-user-verification=BOOL
138 When enrolling a FIDO2 security token, controls whether to require
139 user verification when unlocking the volume (the FIDO2 "uv"
140 feature). Defaults to "no". (Note: this setting is without effect
141 if the security token does not support the "uv" feature at all, or
142 does not allow enabling or disabling it.)
143 --tpm2-device=PATH
145 Enroll a TPM2 security chip. Expects a device node path referring
146 to the TPM2 chip (e.g. /dev/tpmrm0). Alternatively the special
147 value "auto" may be specified, in order to automatically determine
148 the device node of a currently discovered TPM2 device (of which
149 there must be exactly one). The special value "list" may be used to
150 enumerate all suitable TPM2 devices currently discovered.
151 In order to unlock a LUKS2 volume with an enrolled TPM2 security
153 chip, specify the tpm2-device= option in the respective
154 /etc/crypttab line:
155 myvolume /dev/sda1 - tpm2-device=auto
157 See crypttab(5) for a more comprehensive example of a
159 systemd-cryptenroll invocation and its matching /etc/crypttab line.
160 Use --tpm2-pcrs= (see below) to configure which TPM2 PCR indexes to
162 bind the enrollment to.
163 --tpm2-pcrs= [PCR...]
165 Configures the TPM2 PCRs (Platform Configuration Registers) to bind
166 the enrollment requested via --tpm2-device= to. Takes a "+"
167 separated list of numeric PCR indexes in the range 0...23. If not
168 used, defaults to PCR 7 only. If an empty string is specified,
169 binds the enrollment to no PCRs at all. PCRs allow binding the
170 enrollment to specific software versions and system state, so that
171 the enrolled unlocking key is only accessible (may be "unsealed")
172 if specific trusted software and/or configuration is used.
173 Table 1. Well-known PCR Definitions
175 ┌────┬────────────────────────────┐
176 │PCR │ Explanation │
177 ├────┼────────────────────────────┤
178 │0 │ Core system firmware │
179 │ │ executable code; changes │
180 │ │ on firmware updates │
181 ├────┼────────────────────────────┤
182 │1 │ Core system firmware │
183 │ │ data/host platform │
184 │ │ configuration; typically │
185 │ │ contains serial and model │
186 │ │ numbers, changes on basic │
187 │ │ hardware/CPU/RAM │
188 │ │ replacements │
189 ├────┼────────────────────────────┤
190 │2 │ Extended or pluggable │
191 │ │ executable code; includes │
192 │ │ option ROMs on pluggable │
193 │ │ hardware │
194 ├────┼────────────────────────────┤
195 │3 │ Extended or pluggable │
196 │ │ firmware data; includes │
197 │ │ information about │
198 │ │ pluggable hardware │
199 ├────┼────────────────────────────┤
200 │4 │ Boot loader; changes on │
201 │ │ boot loader updates. The │
202 │ │ shim project will measure │
203 │ │ the PE binary it chain │
204 │ │ loads into this PCR. │
205 ├────┼────────────────────────────┤
206 │5 │ GPT/Partition table; │
207 │ │ changes when the │
208 │ │ partitions are added, │
209 │ │ modified or removed │
210 ├────┼────────────────────────────┤
211 │6 │ Power state events; │
212 │ │ changes on system │
213 │ │ suspend/sleep │
214 ├────┼────────────────────────────┤
215 │7 │ Secure boot state; changes │
216 │ │ when UEFI SecureBoot mode │
217 │ │ is enabled/disabled, or │
218 │ │ firmware certificates (PK, │
219 │ │ KEK, db, dbx, ...) │
220 │ │ changes. The shim project │
221 │ │ will measure most of its │
222 │ │ (non-MOK) certificates and │
223 │ │ SBAT data into this PCR. │
224 ├────┼────────────────────────────┤
225 │8 │ sd-boot(7) measures the │
226 │ │ kernel command line into │
227 │ │ this PCR. │
228 ├────┼────────────────────────────┤
229 │10 │ The IMA project measures │
230 │ │ its runtime state into │
231 │ │ this PCR. │
232 ├────┼────────────────────────────┤
233 │14 │ The shim project measures │
234 │ │ its "MOK" certificates and │
235 │ │ hashes into this PCR. │
236 └────┴────────────────────────────┘
237 For most applications it should be sufficient to bind against PCR 7
238 (and possibly PCR 14, if shim/MOK is desired), as this includes
239 measurements of the trusted certificates (and possibly hashes) that
240 are used to validate all components of the boot process up to and
241 including the OS kernel. In order to simplify firmware and OS
242 version updates it's typically not advisable to include PCRs such
243 as 0 and 2 in the binding of the enrollment, since the program code
244 they cover should already be protected indirectly through the
245 certificates measured into PCR 7. Validation through these
246 certificates is typically preferable over validation through direct
247 measurements as it is less brittle in context of OS/firmware
248 updates: the measurements will change on every update, but code
249 signatures likely will validate against pre-existing certificates.
250 --wipe-slot= [SLOT...]
252 Wipes one or more LUKS2 key slots. Takes a comma separated list of
253 numeric slot indexes, or the special strings "all" (for wiping all
254 key slots), "empty" (for wiping all key slots that are unlocked by
255 an empty passphrase), "password" (for wiping all key slots that are
256 unlocked by a traditional passphrase), "recovery" (for wiping all
257 key slots that are unlocked by a recovery key), "pkcs11" (for
258 wiping all key slots that are unlocked by a PKCS#11 token), "fido2"
259 (for wiping all key slots that are unlocked by a FIDO2 token),
260 "tpm2" (for wiping all key slots that are unlocked by a TPM2 chip),
261 or any combination of these strings or numeric indexes, in which
262 case all slots matching either are wiped. As safety precaution an
263 operation that wipes all slots without exception (so that the
264 volume cannot be unlocked at all anymore, unless the volume key is
265 known) is refused.
266 This switch may be used alone, in which case only the requested
268 wipe operation is executed. It may also be used in combination with
269 any of the enrollment options listed above, in which case the
270 enrollment is completed first, and only when successful the wipe
271 operation executed — and the newly added slot is always excluded
272 from the wiping. Combining enrollment and slot wiping may thus be
273 used to update existing enrollments:
274 systemd-cryptenroll /dev/sda1 --wipe-slot=tpm2 --tpm2-device=auto
276 The above command will enroll the TPM2 chip, and then wipe all
278 previously created TPM2 enrollments on the LUKS2 volume, leaving
279 only the newly created one. Combining wiping and enrollment may
280 also be used to replace enrollments of different types, for example
281 for changing from a PKCS#11 enrollment to a FIDO2 one:
282 systemd-cryptenroll /dev/sda1 --wipe-slot=pkcs11 --fido2-device=auto
284 Or for replacing an enrolled empty password by TPM2:
286 systemd-cryptenroll /dev/sda1 --wipe-slot=empty --tpm2-device=auto
288 -h, --help
290 Print a short help text and exit.
291 --version
293 Print a short version string and exit.
294
296 On success, 0 is returned, a non-zero failure code otherwise.
297
299 systemd(1), systemd-cryptsetup@.service(8), crypttab(5), cryptsetup(8)
300systemd 250 SYSTEMD-CRYPTENROLL(1)