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. Recovery keys. These are similar to regular passphrases, however
27 are randomly generated on the computer and thus generally have
28 higher entropy than user chosen passphrases. Their character set
29 has been designed to ensure they are easy to type in, while having
30 high entropy. They may also be scanned off screen using QR codes.
31 Recovery keys may be used for unlocking LUKS2 volumes wherever
32 passphrases are accepted. They are intended to be used in
33 combination with an enrolled hardware security token, as a recovery
34 option when the token is lost.
35 5. Regular passphrases
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 most identical to
75 passphrases, but are computer generated instead of human chosen,
76 and thus have a guaranteed high entropy. The key uses a character
77 set that is easy to type in, and may be scanned off screen via a QR
78 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 │
202 ├────┼────────────────────────────┤
203 │5 │ GPT/Partition table; │
204 │ │ changes when the │
205 │ │ partitions are added, │
206 │ │ modified or removed │
207 ├────┼────────────────────────────┤
208 │6 │ Power state events; │
209 │ │ changes on system │
210 │ │ suspend/sleep │
211 ├────┼────────────────────────────┤
212 │7 │ Secure boot state; changes │
213 │ │ when UEFI SecureBoot mode │
214 │ │ is enabled/disabled │
215 ├────┼────────────────────────────┤
216 │8 │ sd-boot(7) measures the │
217 │ │ kernel command line in │
218 │ │ this PCR. │
219 └────┴────────────────────────────┘
220 --wipe-slot= [SLOT...]
222 Wipes one or more LUKS2 key slots. Takes a comma separated list of
223 numeric slot indexes, or the special strings "all" (for wiping all
224 key slots), "empty" (for wiping all key slots that are unlocked by
225 an empty passphrase), "password" (for wiping all key slots that are
226 unlocked by a traditional passphrase), "recovery" (for wiping all
227 key slots that are unlocked by a recovery key), "pkcs11" (for
228 wiping all key slots that are unlocked by a PKCS#11 token), "fido2"
229 (for wiping all key slots that are unlocked by a FIDO2 token),
230 "tpm2" (for wiping all key slots that are unlocked by a TPM2 chip),
231 or any combination of these strings or numeric indexes, in which
232 case all slots matching either are wiped. As safety precaution an
233 operation that wipes all slots without exception (so that the
234 volume cannot be unlocked at all anymore, unless the volume key is
235 known) is refused.
236 This switch may be used alone, in which case only the requested
238 wipe operation is executed. It may also be used in combination with
239 any of the enrollment options listed above, in which case the
240 enrollment is completed first, and only when successful the wipe
241 operation executed — and the newly added slot is always excluded
242 from the wiping. Combining enrollment and slot wiping may thus be
243 used to update existing enrollments:
244 systemd-cryptenroll /dev/sda1 --wipe-slot=tpm2 --tpm2-device=auto
246 The above command will enroll the TPM2 chip, and then wipe all
248 previously created TPM2 enrollments on the LUKS2 volume, leaving
249 only the newly created one. Combining wiping and enrollment may
250 also be used to replace enrollments of different types, for example
251 for changing from a PKCS#11 enrollment to a FIDO2 one:
252 systemd-cryptenroll /dev/sda1 --wipe-slot=pkcs11 --fido2-device=auto
254 Or for replacing an enrolled empty password by TPM2:
256 systemd-cryptenroll /dev/sda1 --wipe-slot=empty --tpm2-device=auto
258 -h, --help
260 Print a short help text and exit.
261 --version
263 Print a short version string and exit.
264
266 On success, 0 is returned, a non-zero failure code otherwise.
267
269 systemd(1), systemd-cryptsetup@.service(8), crypttab(5), cryptsetup(8)
270systemd 249 SYSTEMD-CRYPTENROLL(1)