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<!-- 6 SPDX-License-Identifier: LGPL-2.1-or-later 7 8 This is based on crypttab(5) from Fedora's initscripts package, which in 9 turn is based on Debian's version. 10 11 The Red Hat version has been written by Miloslav Trmac <mitr@redhat.com>. 12--> 13<refentry id="crypttab" conditional='HAVE_LIBCRYPTSETUP' xmlns:xi="http://www.w3.org/2001/XInclude"> 14 15 <refentryinfo> 16 <title>crypttab</title> 17 <productname>systemd</productname> 18 </refentryinfo> 19 20 <refmeta> 21 <refentrytitle>crypttab</refentrytitle> 22 <manvolnum>5</manvolnum> 23 </refmeta> 24 25 <refnamediv> 26 <refname>crypttab</refname> 27 <refpurpose>Configuration for encrypted block devices</refpurpose> 28 </refnamediv> 29 30 <refsynopsisdiv> 31 <para><filename>/etc/crypttab</filename></para> 32 </refsynopsisdiv> 33 34 <refsect1> 35 <title>Description</title> 36 37 <para>The <filename>/etc/crypttab</filename> file describes 38 encrypted block devices that are set up during system boot.</para> 39 40 <para>Empty lines and lines starting with the <literal>#</literal> 41 character are ignored. Each of the remaining lines describes one 42 encrypted block device. Fields are delimited by white space.</para> 43 44 <para>Each line is in the form<programlisting><replaceable>volume-name</replaceable> <replaceable>encrypted-device</replaceable> <replaceable>key-file</replaceable> <replaceable>options</replaceable></programlisting> 45 The first two fields are mandatory, the remaining two are 46 optional.</para> 47 48 <para>Setting up encrypted block devices using this file supports four encryption modes: LUKS, TrueCrypt, 49 BitLocker and plain. See <citerefentry 50 project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for 51 more information about each mode. When no mode is specified in the options field and the block device 52 contains a LUKS signature, it is opened as a LUKS device; otherwise, it is assumed to be in raw dm-crypt 53 (plain mode) format.</para> 54 55 <para>The four fields of <filename>/etc/crypttab</filename> are defined as follows:</para> 56 57 <orderedlist> 58 59 <listitem><para>The first field contains the name of the resulting volume with decrypted data; its 60 block device is set up below <filename>/dev/mapper/</filename>.</para></listitem> 61 62 <listitem><para>The second field contains a path to the underlying block 63 device or file, or a specification of a block device via 64 <literal>UUID=</literal> followed by the UUID.</para></listitem> 65 66 <listitem><para>The third field specifies an absolute path to a file with the encryption 67 key. Optionally, the path may be followed by <literal>:</literal> and an 68 <filename>/etc/fstab</filename> style device specification (e.g. starting with 69 <literal>LABEL=</literal> or similar); in which case the path is taken relative to the specified 70 device's file system root. If the field is not present or is <literal>none</literal> or 71 <literal>-</literal>, a key file named after the volume to unlock (i.e. the first column of the line), 72 suffixed with <filename>.key</filename> is automatically loaded from the 73 <filename>/etc/cryptsetup-keys.d/</filename> and <filename>/run/cryptsetup-keys.d/</filename> 74 directories, if present. Otherwise, the password has to be manually entered during system boot. For 75 swap encryption, <filename>/dev/urandom</filename> may be used as key file, resulting in a randomized 76 key.</para> 77 78 <para>If the specified key file path refers to an <constant>AF_UNIX</constant> stream socket in the 79 file system, the key is acquired by connecting to the socket and reading it from the connection. This 80 allows the implementation of a service to provide key information dynamically, at the moment when it is 81 needed. For details see below.</para></listitem> 82 83 <listitem><para>The fourth field, if present, is a comma-delimited list of options. The supported 84 options are listed below.</para></listitem> 85 </orderedlist> 86 </refsect1> 87 88 <refsect1> 89 <title>Key Acquisition</title> 90 91 <para>Six different mechanisms for acquiring the decryption key or passphrase unlocking the encrypted 92 volume are supported. Specifically:</para> 93 94 <orderedlist> 95 96 <listitem><para>Most prominently, the user may be queried interactively during volume activation 97 (i.e. typically at boot), asking them to type in the necessary passphrase(s).</para></listitem> 98 99 <listitem><para>The (unencrypted) key may be read from a file on disk, possibly on removable media. The third field 100 of each line encodes the location, for details see above.</para></listitem> 101 102 <listitem><para>The (unencrypted) key may be requested from another service, by specifying an 103 <constant>AF_UNIX</constant> file system socket in place of a key file in the third field. For details 104 see above and below.</para></listitem> 105 106 <listitem><para>The key may be acquired via a PKCS#11 compatible hardware security token or 107 smartcard. In this case an encrypted key is stored on disk/removable media, acquired via 108 <constant>AF_UNIX</constant>, or stored in the LUKS2 JSON token metadata header. The encrypted key is 109 then decrypted by the PKCS#11 token with an RSA key stored on it, and then used to unlock the encrypted 110 volume. Use the <option>pkcs11-uri=</option> option described below to use this mechanism.</para></listitem> 111 112 <listitem><para>Similar, the key may be acquired via a FIDO2 compatible hardware security token (which 113 must implement the "hmac-secret" extension). In this case a (during enrollment) randomly generated key 114 is stored on disk/removable media, acquired via <constant>AF_UNIX</constant>, or stored in the LUKS2 115 JSON token metadata header. The random key is hashed via a keyed hash function (HMAC) on the FIDO2 116 token, using a secret key stored on the token that never leaves it. The resulting hash value is then 117 used as key to unlock the encrypted volume. Use the <option>fido2-device=</option> option described 118 below to use this mechanism.</para></listitem> 119 120 <listitem><para>Similar, the key may be acquired via a TPM2 security chip. In this case a (during 121 enrollment) randomly generated key — encrypted by an asymmetric key derived from the TPM2 chip's seed 122 key — is stored on disk/removable media, acquired via <constant>AF_UNIX</constant>, or stored in the 123 LUKS2 JSON token metadata header. Use the <option>tpm2-device=</option> option described below to use 124 this mechanism.</para></listitem> 125 </orderedlist> 126 127 <para>For the latter five mechanisms the source for the key material used for unlocking the volume is 128 primarily configured in the third field of each <filename>/etc/crypttab</filename> line, but may also 129 configured in <filename>/etc/cryptsetup-keys.d/</filename> and 130 <filename>/run/cryptsetup-keys.d/</filename> (see above) or in the LUKS2 JSON token header (in case of 131 the latter three). Use the 132 <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> 133 tool to enroll PKCS#11, FIDO2 and TPM2 devices in LUKS2 volumes.</para> 134 </refsect1> 135 136 <refsect1> 137 <title>Supported Options</title> 138 139 <para>The following options may be used in the fourth field of each line:</para> 140 141 <variablelist class='fstab-options'> 142 143 <varlistentry> 144 <term><option>cipher=</option></term> 145 146 <listitem><para>Specifies the cipher to use. See <citerefentry 147 project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> 148 for possible values and the default value of this option. A cipher with unpredictable IV values, such 149 as <literal>aes-cbc-essiv:sha256</literal>, is recommended. Embedded commas in the cipher 150 specification need to be escaped by preceding them with a backslash, see example below.</para> 151 </listitem> 152 </varlistentry> 153 154 <varlistentry> 155 <term><option>discard</option></term> 156 157 <listitem><para>Allow discard requests to be passed through the encrypted block 158 device. This improves performance on SSD storage but has security implications. 159 </para></listitem> 160 </varlistentry> 161 162 <varlistentry> 163 <term><option>hash=</option></term> 164 165 <listitem><para>Specifies the hash to use for password 166 hashing. See 167 <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> 168 for possible values and the default value of this 169 option.</para></listitem> 170 </varlistentry> 171 172 <varlistentry> 173 <term><option>header=</option></term> 174 175 <listitem><para>Use a detached (separated) metadata device or 176 file where the LUKS header is stored. This option is only 177 relevant for LUKS devices. See 178 <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> 179 for possible values and the default value of this 180 option.</para> 181 182 <para>Optionally, the path may be followed by <literal>:</literal> and an 183 <filename>/etc/fstab</filename> device specification (e.g. starting with <literal>UUID=</literal> or 184 similar); in which case, the path is relative to the device file system root. The device gets mounted 185 automatically for LUKS device activation duration only.</para></listitem> 186 </varlistentry> 187 188 <varlistentry> 189 <term><option>keyfile-offset=</option></term> 190 191 <listitem><para>Specifies the number of bytes to skip at the 192 start of the key file. See 193 <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> 194 for possible values and the default value of this 195 option.</para></listitem> 196 </varlistentry> 197 198 <varlistentry> 199 <term><option>keyfile-size=</option></term> 200 201 <listitem><para>Specifies the maximum number of bytes to read 202 from the key file. See 203 <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> 204 for possible values and the default value of this option. This 205 option is ignored in plain encryption mode, as the key file 206 size is then given by the key size.</para></listitem> 207 </varlistentry> 208 209 <varlistentry> 210 <term><option>keyfile-erase</option></term> 211 212 <listitem><para>If enabled, the specified key file is erased after the volume is activated or when 213 activation fails. This is in particular useful when the key file is only acquired transiently before 214 activation (e.g. via a file in <filename>/run/</filename>, generated by a service running before 215 activation), and shall be removed after use. Defaults to off.</para></listitem> 216 </varlistentry> 217 218 <varlistentry> 219 <term><option>key-slot=</option></term> 220 221 <listitem><para>Specifies the key slot to compare the 222 passphrase or key against. If the key slot does not match the 223 given passphrase or key, but another would, the setup of the 224 device will fail regardless. This option implies 225 <option>luks</option>. See 226 <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> 227 for possible values. The default is to try all key slots in 228 sequential order.</para></listitem> 229 </varlistentry> 230 231 <varlistentry> 232 <term><option>keyfile-timeout=</option></term> 233 234 <listitem><para> Specifies the timeout for the device on 235 which the key file resides and falls back to a password if 236 it could not be mounted. See 237 <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> 238 for key files on external devices. 239 </para></listitem> 240 </varlistentry> 241 242 <varlistentry> 243 <term><option>luks</option></term> 244 245 <listitem><para>Force LUKS mode. When this mode is used, the 246 following options are ignored since they are provided by the 247 LUKS header on the device: <option>cipher=</option>, 248 <option>hash=</option>, 249 <option>size=</option>.</para></listitem> 250 </varlistentry> 251 252 <varlistentry> 253 <term><option>bitlk</option></term> 254 255 <listitem><para>Decrypt BitLocker drive. Encryption parameters 256 are deduced by cryptsetup from BitLocker header.</para></listitem> 257 </varlistentry> 258 259 <varlistentry> 260 <term><option>_netdev</option></term> 261 262 <listitem><para>Marks this cryptsetup device as requiring network. It will be 263 started after the network is available, similarly to 264 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> 265 units marked with <option>_netdev</option>. The service unit to set up this device 266 will be ordered between <filename>remote-fs-pre.target</filename> and 267 <filename>remote-cryptsetup.target</filename>, instead of 268 <filename>cryptsetup-pre.target</filename> and 269 <filename>cryptsetup.target</filename>.</para> 270 271 <para>Hint: if this device is used for a mount point that is specified in 272 <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 273 the <option>_netdev</option> option should also be used for the mount 274 point. Otherwise, a dependency loop might be created where the mount point 275 will be pulled in by <filename>local-fs.target</filename>, while the 276 service to configure the network is usually only started <emphasis>after</emphasis> 277 the local file system has been mounted.</para> 278 </listitem> 279 </varlistentry> 280 281 <varlistentry> 282 <term><option>noauto</option></term> 283 284 <listitem><para>This device will not be added to <filename>cryptsetup.target</filename>. 285 This means that it will not be automatically unlocked on boot, unless something else pulls 286 it in. In particular, if the device is used for a mount point, it'll be unlocked 287 automatically during boot, unless the mount point itself is also disabled with 288 <option>noauto</option>.</para></listitem> 289 </varlistentry> 290 291 <varlistentry> 292 <term><option>nofail</option></term> 293 294 <listitem><para>This device will not be a hard dependency of 295 <filename>cryptsetup.target</filename>. It'll still be pulled in and started, but the system 296 will not wait for the device to show up and be unlocked, and boot will not fail if this is 297 unsuccessful. Note that other units that depend on the unlocked device may still fail. In 298 particular, if the device is used for a mount point, the mount point itself also needs to 299 have the <option>nofail</option> option, or the boot will fail if the device is not unlocked 300 successfully.</para></listitem> 301 </varlistentry> 302 303 <varlistentry> 304 <term><option>offset=</option></term> 305 306 <listitem><para>Start offset in the backend device, in 512-byte sectors. This 307 option is only relevant for plain devices.</para></listitem> 308 </varlistentry> 309 310 <varlistentry> 311 <term><option>plain</option></term> 312 313 <listitem><para>Force plain encryption mode.</para></listitem> 314 </varlistentry> 315 316 <varlistentry> 317 <term><option>read-only</option></term><term><option>readonly</option></term> 318 319 <listitem><para>Set up the encrypted block device in read-only 320 mode.</para></listitem> 321 </varlistentry> 322 323 <varlistentry> 324 <term><option>same-cpu-crypt</option></term> 325 326 <listitem><para>Perform encryption using the same CPU that IO was submitted on. The default is to use 327 an unbound workqueue so that encryption work is automatically balanced between available CPUs.</para> 328 329 <para>This requires kernel 4.0 or newer.</para> 330 </listitem> 331 </varlistentry> 332 333 <varlistentry> 334 <term><option>submit-from-crypt-cpus</option></term> 335 336 <listitem><para>Disable offloading writes to a separate thread after encryption. There are some 337 situations where offloading write requests from the encryption threads to a dedicated thread degrades 338 performance significantly. The default is to offload write requests to a dedicated thread because it 339 benefits the CFQ scheduler to have writes submitted using the same context.</para> 340 341 <para>This requires kernel 4.0 or newer.</para> 342 </listitem> 343 </varlistentry> 344 345 <varlistentry> 346 <term><option>no-read-workqueue</option></term> 347 348 <listitem><para>Bypass dm-crypt internal workqueue and process read requests synchronously. The 349 default is to queue these requests and process them asynchronously.</para> 350 351 <para>This requires kernel 5.9 or newer.</para> 352 </listitem> 353 </varlistentry> 354 <varlistentry> 355 <term><option>no-write-workqueue</option></term> 356 357 <listitem><para>Bypass dm-crypt internal workqueue and process write requests synchronously. The 358 default is to queue these requests and process them asynchronously.</para> 359 360 <para>This requires kernel 5.9 or newer.</para> 361 </listitem> 362 </varlistentry> 363 364 <varlistentry> 365 <term><option>skip=</option></term> 366 367 <listitem><para>How many 512-byte sectors of the encrypted data to skip at the 368 beginning. This is different from the <option>offset=</option> option with respect 369 to the sector numbers used in initialization vector (IV) calculation. Using 370 <option>offset=</option> will shift the IV calculation by the same negative 371 amount. Hence, if <option>offset=<replaceable>n</replaceable></option> is given, 372 sector <replaceable>n</replaceable> will get a sector number of 0 for the IV 373 calculation. Using <option>skip=</option> causes sector 374 <replaceable>n</replaceable> to also be the first sector of the mapped device, but 375 with its number for IV generation being <replaceable>n</replaceable>.</para> 376 377 <para>This option is only relevant for plain devices.</para> 378 </listitem> 379 </varlistentry> 380 381 <varlistentry> 382 <term><option>size=</option></term> 383 384 <listitem><para>Specifies the key size in bits. See 385 <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> 386 for possible values and the default value of this 387 option.</para></listitem> 388 </varlistentry> 389 390 <varlistentry> 391 <term><option>sector-size=</option></term> 392 393 <listitem><para>Specifies the sector size in bytes. See 394 <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> 395 for possible values and the default value of this 396 option.</para></listitem> 397 </varlistentry> 398 399 <varlistentry> 400 <term><option>swap</option></term> 401 402 <listitem><para>The encrypted block device will be used as a 403 swap device, and will be formatted accordingly after setting 404 up the encrypted block device, with 405 <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>. 406 This option implies <option>plain</option>.</para> 407 408 <para>WARNING: Using the <option>swap</option> option will 409 destroy the contents of the named partition during every boot, 410 so make sure the underlying block device is specified 411 correctly.</para></listitem> 412 </varlistentry> 413 414 <varlistentry> 415 <term><option>tcrypt</option></term> 416 417 <listitem><para>Use TrueCrypt encryption mode. When this mode 418 is used, the following options are ignored since they are 419 provided by the TrueCrypt header on the device or do not 420 apply: 421 <option>cipher=</option>, 422 <option>hash=</option>, 423 <option>keyfile-offset=</option>, 424 <option>keyfile-size=</option>, 425 <option>size=</option>.</para> 426 427 <para>When this mode is used, the passphrase is read from the 428 key file given in the third field. Only the first line of this 429 file is read, excluding the new line character.</para> 430 431 <para>Note that the TrueCrypt format uses both passphrase and 432 key files to derive a password for the volume. Therefore, the 433 passphrase and all key files need to be provided. Use 434 <option>tcrypt-keyfile=</option> to provide the absolute path 435 to all key files. When using an empty passphrase in 436 combination with one or more key files, use 437 <literal>/dev/null</literal> as the password file in the third 438 field.</para></listitem> 439 </varlistentry> 440 441 <varlistentry> 442 <term><option>tcrypt-hidden</option></term> 443 444 <listitem><para>Use the hidden TrueCrypt volume. This option 445 implies <option>tcrypt</option>.</para> 446 447 <para>This will map the hidden volume that is inside of the 448 volume provided in the second field. Please note that there is 449 no protection for the hidden volume if the outer volume is 450 mounted instead. See 451 <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> 452 for more information on this limitation.</para></listitem> 453 </varlistentry> 454 455 <varlistentry> 456 <term><option>tcrypt-keyfile=</option></term> 457 458 <listitem><para>Specifies the absolute path to a key file to 459 use for a TrueCrypt volume. This implies 460 <option>tcrypt</option> and can be used more than once to 461 provide several key files.</para> 462 463 <para>See the entry for <option>tcrypt</option> on the 464 behavior of the passphrase and key files when using TrueCrypt 465 encryption mode.</para></listitem> 466 </varlistentry> 467 468 <varlistentry> 469 <term><option>tcrypt-system</option></term> 470 471 <listitem><para>Use TrueCrypt in system encryption mode. This 472 option implies <option>tcrypt</option>.</para></listitem> 473 </varlistentry> 474 475 <varlistentry> 476 <term><option>tcrypt-veracrypt</option></term> 477 478 <listitem><para>Check for a VeraCrypt volume. VeraCrypt is a fork of 479 TrueCrypt that is mostly compatible, but uses different, stronger key 480 derivation algorithms that cannot be detected without this flag. 481 Enabling this option could substantially slow down unlocking, because 482 VeraCrypt's key derivation takes much longer than TrueCrypt's. This 483 option implies <option>tcrypt</option>.</para></listitem> 484 </varlistentry> 485 486 <varlistentry> 487 <term><option>timeout=</option></term> 488 489 <listitem><para>Specifies the timeout for querying for a 490 password. If no unit is specified, seconds is used. Supported 491 units are s, ms, us, min, h, d. A timeout of 0 waits 492 indefinitely (which is the default).</para></listitem> 493 </varlistentry> 494 495 <varlistentry> 496 <term><option>tmp=</option></term> 497 498 <listitem><para>The encrypted block device will be prepared for using it as 499 <filename>/tmp/</filename>; it will be formatted using <citerefentry 500 project='man-pages'><refentrytitle>mkfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes 501 a file system type as argument, such as <literal>ext4</literal>, <literal>xfs</literal> or 502 <literal>btrfs</literal>. If no argument is specified defaults to <literal>ext4</literal>. This 503 option implies <option>plain</option>.</para> 504 505 <para>WARNING: Using the <option>tmp</option> option will destroy the contents of the named partition 506 during every boot, so make sure the underlying block device is specified correctly.</para></listitem> 507 </varlistentry> 508 509 <varlistentry> 510 <term><option>tries=</option></term> 511 512 <listitem><para>Specifies the maximum number of times the user 513 is queried for a password. The default is 3. If set to 0, the 514 user is queried for a password indefinitely.</para></listitem> 515 </varlistentry> 516 517 <varlistentry> 518 <term><option>headless=</option></term> 519 520 <listitem><para>Takes a boolean argument, defaults to false. If true, never query interactively 521 for the password/PIN. Useful for headless systems.</para></listitem> 522 </varlistentry> 523 524 <varlistentry> 525 <term><option>verify</option></term> 526 527 <listitem><para>If the encryption password is read from console, it has to be entered twice to 528 prevent typos.</para></listitem> 529 </varlistentry> 530 531 <varlistentry> 532 <term><option>password-echo=yes|no|masked</option></term> 533 534 <listitem><para>Controls whether to echo passwords or security token PINs 535 that are read from console. Takes a boolean or the special string <literal>masked</literal>. 536 The default is <option>password-echo=masked</option>.</para> 537 538 <para>If enabled, the typed characters are echoed literally. If disabled, 539 the typed characters are not echoed in any form, the user will not get 540 feedback on their input. If set to <literal>masked</literal>, an asterisk 541 (<literal>*</literal>) is echoed for each character typed. Regardless of 542 which mode is chosen, if the user hits the tabulator key (<literal>↹</literal>) 543 at any time, or the backspace key (<literal>⌫</literal>) before any other 544 data has been entered, then echo is turned off.</para></listitem> 545 </varlistentry> 546 547 <varlistentry> 548 <term><option>pkcs11-uri=</option></term> 549 550 <listitem><para>Takes either the special value <literal>auto</literal> or an <ulink 551 url="https://tools.ietf.org/html/rfc7512">RFC7512 PKCS#11 URI</ulink> pointing to a private RSA key 552 which is used to decrypt the encrypted key specified in the third column of the line. This is useful 553 for unlocking encrypted volumes through PKCS#11 compatible security tokens or smartcards. See below 554 for an example how to set up this mechanism for unlocking a LUKS2 volume with a YubiKey security 555 token.</para> 556 557 <para>If specified as <literal>auto</literal> the volume must be of type LUKS2 and must carry PKCS#11 558 security token metadata in its LUKS2 JSON token section. In this mode the URI and the encrypted key 559 are automatically read from the LUKS2 JSON token header. Use 560 <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> 561 as simple tool for enrolling PKCS#11 security tokens or smartcards in a way compatible with 562 <literal>auto</literal>. In this mode the third column of the line should remain empty (that is, 563 specified as <literal>-</literal>).</para> 564 565 <para>The specified URI can refer directly to a private RSA key stored on a token or alternatively 566 just to a slot or token, in which case a search for a suitable private RSA key will be performed. In 567 this case if multiple suitable objects are found the token is refused. The encrypted key configured 568 in the third column of the line is passed as is (i.e. in binary form, unprocessed) to RSA 569 decryption. The resulting decrypted key is then Base64 encoded before it is used to unlock the LUKS 570 volume.</para> 571 572 <para>Use <command>systemd-cryptenroll --pkcs11-token-uri=list</command> to list all suitable PKCS#11 573 security tokens currently plugged in, along with their URIs.</para> 574 575 <para>Note that many newer security tokens that may be used as PKCS#11 security token typically also 576 implement the newer and simpler FIDO2 standard. Consider using <option>fido2-device=</option> 577 (described below) to enroll it via FIDO2 instead. Note that a security token enrolled via PKCS#11 578 cannot be used to unlock the volume via FIDO2, unless also enrolled via FIDO2, and vice 579 versa.</para></listitem> 580 </varlistentry> 581 582 <varlistentry> 583 <term><option>fido2-device=</option></term> 584 585 <listitem><para>Takes either the special value <literal>auto</literal> or the path to a 586 <literal>hidraw</literal> device node (e.g. <filename>/dev/hidraw1</filename>) referring to a FIDO2 587 security token that implements the <literal>hmac-secret</literal> extension (most current hardware 588 security tokens do). See below for an example how to set up this mechanism for unlocking an encrypted 589 volume with a FIDO2 security token.</para> 590 591 <para>If specified as <literal>auto</literal> the FIDO2 token device is automatically discovered, as 592 it is plugged in.</para> 593 594 <para>FIDO2 volume unlocking requires a client ID hash (CID) to be configured via 595 <option>fido2-cid=</option> (see below) and a key to pass to the security token's HMAC functionality 596 (configured in the line's third column) to operate. If not configured and the volume is of type 597 LUKS2, the CID and the key are read from LUKS2 JSON token metadata instead. Use 598 <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> 599 as simple tool for enrolling FIDO2 security tokens, compatible with this automatic mode, which is 600 only available for LUKS2 volumes.</para> 601 602 <para>Use <command>systemd-cryptenroll --fido2-device=list</command> to list all suitable FIDO2 603 security tokens currently plugged in, along with their device nodes.</para> 604 605 <para>This option implements the following mechanism: the configured key is hashed via they HMAC 606 keyed hash function the FIDO2 device implements, keyed by a secret key embedded on the device. The 607 resulting hash value is Base64 encoded and used to unlock the LUKS2 volume. As it should not be 608 possible to extract the secret from the hardware token, it should not be possible to retrieve the 609 hashed key given the configured key — without possessing the hardware token.</para> 610 611 <para>Note that many security tokens that implement FIDO2 also implement PKCS#11, suitable for 612 unlocking volumes via the <option>pkcs11-uri=</option> option described above. Typically the newer, 613 simpler FIDO2 standard is preferable.</para></listitem> 614 </varlistentry> 615 616 <varlistentry> 617 <term><option>fido2-cid=</option></term> 618 619 <listitem><para>Takes a Base64 encoded FIDO2 client ID to use for the FIDO2 unlock operation. If 620 specified, but <option>fido2-device=</option> is not, <option>fido2-device=auto</option> is 621 implied. If <option>fido2-device=</option> is used but <option>fido2-cid=</option> is not, the volume 622 must be of LUKS2 type, and the CID is read from the LUKS2 JSON token header. Use 623 <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> 624 for enrolling a FIDO2 token in the LUKS2 header compatible with this automatic 625 mode.</para></listitem> 626 </varlistentry> 627 628 <varlistentry> 629 <term><option>fido2-rp=</option></term> 630 631 <listitem><para>Takes a string, configuring the FIDO2 Relying Party (rp) for the FIDO2 unlock 632 operation. If not specified <literal>io.systemd.cryptsetup</literal> is used, except if the LUKS2 633 JSON token header contains a different value. It should normally not be necessary to override 634 this.</para></listitem> 635 </varlistentry> 636 637 <varlistentry> 638 <term><option>tpm2-device=</option></term> 639 640 <listitem><para>Takes either the special value <literal>auto</literal> or the path to a device node 641 (e.g. <filename>/dev/tpmrm0</filename>) referring to a TPM2 security chip. See below for an example 642 how to set up this mechanism for unlocking an encrypted volume with a TPM2 chip.</para> 643 644 <para>Use <option>tpm2-pcrs=</option> (see below) to configure the set of TPM2 PCRs to bind the 645 volume unlocking to. Use 646 <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> 647 as simple tool for enrolling TPM2 security chips in LUKS2 volumes.</para> 648 649 <para>If specified as <literal>auto</literal> the TPM2 device is automatically discovered. Use 650 <command>systemd-cryptenroll --tpm2-device=list</command> to list all suitable TPM2 devices currently 651 available, along with their device nodes.</para> 652 653 <para>This option implements the following mechanism: when enrolling a TPM2 device via 654 <command>systemd-cryptenroll</command> on a LUKS2 volume, a randomized key unlocking the volume is 655 generated on the host and loaded into the TPM2 chip where it is encrypted with an asymmetric 656 "primary" key pair derived from the TPM2's internal "seed" key. Neither the seed key nor the primary 657 key are permitted to ever leave the TPM2 chip — however, the now encrypted randomized key may. It is 658 saved in the LUKS2 volume JSON token header. When unlocking the encrypted volume, the primary key 659 pair is generated on the TPM2 chip again (which works as long as the chip's seed key is correctly 660 maintained by the TPM2 chip), which is then used to decrypt (on the TPM2 chip) the encrypted key from 661 the LUKS2 volume JSON token header saved there during enrollment. The resulting decrypted key is then 662 used to unlock the volume. When the randomized key is encrypted the current values of the selected 663 PCRs (see below) are included in the operation, so that different PCR state results in different 664 encrypted keys and the decrypted key can only be recovered if the same PCR state is 665 reproduced.</para></listitem> 666 </varlistentry> 667 668 <varlistentry> 669 <term><option>tpm2-pcrs=</option></term> 670 671 <listitem><para>Takes a <literal>+</literal> separated list of numeric TPM2 PCR (i.e. "Platform 672 Configuration Register") indexes to bind the TPM2 volume unlocking to. This option is only useful 673 when TPM2 enrollment metadata is not available in the LUKS2 JSON token header already, the way 674 <command>systemd-cryptenroll</command> writes it there. If not used (and no metadata in the LUKS2 675 JSON token header defines it), defaults to a list of a single entry: PCR 7. Assign an empty string to 676 encode a policy that binds the key to no PCRs, making the key accessible to local programs regardless 677 of the current PCR state.</para></listitem> 678 </varlistentry> 679 680 <varlistentry> 681 <term><option>tpm2-pin=</option></term> 682 683 <listitem><para>Takes a boolean argument, defaults to <literal>false</literal>. Controls whether 684 TPM2 volume unlocking is bound to a PIN in addition to PCRs. Similarly, this option is only useful 685 when TPM2 enrollment metadata is not available.</para></listitem> 686 </varlistentry> 687 688 <varlistentry> 689 <term><option>token-timeout=</option></term> 690 691 <listitem><para>Specifies how long to wait at most for configured security devices (i.e. FIDO2, 692 PKCS#11, TPM2) to show up. Takes a time value in seconds (but other time units may be specified too, 693 see <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> 694 for supported formats). Defaults to 30s. Once the specified timeout elapsed authentication via 695 password is attempted. Note that this timeout applies to waiting for the security device to show up — 696 it does not apply to the PIN prompt for the device (should one be needed) or similar. Pass 0 to turn 697 off the time-out and wait forever.</para></listitem> 698 </varlistentry> 699 700 <varlistentry> 701 <term><option>try-empty-password=</option></term> 702 703 <listitem><para>Takes a boolean argument. If enabled, right before asking the user for a password it 704 is first attempted to unlock the volume with an empty password. This is useful for systems that are 705 initialized with an encrypted volume with only an empty password set, which shall be replaced with a 706 suitable password during first boot, but after activation.</para></listitem> 707 </varlistentry> 708 709 <varlistentry> 710 <term><option>x-systemd.device-timeout=</option></term> 711 712 <listitem><para>Specifies how long systemd should wait for a block device to show up before 713 giving up on the entry. The argument is a time in seconds or explicitly specified units of 714 <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>ms</literal>. 715 </para></listitem> 716 </varlistentry> 717 718 <varlistentry> 719 <term><option>x-initrd.attach</option></term> 720 721 <listitem><para>Setup this encrypted block device in the initramfs, similarly to 722 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> 723 units marked with <option>x-initrd.mount</option>.</para> 724 725 <para>Although it's not necessary to mark the mount entry for the root file system with 726 <option>x-initrd.mount</option>, <option>x-initrd.attach</option> is still recommended with 727 the encrypted block device containing the root file system as otherwise systemd will 728 attempt to detach the device during the regular system shutdown while it's still in 729 use. With this option the device will still be detached but later after the root file 730 system is unmounted.</para> 731 732 <para>All other encrypted block devices that contain file systems mounted in the initramfs 733 should use this option.</para> 734 </listitem> 735 </varlistentry> 736 737 </variablelist> 738 739 <para>At early boot and when the system manager configuration is 740 reloaded, this file is translated into native systemd units by 741 <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> 742 </refsect1> 743 744 <refsect1> 745 <title><constant>AF_UNIX</constant> Key Files</title> 746 747 <para>If the key file path (as specified in the third column of <filename>/etc/crypttab</filename> 748 entries, see above) refers to an <constant>AF_UNIX</constant> stream socket in the file system, the key 749 is acquired by connecting to the socket and reading the key from the connection. The connection is made 750 from an <constant>AF_UNIX</constant> socket name in the abstract namespace, see <citerefentry 751 project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry> for 752 details. The source socket name is chosen according the following format:</para> 753 754 <programlisting><constant>NUL</constant> <replaceable>RANDOM</replaceable> <literal>/cryptsetup/</literal> <replaceable>VOLUME</replaceable></programlisting> 755 756 <para>In other words: a <constant>NUL</constant> byte (as required for abstract namespace sockets), 757 followed by a random string (consisting of alphanumeric characters only), followed by the literal 758 string <literal>/cryptsetup/</literal>, followed by the name of the volume to acquire they key 759 for. Example (for a volume <literal>myvol</literal>):</para> 760 761 <example><programlisting>\0d7067f78d9827418/cryptsetup/myvol</programlisting></example> 762 763 <para>Services listening on the <constant>AF_UNIX</constant> stream socket may query the source socket 764 name with <citerefentry 765 project='man-pages'><refentrytitle>getpeername</refentrytitle><manvolnum>2</manvolnum></citerefentry>, 766 and use it to determine which key to send, allowing a single listening socket to serve keys for a 767 multitude of volumes. If the PKCS#11 logic is used (see above) the socket source name is picked in 768 identical fashion, except that the literal string <literal>/cryptsetup-pkcs11/</literal> is used (similar 769 for FIDO2: <literal>/cryptsetup-fido2/</literal> and TPM2: <literal>/cryptsetup-tpm2/</literal>). This is 770 done so that services providing key material know that not a secret key is requested but an encrypted key 771 that will be decrypted via the PKCS#11/FIDO2/TPM2 logic to acquire the final secret key.</para> 772 </refsect1> 773 774 <refsect1> 775 <title>Examples</title> 776 <example> 777 <title>/etc/crypttab example</title> 778 <para>Set up four encrypted block devices. One using LUKS for normal storage, another one for usage as 779 a swap device and two TrueCrypt volumes. For the fourth device, the option string is interpreted as two 780 options <literal>cipher=xchacha12,aes-adiantum-plain64</literal>, 781 <literal>keyfile-timeout=10s</literal>.</para> 782 783 <programlisting>luks UUID=2505567a-9e27-4efe-a4d5-15ad146c258b 784swap /dev/sda7 /dev/urandom swap 785truecrypt /dev/sda2 /etc/container_password tcrypt 786hidden /mnt/tc_hidden /dev/null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile 787external /dev/sda3 keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchacha12\,aes-adiantum-plain64 788</programlisting> 789 </example> 790 791 <example> 792 <title>Yubikey-based PKCS#11 Volume Unlocking Example</title> 793 794 <para>The PKCS#11 logic allows hooking up any compatible security token that is capable of storing RSA 795 decryption keys for unlocking an encrypted volume. Here's an example how to set up a Yubikey security 796 token for this purpose on a LUKS2 volume, using <citerefentry 797 project='debian'><refentrytitle>ykmap</refentrytitle><manvolnum>1</manvolnum></citerefentry> from the 798 yubikey-manager project to initialize the token and 799 <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> 800 to add it in the LUKS2 volume:</para> 801 802<programlisting><xi:include href="yubikey-crypttab.sh" parse="text" /></programlisting> 803 804 <para>A few notes on the above:</para> 805 806 <itemizedlist> 807 <listitem><para>We use RSA2048, which is the longest key size current Yubikeys support</para></listitem> 808 <listitem><para>We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes, 809 <ulink url="https://developers.yubico.com/PIV/Introduction/Certificate_slots.html">see 810 documentation</ulink>.</para></listitem> 811 </itemizedlist> 812 </example> 813 814 <example> 815 <title>FIDO2 Volume Unlocking Example</title> 816 817 <para>The FIDO2 logic allows using any compatible FIDO2 security token that implements the 818 <literal>hmac-secret</literal> extension for unlocking an encrypted volume. Here's an example how to 819 set up a FIDO2 security token for this purpose for a LUKS2 volume, using 820 <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>:</para> 821 822<programlisting><xi:include href="fido2-crypttab.sh" parse="text" /></programlisting> 823 </example> 824 825 <example> 826 <title>TPM2 Volume Unlocking Example</title> 827 828 <para>The TPM2 logic allows using any TPM2 chip supported by the Linux kernel for unlocking an 829 encrypted volume. Here's an example how to set up a TPM2 chip for this purpose for a LUKS2 volume, 830 using 831 <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>:</para> 832 833<programlisting><xi:include href="tpm2-crypttab.sh" parse="text" /></programlisting> 834 </example> 835 </refsect1> 836 837 <refsect1> 838 <title>See Also</title> 839 <para> 840 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 841 <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 842 <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 843 <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 844 <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 845 <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 846 <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 847 <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry> 848 </para> 849 </refsect1> 850 851</refentry> 852