1<?xml version="1.0"?> 2<!--*-nxml-*--> 3<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 4 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 5<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 6<refentry id="systemd-cryptenroll" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='HAVE_LIBCRYPTSETUP'> 7 8 <refentryinfo> 9 <title>systemd-cryptenroll</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>systemd-cryptenroll</refentrytitle> 15 <manvolnum>1</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>systemd-cryptenroll</refname> 20 <refpurpose>Enroll PKCS#11, FIDO2, TPM2 token/devices to LUKS2 encrypted volumes</refpurpose> 21 </refnamediv> 22 23 <refsynopsisdiv> 24 <cmdsynopsis> 25 <command>systemd-cryptenroll <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">DEVICE</arg></command> 26 </cmdsynopsis> 27 </refsynopsisdiv> 28 29 <refsect1> 30 <title>Description</title> 31 32 <para><command>systemd-cryptenroll</command> is a tool for enrolling hardware security tokens and devices 33 into a LUKS2 encrypted volume, which may then be used to unlock the volume during boot. Specifically, it 34 supports tokens and credentials of the following kind to be enrolled:</para> 35 36 <orderedlist> 37 <listitem><para>PKCS#11 security tokens and smartcards that may carry an RSA key pair (e.g. various 38 YubiKeys)</para></listitem> 39 40 <listitem><para>FIDO2 security tokens that implement the <literal>hmac-secret</literal> extension (most 41 FIDO2 keys, including YubiKeys)</para></listitem> 42 43 <listitem><para>TPM2 security devices</para></listitem> 44 45 <listitem><para>Regular passphrases</para></listitem> 46 47 <listitem><para>Recovery keys. These are similar to regular passphrases, however are randomly generated 48 on the computer and thus generally have higher entropy than user-chosen passphrases. Their character 49 set has been designed to ensure they are easy to type in, while having high entropy. They may also be 50 scanned off screen using QR codes. Recovery keys may be used for unlocking LUKS2 volumes wherever 51 passphrases are accepted. They are intended to be used in combination with an enrolled hardware 52 security token, as a recovery option when the token is lost.</para></listitem> 53 </orderedlist> 54 55 <para>In addition, the tool may be used to enumerate currently enrolled security tokens and wipe a subset 56 of them. The latter may be combined with the enrollment operation of a new security token, in order to 57 update or replace enrollments.</para> 58 59 <para>The tool supports only LUKS2 volumes, as it stores token meta-information in the LUKS2 JSON token 60 area, which is not available in other encryption formats.</para> 61 </refsect1> 62 63 <refsect1> 64 <title>Limitations</title> 65 66 <para>Note that currently when enrolling a new key of one of the five supported types listed above, it is 67 required to first provide a passphrase or recovery key (i.e. one of the latter two key types). For 68 example, it's currently not possible to unlock a device with a FIDO2 key in order to enroll a new FIDO2 69 key. Instead, in order to enroll a new FIDO2 key, it is necessary to provide an already enrolled regular 70 passphrase or recovery key. Thus, if in future key roll-over is desired it's generally recommended to 71 combine TPM2, FIDO2, PKCS#11 key enrollment with enrolling a regular passphrase or recovery key.</para> 72 73 <para>Also note that support for enrolling multiple FIDO2 tokens is currently not too useful, as while 74 unlocking <command>systemd-cryptsetup</command> cannot identify which token is currently plugged in and 75 thus does not know which authentication request to send to the device. This limitation does not apply to 76 tokens enrolled via PKCS#11 — because tokens of this type may be identified immediately, before 77 authentication.</para> 78 </refsect1> 79 80 <refsect1> 81 <title>Options</title> 82 83 <para>The following options are understood:</para> 84 85 <variablelist> 86 <varlistentry> 87 <term><option>--password</option></term> 88 89 <listitem><para>Enroll a regular password/passphrase. This command is mostly equivalent to 90 <command>cryptsetup luksAddKey</command>, however may be combined with 91 <option>--wipe-slot=</option> in one call, see below.</para></listitem> 92 </varlistentry> 93 94 <varlistentry> 95 <term><option>--recovery-key</option></term> 96 97 <listitem><para>Enroll a recovery key. Recovery keys are mostly identical to passphrases, but are 98 computer-generated instead of being chosen by a human, and thus have a guaranteed high entropy. The 99 key uses a character set that is easy to type in, and may be scanned off screen via a QR code. 100 </para></listitem> 101 </varlistentry> 102 103 <varlistentry> 104 <term><option>--pkcs11-token-uri=</option><replaceable>URI</replaceable></term> 105 106 <listitem><para>Enroll a PKCS#11 security token or smartcard (e.g. a YubiKey). Expects a PKCS#11 107 smartcard URI referring to the token. Alternatively the special value <literal>auto</literal> may 108 be specified, in order to automatically determine the URI of a currently plugged in security token 109 (of which there must be exactly one). The special value <literal>list</literal> may be used to 110 enumerate all suitable PKCS#11 tokens currently plugged in. The security token must contain an RSA 111 key pair which is used to encrypt the randomly generated key that is used to unlock the LUKS2 112 volume. The encrypted key is then stored in the LUKS2 JSON token header area.</para> 113 114 <para>In order to unlock a LUKS2 volume with an enrolled PKCS#11 security token, specify the 115 <option>pkcs11-uri=</option> option in the respective <filename>/etc/crypttab</filename> line:</para> 116 117 <programlisting>myvolume /dev/sda1 - pkcs11-uri=auto</programlisting> 118 119 <para>See 120 <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a 121 more comprehensive example of a <command>systemd-cryptenroll</command> invocation and its matching 122 <filename>/etc/crypttab</filename> line.</para></listitem> 123 </varlistentry> 124 125 <varlistentry> 126 <term><option>--fido2-credential-algorithm=</option><replaceable>STRING</replaceable></term> 127 <listitem><para>Specify COSE algorithm used in credential generation. The default value is 128 <literal>es256</literal>. Supported values are <literal>es256</literal>, <literal>rs256</literal> 129 and <literal>eddsa</literal>.</para> 130 131 <para><literal>es256</literal> denotes ECDSA over NIST P-256 with SHA-256. <literal>rs256</literal> 132 denotes 2048-bit RSA with PKCS#1.5 padding and SHA-256. <literal>eddsa</literal> denotes 133 EDDSA over Curve25519 with SHA-512.</para> 134 135 <para>Note that your authenticator may not support some algorithms.</para></listitem> 136 </varlistentry> 137 138 <varlistentry> 139 <term><option>--fido2-device=</option><replaceable>PATH</replaceable></term> 140 141 <listitem><para>Enroll a FIDO2 security token that implements the <literal>hmac-secret</literal> 142 extension (e.g. a YubiKey). Expects a <filename>hidraw</filename> device referring to the FIDO2 143 device (e.g. <filename>/dev/hidraw1</filename>). Alternatively the special value 144 <literal>auto</literal> may be specified, in order to automatically determine the device node of a 145 currently plugged in security token (of which there must be exactly one). The special value 146 <literal>list</literal> may be used to enumerate all suitable FIDO2 tokens currently plugged in. Note 147 that many hardware security tokens that implement FIDO2 also implement the older PKCS#11 148 standard. Typically FIDO2 is preferable, given it's simpler to use and more modern.</para> 149 150 <para>In order to unlock a LUKS2 volume with an enrolled FIDO2 security token, specify the 151 <option>fido2-device=</option> option in the respective <filename>/etc/crypttab</filename> line:</para> 152 153 <programlisting>myvolume /dev/sda1 - fido2-device=auto</programlisting> 154 155 <para>See 156 <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a 157 more comprehensive example of a <command>systemd-cryptenroll</command> invocation and its matching 158 <filename>/etc/crypttab</filename> line.</para></listitem> 159 </varlistentry> 160 161 <varlistentry> 162 <term><option>--fido2-with-client-pin=</option><replaceable>BOOL</replaceable></term> 163 164 <listitem><para>When enrolling a FIDO2 security token, controls whether to require the user to enter 165 a PIN when unlocking the volume (the FIDO2 <literal>clientPin</literal> feature). Defaults to 166 <literal>yes</literal>. (Note: this setting is without effect if the security token does not support 167 the <literal>clientPin</literal> feature at all, or does not allow enabling or disabling 168 it.)</para></listitem> 169 </varlistentry> 170 171 <varlistentry> 172 <term><option>--fido2-with-user-presence=</option><replaceable>BOOL</replaceable></term> 173 174 <listitem><para>When enrolling a FIDO2 security token, controls whether to require the user to 175 verify presence (tap the token, the FIDO2 <literal>up</literal> feature) when unlocking the volume. 176 Defaults to <literal>yes</literal>. (Note: this setting is without effect if the security token does not support 177 the <literal>up</literal> feature at all, or does not allow enabling or disabling it.) 178 </para></listitem> 179 </varlistentry> 180 181 <varlistentry> 182 <term><option>--fido2-with-user-verification=</option><replaceable>BOOL</replaceable></term> 183 184 <listitem><para>When enrolling a FIDO2 security token, controls whether to require user verification 185 when unlocking the volume (the FIDO2 <literal>uv</literal> feature). Defaults to 186 <literal>no</literal>. (Note: this setting is without effect if the security token does not support 187 the <literal>uv</literal> feature at all, or does not allow enabling or disabling it.)</para></listitem> 188 </varlistentry> 189 190 <varlistentry> 191 <term><option>--tpm2-device=</option><replaceable>PATH</replaceable></term> 192 193 <listitem><para>Enroll a TPM2 security chip. Expects a device node path referring to the TPM2 chip 194 (e.g. <filename>/dev/tpmrm0</filename>). Alternatively the special value <literal>auto</literal> may 195 be specified, in order to automatically determine the device node of a currently discovered TPM2 196 device (of which there must be exactly one). The special value <literal>list</literal> may be used to 197 enumerate all suitable TPM2 devices currently discovered.</para> 198 199 <para>In order to unlock a LUKS2 volume with an enrolled TPM2 security chip, specify the 200 <option>tpm2-device=</option> option in the respective <filename>/etc/crypttab</filename> line:</para> 201 202 <programlisting>myvolume /dev/sda1 - tpm2-device=auto</programlisting> 203 204 <para>See 205 <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a 206 more comprehensive example of a <command>systemd-cryptenroll</command> invocation and its matching 207 <filename>/etc/crypttab</filename> line.</para> 208 209 <para>Use <option>--tpm2-pcrs=</option> (see below) to configure which TPM2 PCR indexes to bind the 210 enrollment to.</para></listitem> 211 </varlistentry> 212 213 <varlistentry> 214 <term><option>--tpm2-pcrs=</option><arg rep="repeat">PCR</arg></term> 215 216 <listitem><para>Configures the TPM2 PCRs (Platform Configuration Registers) to bind the enrollment 217 requested via <option>--tpm2-device=</option> to. Takes a <literal>+</literal> separated list of 218 numeric PCR indexes in the range 0…23. If not used, defaults to PCR 7 only. If an empty string is 219 specified, binds the enrollment to no PCRs at all. PCRs allow binding the enrollment to specific 220 software versions and system state, so that the enrolled unlocking key is only accessible (may be 221 "unsealed") if specific trusted software and/or configuration is used.</para> 222 223 <table> 224 <title>Well-known PCR Definitions</title> 225 226 <!-- See: https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/ --> 227 <!-- See: https://github.com/rhboot/shim/blob/main/README.tpm --> 228 <!-- See: https://www.gnu.org/software/grub/manual/grub/html_node/Measured-Boot.html --> 229 <!-- See: https://sourceforge.net/p/linux-ima/wiki/Home/ --> 230 <!-- See: https://github.com/tianocore-docs/edk2-TrustedBootChain/blob/main/4_Other_Trusted_Boot_Chains.md --> 231 <!-- See: https://wiki.archlinux.org/title/Trusted_Platform_Module#Accessing_PCR_registers --> 232 233 <tgroup cols='2' align='left' colsep='1' rowsep='1'> 234 <colspec colname="pcr" /> 235 <colspec colname="definition" /> 236 237 <thead> 238 <row> 239 <entry>PCR</entry> 240 <entry>Explanation</entry> 241 </row> 242 </thead> 243 244 <tbody> 245 <row> 246 <entry>0</entry> 247 <entry>Core system firmware executable code; changes on firmware updates</entry> 248 </row> 249 250 <row> 251 <entry>1</entry> 252 <entry>Core system firmware data/host platform configuration; typically contains serial and model numbers, changes on basic hardware/CPU/RAM replacements</entry> 253 </row> 254 255 <row> 256 <entry>2</entry> 257 <entry>Extended or pluggable executable code; includes option ROMs on pluggable hardware</entry> 258 </row> 259 260 <row> 261 <entry>3</entry> 262 <entry>Extended or pluggable firmware data; includes information about pluggable hardware</entry> 263 </row> 264 265 <row> 266 <entry>4</entry> 267 <entry>Boot loader and additional drivers; changes on boot loader updates. The shim project will measure the PE binary it chain loads into this PCR. If the Linux kernel is invoked as UEFI PE binary, it is measured here, too. <citerefentry><refentrytitle>sd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures system extension images read from the ESP here too (see <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>).</entry> 268 </row> 269 270 <row> 271 <entry>5</entry> 272 <entry>GPT/Partition table; changes when the partitions are added, modified or removed</entry> 273 </row> 274 275 <row> 276 <entry>6</entry> 277 <entry>Power state events; changes on system suspend/sleep</entry> 278 </row> 279 280 <row> 281 <entry>7</entry> 282 <entry>Secure boot state; changes when UEFI SecureBoot mode is enabled/disabled, or firmware certificates (PK, KEK, db, dbx, …) changes. The shim project will measure most of its (non-MOK) certificates and SBAT data into this PCR.</entry> 283 </row> 284 285 <!-- Grub measures all its commands and the kernel command line into PCR 8… --> 286 <!-- Grub measures all files it reads (including kernel image, initrd, …) into PCR 9… --> 287 288 <row> 289 <entry>9</entry> 290 <entry>The Linux kernel measures all initial RAM file systems it receives into this PCR.</entry> 291 <!-- Strictly speaking only Linux >= 5.17 using the LOAD_FILE2 protocol, see https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f046fff8bc4c4d8f8a478022e76e40b818f692df --> 292 </row> 293 294 <row> 295 <entry>10</entry> 296 <entry>The IMA project measures its runtime state into this PCR.</entry> 297 </row> 298 299 <row> 300 <entry>12</entry> 301 <entry><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures any specified kernel command line into this PCR. <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures any manually specified kernel command line (i.e. a kernel command line that overrides the one embedded in the unified PE image) and loaded credentials into this PCR. (Note that if <command>sytemd-boot</command> and <command>systemd-stub</command> are used in combination the command line might be measured twice!)</entry> 302 </row> 303 304 <row> 305 <entry>14</entry> 306 <entry>The shim project measures its "MOK" certificates and hashes into this PCR.</entry> 307 </row> 308 </tbody> 309 </tgroup> 310 </table> 311 312 <para>For most applications it should be sufficient to bind against PCR 7 (and possibly PCR 14, if 313 shim/MOK is desired), as this includes measurements of the trusted certificates (and possibly hashes) 314 that are used to validate all components of the boot process up to and including the OS kernel. In 315 order to simplify firmware and OS version updates it's typically not advisable to include PCRs such 316 as 0 and 2 in the binding of the enrollment, since the program code they cover should already be 317 protected indirectly through the certificates measured into PCR 7. Validation through these 318 certificates is typically preferable over validation through direct measurements as it is less 319 brittle in context of OS/firmware updates: the measurements will change on every update, but code 320 signatures likely will validate against pre-existing certificates.</para></listitem> 321 </varlistentry> 322 323 <varlistentry> 324 <term><option>--tpm2-with-pin=</option><replaceable>BOOL</replaceable></term> 325 326 <listitem><para>When enrolling a TPM2 device, controls whether to require the user to enter a PIN 327 when unlocking the volume in addition to PCR binding, based on TPM2 policy authentication. Defaults 328 to <literal>no</literal>. Despite being called PIN, any character can be used, not just numbers. 329 </para> 330 331 <para>Note that incorrect PIN entry when unlocking increments the 332 TPM dictionary attack lockout mechanism, and may lock out users for a prolonged time, depending on 333 its configuration. The lockout mechanism is a global property of the TPM, 334 <command>systemd-cryptenroll</command> does not control or configure the lockout mechanism. You may 335 use tpm2-tss tools to inspect or configure the dictionary attack lockout, with 336 <citerefentry project='mankier'><refentrytitle>tpm2_getcap</refentrytitle><manvolnum>1</manvolnum></citerefentry> and 337 <citerefentry project='mankier'><refentrytitle>tpm2_dictionarylockout</refentrytitle><manvolnum>1</manvolnum></citerefentry> 338 commands, respectively.</para></listitem> 339 </varlistentry> 340 341 <varlistentry> 342 <term><option>--wipe-slot=</option><arg rep="repeat">SLOT</arg></term> 343 344 <listitem><para>Wipes one or more LUKS2 key slots. Takes a comma separated list of numeric slot 345 indexes, or the special strings <literal>all</literal> (for wiping all key slots), 346 <literal>empty</literal> (for wiping all key slots that are unlocked by an empty passphrase), 347 <literal>password</literal> (for wiping all key slots that are unlocked by a traditional passphrase), 348 <literal>recovery</literal> (for wiping all key slots that are unlocked by a recovery key), 349 <literal>pkcs11</literal> (for wiping all key slots that are unlocked by a PKCS#11 token), 350 <literal>fido2</literal> (for wiping all key slots that are unlocked by a FIDO2 token), 351 <literal>tpm2</literal> (for wiping all key slots that are unlocked by a TPM2 chip), or any 352 combination of these strings or numeric indexes, in which case all slots matching either are 353 wiped. As safety precaution an operation that wipes all slots without exception (so that the volume 354 cannot be unlocked at all anymore, unless the volume key is known) is refused.</para> 355 356 <para>This switch may be used alone, in which case only the requested wipe operation is executed. It 357 may also be used in combination with any of the enrollment options listed above, in which case the 358 enrollment is completed first, and only when successful the wipe operation executed — and the newly 359 added slot is always excluded from the wiping. Combining enrollment and slot wiping may thus be used to 360 update existing enrollments:</para> 361 362 <programlisting>systemd-cryptenroll /dev/sda1 --wipe-slot=tpm2 --tpm2-device=auto</programlisting> 363 364 <para>The above command will enroll the TPM2 chip, and then wipe all previously created TPM2 365 enrollments on the LUKS2 volume, leaving only the newly created one. Combining wiping and enrollment 366 may also be used to replace enrollments of different types, for example for changing from a PKCS#11 367 enrollment to a FIDO2 one:</para> 368 369 <programlisting>systemd-cryptenroll /dev/sda1 --wipe-slot=pkcs11 --fido2-device=auto</programlisting> 370 371 <para>Or for replacing an enrolled empty password by TPM2:</para> 372 373 <programlisting>systemd-cryptenroll /dev/sda1 --wipe-slot=empty --tpm2-device=auto</programlisting> 374 </listitem> 375 </varlistentry> 376 377 <xi:include href="standard-options.xml" xpointer="help" /> 378 <xi:include href="standard-options.xml" xpointer="version" /> 379 </variablelist> 380 381 </refsect1> 382 383 <refsect1> 384 <title>Exit status</title> 385 386 <para>On success, 0 is returned, a non-zero failure code otherwise.</para> 387 </refsect1> 388 389 <refsect1> 390 <title>See Also</title> 391 <para> 392 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 393 <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 394 <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 395 <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> 396 </para> 397 </refsect1> 398 399</refentry> 400