man/crypttab.xml

   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>Similarly, the key may be acquired via a FIDO2 compatible hardware security token
 113       (which must implement the "hmac-secret" extension). In this case a key generated randomly during
 114       enrollment is stored on disk/removable media, acquired via <constant>AF_UNIX</constant>, or stored in
 115       the LUKS2 JSON token metadata header. The random key is hashed via a keyed hash function (HMAC) on the
 116       FIDO2 token, using a secret key stored on the token that never leaves it. The resulting hash value is
 117       then used as key to unlock the encrypted volume. Use the <option>fido2-device=</option> option
 118       described below to use this mechanism.</para></listitem>
 119
 120       <listitem><para>Similarly, 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 or the device used as the key file,
 236         and falls back to a password if it could not be accessed. 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>tpm2-signature=</option></term>
 690
 691         <listitem><para>Takes an absolute path to a TPM2 PCR JSON signature file, as produced by the
 692         <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 693         tool. This permits locking LUKS2 volumes to any PCR values for which a valid signature matching a
 694         public key specified at key enrollment time can be provided. See
 695         <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 696         for details on enrolling TPM2 PCR public keys. If this option is not specified but it is attempted to
 697         unlock a LUKS2 volume with a signed TPM2 PCR enrollment a suitable signature file
 698         <filename>tpm2-pcr-signature.json</filename> is searched for in <filename>/etc/systemd/</filename>,
 699         <filename>/run/systemd/</filename>, <filename>/usr/lib/systemd/</filename> (in this
 700         order).</para></listitem>
 701       </varlistentry>
 702
 703       <varlistentry>
 704         <term><option>token-timeout=</option></term>
 705
 706         <listitem><para>Specifies how long to wait at most for configured security devices (i.e. FIDO2,
 707         PKCS#11, TPM2) to show up. Takes a time value in seconds (but other time units may be specified too,
 708         see <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 709         for supported formats). Defaults to 30s. Once the specified timeout elapsed authentication via
 710         password is attempted. Note that this timeout applies to waiting for the security device to show up —
 711         it does not apply to the PIN prompt for the device (should one be needed) or similar. Pass 0 to turn
 712         off the time-out and wait forever.</para></listitem>
 713       </varlistentry>
 714
 715       <varlistentry>
 716         <term><option>try-empty-password=</option></term>
 717
 718         <listitem><para>Takes a boolean argument. If enabled, right before asking the user for a password it
 719         is first attempted to unlock the volume with an empty password. This is useful for systems that are
 720         initialized with an encrypted volume with only an empty password set, which shall be replaced with a
 721         suitable password during first boot, but after activation.</para></listitem>
 722       </varlistentry>
 723
 724       <varlistentry>
 725         <term><option>x-systemd.device-timeout=</option></term>
 726
 727         <listitem><para>Specifies how long systemd should wait for a block device to show up before
 728         giving up on the entry. The argument is a time in seconds or explicitly specified units of
 729         <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>ms</literal>.
 730         </para></listitem>
 731       </varlistentry>
 732
 733       <varlistentry>
 734         <term><option>x-initrd.attach</option></term>
 735
 736         <listitem><para>Setup this encrypted block device in the initrd, similarly to
 737         <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 738         units marked with <option>x-initrd.mount</option>.</para>
 739
 740         <para>Although it's not necessary to mark the mount entry for the root file system with
 741         <option>x-initrd.mount</option>, <option>x-initrd.attach</option> is still recommended with
 742         the encrypted block device containing the root file system as otherwise systemd will
 743         attempt to detach the device during the regular system shutdown while it's still in
 744         use. With this option the device will still be detached but later after the root file
 745         system is unmounted.</para>
 746
 747         <para>All other encrypted block devices that contain file systems mounted in the initrd should use
 748         this option.</para>
 749         </listitem>
 750       </varlistentry>
 751
 752     </variablelist>
 753
 754     <para>At early boot and when the system manager configuration is
 755     reloaded, this file is translated into native systemd units by
 756     <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 757   </refsect1>
 758
 759   <refsect1>
 760     <title><constant>AF_UNIX</constant> Key Files</title>
 761
 762     <para>If the key file path (as specified in the third column of <filename>/etc/crypttab</filename>
 763     entries, see above) refers to an <constant>AF_UNIX</constant> stream socket in the file system, the key
 764     is acquired by connecting to the socket and reading the key from the connection. The connection is made
 765     from an <constant>AF_UNIX</constant> socket name in the abstract namespace, see <citerefentry
 766     project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
 767     details. The source socket name is chosen according the following format:</para>
 768
 769     <programlisting><constant>NUL</constant> <replaceable>RANDOM</replaceable> /cryptsetup/ <replaceable>VOLUME</replaceable></programlisting>
 770
 771     <para>In other words: a <constant>NUL</constant> byte (as required for abstract namespace sockets),
 772     followed by a random string (consisting of alphanumeric characters only), followed by the literal
 773     string <literal>/cryptsetup/</literal>, followed by the name of the volume to acquire they key
 774     for. For example, for the volume <literal>myvol</literal>:</para>
 775
 776     <programlisting>\0d7067f78d9827418/cryptsetup/myvol</programlisting>
 777
 778     <para>Services listening on the <constant>AF_UNIX</constant> stream socket may query the source socket
 779     name with <citerefentry
 780     project='man-pages'><refentrytitle>getpeername</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 781     and use this to determine which key to send, allowing a single listening socket to serve keys for
 782     multiple volumes. If the PKCS#11 logic is used (see above), the socket source name is picked in similar
 783     fashion, except that the literal string <literal>/cryptsetup-pkcs11/</literal> is used. And similarly for
 784     FIDO2 (<literal>/cryptsetup-fido2/</literal>) and TPM2 (<literal>/cryptsetup-tpm2/</literal>). A diffent
 785     path component is used so that services providing key material know that the secret key was not requested
 786     directly, but instead an encrypted key that will be decrypted via the PKCS#11/FIDO2/TPM2 logic to acquire
 787     the final secret key.</para>
 788   </refsect1>
 789
 790   <refsect1>
 791     <title>Examples</title>
 792     <example>
 793       <title>/etc/crypttab example</title>
 794       <para>Set up four encrypted block devices. One using LUKS for normal storage, another one for usage as
 795       a swap device and two TrueCrypt volumes. For the fourth device, the option string is interpreted as two
 796       options <literal>cipher=xchacha12,aes-adiantum-plain64</literal>,
 797       <literal>keyfile-timeout=10s</literal>.</para>
 798
 799       <programlisting>luks       UUID=2505567a-9e27-4efe-a4d5-15ad146c258b
 800 swap       /dev/sda7       /dev/urandom       swap
 801 truecrypt  /dev/sda2       /etc/container_password  tcrypt
 802 hidden     /mnt/tc_hidden  /dev/null    tcrypt-hidden,tcrypt-keyfile=/etc/keyfile
 803 external   /dev/sda3       keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchacha12\,aes-adiantum-plain64
 804 </programlisting>
 805     </example>
 806
 807     <example>
 808       <title>Yubikey-based PKCS#11 Volume Unlocking Example</title>
 809
 810       <para>The PKCS#11 logic allows hooking up any compatible security token that is capable of storing RSA
 811       decryption keys for unlocking an encrypted volume. Here's an example how to set up a Yubikey security
 812       token for this purpose on a LUKS2 volume, using <citerefentry
 813       project='debian'><refentrytitle>ykmap</refentrytitle><manvolnum>1</manvolnum></citerefentry> from the
 814       yubikey-manager project to initialize the token and
 815       <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 816       to add it in the LUKS2 volume:</para>
 817
 818 <programlisting><xi:include href="yubikey-crypttab.sh" parse="text" /></programlisting>
 819
 820       <para>A few notes on the above:</para>
 821
 822       <itemizedlist>
 823         <listitem><para>We use RSA2048, which is the longest key size current Yubikeys support</para></listitem>
 824         <listitem><para>We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes,
 825         <ulink url="https://developers.yubico.com/PIV/Introduction/Certificate_slots.html">see
 826         documentation</ulink>.</para></listitem>
 827       </itemizedlist>
 828     </example>
 829
 830     <example>
 831       <title>FIDO2 Volume Unlocking Example</title>
 832
 833       <para>The FIDO2 logic allows using any compatible FIDO2 security token that implements the
 834       <literal>hmac-secret</literal> extension for unlocking an encrypted volume. Here's an example how to
 835       set up a FIDO2 security token for this purpose for a LUKS2 volume, using
 836       <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>:</para>
 837
 838 <programlisting><xi:include href="fido2-crypttab.sh" parse="text" /></programlisting>
 839     </example>
 840
 841     <example>
 842       <title>TPM2 Volume Unlocking Example</title>
 843
 844       <para>The TPM2 logic allows using any TPM2 chip supported by the Linux kernel for unlocking an
 845       encrypted volume. Here's an example how to set up a TPM2 chip for this purpose for a LUKS2 volume,
 846       using
 847       <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>:</para>
 848
 849 <programlisting><xi:include href="tpm2-crypttab.sh" parse="text" /></programlisting>
 850     </example>
 851   </refsect1>
 852
 853   <refsect1>
 854     <title>See Also</title>
 855     <para>
 856       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 857       <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 858       <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 859       <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 860       <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 861       <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 862       <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 863       <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 864     </para>
 865   </refsect1>
 866
 867 </refentry>