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 The following options are understood:
49 --password
51 Enroll a regular password/passphrase. This command is mostly
52 equivalent to cryptsetup luksAddKey, however may be combined with
53 --wipe-slot= in one call, see below.
54 --recovery-key
56 Enroll a recovery key. Recovery keys are most identical to
57 passphrases, but are computer generated instead of human chosen,
58 and thus have a guaranteed high entropy. The key uses a character
59 set that is easy to type in, and may be scanned off screen via a QR
60 code.
61 --pkcs11-token-uri=URI
63 Enroll a PKCS#11 security token or smartcard (e.g. a YubiKey).
64 Expects a PKCS#11 smart card URI referring to the token.
65 Alternatively the special value "auto" may be specified, in order
66 to automatically determine the URI of a currently plugged in
67 security token (of which there must be exactly one). The special
68 value "list" may be used to enumerate all suitable PKCS#11 tokens
69 currently plugged in. The security token must contain an RSA key
70 pair which is used to encrypt the randomly generated key that is
71 used to unlock the LUKS2 volume. The encrypted key is then stored
72 in the LUKS2 JSON token header area.
73 In order to unlock a LUKS2 volume with an enrolled PKCS#11 security
75 token, specify the pkcs11-uri= option in the respective
76 /etc/crypttab line:
77 myvolume /dev/sda1 - pkcs11-uri=auto
79 See crypttab(5) for a more comprehensive example of a
81 systemd-cryptenroll invocation and its matching /etc/crypttab line.
82 --fido2-device=PATH
84 Enroll a FIDO2 security token that implements the "hmac-secret"
85 extension (e.g. a YubiKey). Expects a hidraw device referring to
86 the FIDO2 device (e.g. /dev/hidraw1). Alternatively the special
87 value "auto" may be specified, in order to automatically determine
88 the device node of a currently plugged in security token (of which
89 there must be exactly one). The special value "list" may be used to
90 enumerate all suitable FIDO2 tokens currently plugged in. Note that
91 many hardware security tokens that implement FIDO2 also implement
92 the older PKCS#11 standard. Typically FIDO2 is preferable, given
93 it's simpler to use and more modern.
94 In order to unlock a LUKS2 volume with an enrolled FIDO2 security
96 token, specify the fido2-device= option in the respective
97 /etc/crypttab line:
98 myvolume /dev/sda1 - fido2-device=auto
100 See crypttab(5) for a more comprehensive example of a
102 systemd-cryptenroll invocation and its matching /etc/crypttab line.
103 --tpm2-device=PATH
105 Enroll a TPM2 security chip. Expects a device node path referring
106 to the TPM2 chip (e.g. /dev/tpmrm0). Alternatively the special
107 value "auto" may be specified, in order to automatically determine
108 the device node of a currently discovered TPM2 device (of which
109 there must be exactly one). The special value "list" may be used to
110 enumerate all suitable TPM2 devices currently discovered.
111 In order to unlock a LUKS2 volume with an enrolled TPM2 security
113 chip, specify the tpm2-device= option in the respective
114 /etc/crypttab line:
115 myvolume /dev/sda1 - tpm2-device=auto
117 See crypttab(5) for a more comprehensive example of a
119 systemd-cryptenroll invocation and its matching /etc/crypttab line.
120 Use --tpm2-pcrs= (see below) to configure which TPM2 PCR indexes to
122 bind the enrollment to.
123 --tpm2-pcrs= [PCR...]
125 Configures the TPM2 PCRs (Platform Configuration Registers) to bind
126 the enrollment requested via --tpm2-device= to. Takes a comma
127 separated list of numeric PCR indexes in the range 0...23. If not
128 used, defaults to PCR 7 only. If an empty string is specified,
129 binds the enrollment to no PCRs at all. PCRs allow binding the
130 enrollment to specific software versions and system state, so that
131 the enrolled unlocking key is only accessible (may be "unsealed")
132 if specific trusted software and/or configuration is used.
133 Table 1. Well-known PCR Definitions
135 ┌────┬────────────────────────────┐
136 │PCR │ Explanation │
137 ├────┼────────────────────────────┤
138 │0 │ Core system firmware │
139 │ │ executable code; changes │
140 │ │ on firmware updates │
141 ├────┼────────────────────────────┤
142 │1 │ Core system firmware │
143 │ │ data/host platform │
144 │ │ configuration; typically │
145 │ │ contains serial and model │
146 │ │ numbers, changes on basic │
147 │ │ hardware/CPU/RAM │
148 │ │ replacements │
149 ├────┼────────────────────────────┤
150 │2 │ Extended or pluggable │
151 │ │ executable code; includes │
152 │ │ option ROMs on pluggable │
153 │ │ hardware │
154 ├────┼────────────────────────────┤
155 │3 │ Extended or pluggable │
156 │ │ firmware data; includes │
157 │ │ information about │
158 │ │ pluggable hardware │
159 ├────┼────────────────────────────┤
160 │4 │ Boot loader; changes on │
161 │ │ boot loader updates │
162 ├────┼────────────────────────────┤
163 │5 │ GPT/Partition table; │
164 │ │ changes when the │
165 │ │ partitions are added, │
166 │ │ modified or removed │
167 ├────┼────────────────────────────┤
168 │6 │ Power state events; │
169 │ │ changes on system │
170 │ │ suspend/sleep │
171 ├────┼────────────────────────────┤
172 │7 │ Secure boot state; changes │
173 │ │ when UEFI SecureBoot mode │
174 │ │ is enabled/disabled │
175 ├────┼────────────────────────────┤
176 │8 │ sd-boot(7) measures the │
177 │ │ kernel command line in │
178 │ │ this PCR. │
179 └────┴────────────────────────────┘
180 --wipe-slot= [SLOT...]
182 Wipes one or more LUKS2 key slots. Takes a comma separated list of
183 numeric slot indexes, or the special strings "all" (for wiping all
184 key slots), "empty" (for wiping all key slots that are unlocked by
185 an empty passphrase), "password" (for wiping all key slots that are
186 unlocked by a traditional passphrase), "recovery" (for wiping all
187 key slots that are unlocked by a recovery key), "pkcs11" (for
188 wiping all key slots that are unlocked by a PKCS#11 token), "fido2"
189 (for wiping all key slots that are unlocked by a FIDO2 token),
190 "tpm2" (for wiping all key slots that are unlocked by a TPM2 chip),
191 or any combination of these strings or numeric indexes, in which
192 case all slots matching either are wiped. As safety precaution an
193 operation that wipes all slots without exception (so that the
194 volume cannot be unlocked at all anymore, unless the volume key is
195 known) is refused.
196 This switch may be used alone, in which case only the requested
198 wipe operation is executed. It may also be used in combination with
199 any of the enrollment options listed above, in which case the
200 enrollment is completed first, and only when successful the wipe
201 operation executed — and the newly added slot is always excluded
202 from the wiping. Combining enrollment and slot wiping may thus be
203 used to update existing enrollments:
204 systemd-cryptenroll /dev/sda1 --wipe-slot=tpm2 --tpm2-device=auto
206 The above command will enroll the TPM2 chip, and then wipe all
208 previously created TPM2 enrollments on the LUKS2 volume, leaving
209 only the newly created one. Combining wiping and enrollment may
210 also be used to replace enrollments of different types, for example
211 for changing from a PKCS#11 enrollment to a FIDO2 one:
212 systemd-cryptenroll /dev/sda1 --wipe-slot=pkcs11 --fido2-device=auto
214 Or for replacing an enrolled empty password by TPM2:
216 systemd-cryptenroll /dev/sda1 --wipe-slot=empty --tpm2-device=auto
218 -h, --help
220 Print a short help text and exit.
221 --version
223 Print a short version string and exit.
224
226 On success, 0 is returned, a non-zero failure code otherwise.
227
229 systemd(1), systemd-cryptsetup@.service(8), crypttab(5), cryptsetup(8)
230systemd 248 SYSTEMD-CRYPTENROLL(1)