diff options
Diffstat (limited to 'man/systemd-cryptenroll.xml')
| -rw-r--r-- | man/systemd-cryptenroll.xml | 657 |
1 files changed, 657 insertions, 0 deletions
diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml new file mode 100644 index 0000000..8fd885c --- /dev/null +++ b/man/systemd-cryptenroll.xml @@ -0,0 +1,657 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> +<refentry id="systemd-cryptenroll" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='HAVE_LIBCRYPTSETUP'> + + <refentryinfo> + <title>systemd-cryptenroll</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-cryptenroll</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-cryptenroll</refname> + <refpurpose>Enroll PKCS#11, FIDO2, TPM2 token/devices to LUKS2 encrypted volumes</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-cryptenroll</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt">DEVICE</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-cryptenroll</command> is a tool for enrolling hardware security tokens and devices + into a LUKS2 encrypted volume, which may then be used to unlock the volume during boot. Specifically, it + supports tokens and credentials of the following kind to be enrolled:</para> + + <orderedlist> + <listitem><para>PKCS#11 security tokens and smartcards that may carry an RSA key pair (e.g. various + YubiKeys)</para></listitem> + + <listitem><para>FIDO2 security tokens that implement the <literal>hmac-secret</literal> extension (most + FIDO2 keys, including YubiKeys)</para></listitem> + + <listitem><para>TPM2 security devices</para></listitem> + + <listitem><para>Regular passphrases</para></listitem> + + <listitem><para>Recovery keys. These are similar to regular passphrases, however are randomly generated + on the computer and thus generally have higher entropy than user-chosen passphrases. Their character + set has been designed to ensure they are easy to type in, while having high entropy. They may also be + scanned off screen using QR codes. Recovery keys may be used for unlocking LUKS2 volumes wherever + passphrases are accepted. They are intended to be used in combination with an enrolled hardware + security token, as a recovery option when the token is lost.</para></listitem> + </orderedlist> + + <para>In addition, the tool may be used to enumerate currently enrolled security tokens and wipe a subset + of them. The latter may be combined with the enrollment operation of a new security token, in order to + update or replace enrollments.</para> + + <para>The tool supports only LUKS2 volumes, as it stores token meta-information in the LUKS2 JSON token + area, which is not available in other encryption formats.</para> + + <refsect2> + <title>TPM2 PCRs and policies</title> + + <para>PCRs allow binding of the encryption of secrets to specific software versions and system state, + so that the enrolled key is only accessible (may be "unsealed") if specific trusted software and/or + configuration is used. Such bindings may be created with the option <option>--tpm2-pcrs=</option> + described below.</para> + + <para>Secrets may also be bound indirectly: a signed policy for a state of some combination of PCR + values is provided, and the secret is bound to the public part of the key used to sign this policy. + This means that the owner of a key can generate a sequence of signed policies, for specific software + versions and system states, and the secret can be decrypted as long as the machine state matches one of + those policies. For example, a vendor may provide such a policy for each kernel+initrd update, allowing + users to encrypt secrets so that they can be decrypted when running any kernel+initrd signed by the + vendor. Such bindings may be created with the options <option>--tpm2-public-key=</option>, + <option>--tpm2-public-key-pcrs=</option>, <option>--tpm2-signature=</option> described below. + </para> + + <para>See <ulink url="https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/">Linux TPM + PCR Registry</ulink> for an authoritative list of PCRs and how they are updated. The table below + contains a quick reference, describing in particular the PCRs modified by systemd.</para> + + <table> + <title>Well-known PCR Definitions</title> + + <!-- See: https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/ --> + <!-- See: https://github.com/rhboot/shim/blob/main/README.tpm --> + <!-- See: https://www.gnu.org/software/grub/manual/grub/html_node/Measured-Boot.html --> + <!-- See: https://sourceforge.net/p/linux-ima/wiki/Home/ --> + <!-- See: https://github.com/tianocore-docs/edk2-TrustedBootChain/blob/main/4_Other_Trusted_Boot_Chains.md --> + <!-- See: https://wiki.archlinux.org/title/Trusted_Platform_Module#Accessing_PCR_registers --> + + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname="pcr" /> + <colspec colname="name" /> + <colspec colname="definition" /> + + <thead> + <row> + <entry>PCR</entry> + <entry>name</entry> + <entry>Explanation</entry> + </row> + </thead> + + <tbody> + <row> + <entry>0</entry> + <entry>platform-code</entry> + <entry>Core system firmware executable code; changes on firmware updates</entry> + </row> + + <row> + <entry>1</entry> + <entry>platform-config</entry> + <entry>Core system firmware data/host platform configuration; typically contains serial and model numbers, changes on basic hardware/CPU/RAM replacements</entry> + </row> + + <row> + <entry>2</entry> + <entry>external-code</entry> + <entry>Extended or pluggable executable code; includes option ROMs on pluggable hardware</entry> + </row> + + <row> + <entry>3</entry> + <entry>external-config</entry> + <entry>Extended or pluggable firmware data; includes information about pluggable hardware</entry> + </row> + + <row> + <entry>4</entry> + <entry>boot-loader-code</entry> + <entry>Boot loader and additional drivers, PE binaries invoked by the boot loader; changes on boot loader updates. <citerefentry><refentrytitle>sd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures system extension images read from the ESP here too (see <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>).</entry> + </row> + + <row> + <entry>5</entry> + <entry>boot-loader-config</entry> + <entry>GPT/Partition table; changes when the partitions are added, modified, or removed</entry> + </row> + + <row> + <entry>7</entry> + <entry>secure-boot-policy</entry> + <entry>Secure Boot state; changes when UEFI SecureBoot mode is enabled/disabled, or firmware certificates (PK, KEK, db, dbx, …) changes.</entry> + </row> + + <row> + <entry>9</entry> + <entry>kernel-initrd</entry> + <entry>The Linux kernel measures all initrds it receives into this PCR.</entry> + <!-- Strictly speaking only Linux >= 5.17 using the LOAD_FILE2 protocol, see https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f046fff8bc4c4d8f8a478022e76e40b818f692df --> + </row> + + <row> + <entry>10</entry> + <entry>ima</entry> + <entry>The IMA project measures its runtime state into this PCR.</entry> + </row> + + <row> + <entry>11</entry> + <entry>kernel-boot</entry> + <entry><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures the ELF kernel image, embedded initrd and other payload of the PE image it is placed in into this PCR. <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures boot phase strings into this PCR at various milestones of the boot process.</entry> + </row> + + <row> + <entry>12</entry> + <entry>kernel-config</entry> + <entry><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures the kernel command line into this PCR. <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures any manually specified kernel command line (i.e. a kernel command line that overrides the one embedded in the unified PE image) and loaded credentials into this PCR.</entry> + </row> + + <row> + <entry>13</entry> + <entry>sysexts</entry> + <entry><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures any <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> images it passes to the booted kernel into this PCR.</entry> + </row> + + <row> + <entry>14</entry> + <entry>shim-policy</entry> + <entry>The shim project measures its "MOK" certificates and hashes into this PCR.</entry> + </row> + + <row> + <entry>15</entry> + <entry>system-identity</entry> + <entry><citerefentry><refentrytitle>systemd-cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> optionally measures the volume key of activated LUKS volumes into this PCR. <citerefentry><refentrytitle>systemd-pcrmachine.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures the <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> into this PCR. <citerefentry><refentrytitle>systemd-pcrfs@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures mount points, file system UUIDs, labels, partition UUIDs of the root and <filename>/var/</filename> filesystems into this PCR.</entry> + </row> + + <row> + <entry>16</entry> + <entry>debug</entry> + <entry>Debug</entry> + </row> + + <row> + <entry>23</entry> + <entry>application-support</entry> + <entry>Application Support</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>In general, encrypted volumes would be bound to some combination of PCRs 7, 11, and 14 (if + shim/MOK is used). In order to allow firmware and OS version updates, it is typically not advisable to + use PCRs such as 0 and 2, since the program code they cover should already be covered indirectly + through the certificates measured into PCR 7. Validation through certificates hashes is typically + preferable over validation through direct measurements as it is less brittle in context of OS/firmware + updates: the measurements will change on every update, but signatures should remain unchanged. See the + <ulink url="https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/">Linux TPM PCR + Registry</ulink> for more discussion.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>Limitations</title> + + <para>Note that currently when enrolling a new key of one of the five supported types listed above, it is + required to first provide a passphrase, a recovery key or a FIDO2 token. It's currently not supported to + unlock a device with a TPM2/PKCS#11 key in order to enroll a new TPM2/PKCS#11 key. Thus, if in future key + roll-over is desired it's generally recommended to ensure a passphrase, a recovery key or a FIDO2 token + is always enrolled.</para> + + <para>Also note that support for enrolling multiple FIDO2 tokens is currently limited. When multiple FIDO2 + tokens are enrolled, <command>systemd-cryptseup</command> will perform pre-flight requests to attempt to + identify which of the enrolled tokens are currently plugged in. However, this is not possible for FIDO2 + tokens with user verification (UV, usually via biometrics), in which case it will fall back to attempting + each enrolled token one by one. This will result in multiple prompts for PIN and user verification. This + limitation does not apply to PKCS#11 tokens.</para> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para>Security technology both in systemd and in the general industry constantly evolves. In order to + provide best security guarantees, the way TPM2, FIDO2, PKCS#11 devices are enrolled is regularly updated + in newer versions of systemd. Whenever this happens the following compatibility guarantees are given:</para> + + <itemizedlist> + <listitem><para>Old enrollments continue to be supported and may be unlocked with newer versions of + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>The opposite is not guaranteed however: it might not be possible to unlock volumes with + enrollments done with a newer version of <command>systemd-cryptenroll</command> with an older version + of <command>systemd-cryptsetup</command>.</para></listitem> + </itemizedlist> + + <para>That said, it is generally recommended to use matching versions of + <command>systemd-cryptenroll</command> and <command>systemd-cryptsetup</command>, since this is best + tested and supported.</para> + + <para>It might be advisable to re-enroll existing enrollments to take benefit of newer security features, + as they are added to systemd.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--password</option></term> + + <listitem><para>Enroll a regular password/passphrase. This command is mostly equivalent to + <command>cryptsetup luksAddKey</command>, however may be combined with + <option>--wipe-slot=</option> in one call, see below.</para> + + <xi:include href="version-info.xml" xpointer="v248"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--recovery-key</option></term> + + <listitem><para>Enroll a recovery key. Recovery keys are mostly identical to passphrases, but are + computer-generated instead of being chosen by a human, and thus have a guaranteed high entropy. The + key uses a character set that is easy to type in, and may be scanned off screen via a QR code. + </para> + + <xi:include href="version-info.xml" xpointer="v248"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--unlock-key-file=</option><replaceable>PATH</replaceable></term> + + <listitem><para>Use a file instead of a password/passphrase read from stdin to unlock the volume. + Expects the PATH to the file containing your key to unlock the volume. Currently there is nothing like + <option>--key-file-offset=</option> or <option>--key-file-size=</option> so this file has to only + contain the full key.</para> + + <xi:include href="version-info.xml" xpointer="v252"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--unlock-fido2-device=</option><replaceable>PATH</replaceable></term> + + <listitem><para>Use a FIDO2 device instead of a password/passphrase read from stdin to unlock the + volume. Expects a <filename>hidraw</filename> device referring to the FIDO2 device (e.g. + <filename>/dev/hidraw1</filename>). Alternatively the special value <literal>auto</literal> may be + specified, in order to automatically determine the device node of a currently plugged in security + token (of which there must be exactly one). This automatic discovery is unsupported if + <option>--fido2-device=</option> option is also specified.</para> + + <xi:include href="version-info.xml" xpointer="v253"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--pkcs11-token-uri=</option><replaceable>URI</replaceable></term> + + <listitem><para>Enroll a PKCS#11 security token or smartcard (e.g. a YubiKey). Expects a PKCS#11 + smartcard URI referring to the token. Alternatively the special value <literal>auto</literal> may + be specified, in order to automatically determine the URI of a currently plugged in security token + (of which there must be exactly one). The special value <literal>list</literal> may be used to + enumerate all suitable PKCS#11 tokens currently plugged in. The security token must contain an RSA + key pair which is used to encrypt the randomly generated key that is used to unlock the LUKS2 + volume. The encrypted key is then stored in the LUKS2 JSON token header area.</para> + + <para>In order to unlock a LUKS2 volume with an enrolled PKCS#11 security token, specify the + <option>pkcs11-uri=</option> option in the respective <filename>/etc/crypttab</filename> line:</para> + + <programlisting>myvolume /dev/sda1 - pkcs11-uri=auto</programlisting> + + <para>See + <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a + more comprehensive example of a <command>systemd-cryptenroll</command> invocation and its matching + <filename>/etc/crypttab</filename> line.</para> + + <xi:include href="version-info.xml" xpointer="v248"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--fido2-credential-algorithm=</option><replaceable>STRING</replaceable></term> + <listitem><para>Specify COSE algorithm used in credential generation. The default value is + <literal>es256</literal>. Supported values are <literal>es256</literal>, <literal>rs256</literal> + and <literal>eddsa</literal>.</para> + + <para><literal>es256</literal> denotes ECDSA over NIST P-256 with SHA-256. <literal>rs256</literal> + denotes 2048-bit RSA with PKCS#1.5 padding and SHA-256. <literal>eddsa</literal> denotes + EDDSA over Curve25519 with SHA-512.</para> + + <para>Note that your authenticator may not support some algorithms.</para> + + <xi:include href="version-info.xml" xpointer="v251"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--fido2-device=</option><replaceable>PATH</replaceable></term> + + <listitem><para>Enroll a FIDO2 security token that implements the <literal>hmac-secret</literal> + extension (e.g. a YubiKey). Expects a <filename>hidraw</filename> device referring to the FIDO2 + device (e.g. <filename>/dev/hidraw1</filename>). Alternatively the special value + <literal>auto</literal> may be specified, in order to automatically determine the device node of a + currently plugged in security token (of which there must be exactly one). This automatic discovery + is unsupported if <option>--unlock-fido2-device=</option> option is also specified. The special value + <literal>list</literal> may be used to enumerate all suitable FIDO2 tokens currently plugged in. Note + that many hardware security tokens that implement FIDO2 also implement the older PKCS#11 + standard. Typically FIDO2 is preferable, given it's simpler to use and more modern.</para> + + <para>In order to unlock a LUKS2 volume with an enrolled FIDO2 security token, specify the + <option>fido2-device=</option> option in the respective <filename>/etc/crypttab</filename> line:</para> + + <programlisting>myvolume /dev/sda1 - fido2-device=auto</programlisting> + + <para>See + <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a + more comprehensive example of a <command>systemd-cryptenroll</command> invocation and its matching + <filename>/etc/crypttab</filename> line.</para> + + <xi:include href="version-info.xml" xpointer="v248"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--fido2-with-client-pin=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>When enrolling a FIDO2 security token, controls whether to require the user to enter + a PIN when unlocking the volume (the FIDO2 <literal>clientPin</literal> feature). Defaults to + <literal>yes</literal>. (Note: this setting is without effect if the security token does not support + the <literal>clientPin</literal> feature at all, or does not allow enabling or disabling + it.)</para> + + <xi:include href="version-info.xml" xpointer="v249"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--fido2-with-user-presence=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>When enrolling a FIDO2 security token, controls whether to require the user to + verify presence (tap the token, the FIDO2 <literal>up</literal> feature) when unlocking the volume. + Defaults to <literal>yes</literal>. (Note: this setting is without effect if the security token does not support + the <literal>up</literal> feature at all, or does not allow enabling or disabling it.) + </para> + + <xi:include href="version-info.xml" xpointer="v249"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--fido2-with-user-verification=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>When enrolling a FIDO2 security token, controls whether to require user verification + when unlocking the volume (the FIDO2 <literal>uv</literal> feature). Defaults to + <literal>no</literal>. (Note: this setting is without effect if the security token does not support + the <literal>uv</literal> feature at all, or does not allow enabling or disabling it.)</para> + + <xi:include href="version-info.xml" xpointer="v249"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--tpm2-device=</option><replaceable>PATH</replaceable></term> + + <listitem><para>Enroll a TPM2 security chip. Expects a device node path referring to the TPM2 chip + (e.g. <filename>/dev/tpmrm0</filename>). Alternatively the special value <literal>auto</literal> may + be specified, in order to automatically determine the device node of a currently discovered TPM2 + device (of which there must be exactly one). The special value <literal>list</literal> may be used to + enumerate all suitable TPM2 devices currently discovered.</para> + + <para>In order to unlock a LUKS2 volume with an enrolled TPM2 security chip, specify the + <option>tpm2-device=</option> option in the respective <filename>/etc/crypttab</filename> line:</para> + + <programlisting>myvolume /dev/sda1 - tpm2-device=auto</programlisting> + + <para>See + <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a + more comprehensive example of a <command>systemd-cryptenroll</command> invocation and its matching + <filename>/etc/crypttab</filename> line.</para> + + <para>Use <option>--tpm2-pcrs=</option> (see below) to configure which TPM2 PCR indexes to bind the + enrollment to.</para> + + <xi:include href="version-info.xml" xpointer="v248"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--tpm2-device-key=</option><replaceable>PATH</replaceable></term> + + <listitem><para>Enroll a TPM2 security chip using its public key. Expects a path referring to the + TPM2 public key in TPM2B_PUBLIC format. This cannot be used with <option>--tpm2-device=</option>, as + it performs the same operation, but without connecting to the TPM2 security chip; instead the + enrollment is calculated using the provided TPM2 key. This is useful in situations where the TPM2 + security chip is not available at the time of enrollment.</para> + + <para>The key, in most cases, should be the Storage Root Key (SRK) from a local TPM2 security + chip. If a key from a different handle (not the SRK) is used, you must specify its handle index using + <option>--tpm2-seal-key-handle=</option>.</para> + + <para>The + <citerefentry><refentrytitle>systemd-tpm2-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + service writes the SRK to <filename>/run/systemd/tpm2-srk-public-key.tpm2b_public</filename> + automatically during boot, in the correct format.</para> + + <para>Alternatively, you may use <command>systemd-analyze srk</command> to retrieve the SRK from the + TPM2 security chip explicitly. See + <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details. Example:</para> + + <programlisting>systemd-analyze srk > srk.tpm2b_public</programlisting> + + <xi:include href="version-info.xml" xpointer="v255"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--tpm2-seal-key-handle=</option><replaceable>HANDLE</replaceable></term> + + <listitem><para>Configures which parent key to use for sealing, using the TPM handle (index) of the + key. This is used to "seal" (encrypt) a secret and must be used later to "unseal" (decrypt) the + secret. Expects a hexadecimal 32bit integer, optionally prefixed with + <literal>0x</literal>. Allowable values are any handle index in the persistent + (<literal>0x81000000</literal>-<literal>0x81ffffff</literal>) or transient + (<literal>0x80000000</literal>-<literal>0x80ffffff</literal>) ranges. Since transient handles are + lost after a TPM reset, and may be flushed during TPM context switching, they should not be used + except for very specific use cases, e.g. testing.</para> + + <para>The default is the Storage Root Key (SRK) handle index <literal>0x81000001</literal>. A value + of 0 will use the default. For the SRK handle, a new key will be created and stored in the TPM if one + does not already exist; for any other handle, the key must already exist in the TPM at the specified + handle index.</para> + + <para>This should not be changed unless you know what you are doing.</para> + + <xi:include href="version-info.xml" xpointer="v255"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--tpm2-pcrs=</option><arg rep="repeat">PCR</arg></term> + + <listitem><para>Configures the TPM2 PCRs (Platform Configuration Registers) to bind to when + enrollment is requested via <option>--tpm2-device=</option>. Takes a list of PCR entries, where each + entry starts with a name or numeric index in the range 0…23, optionally followed by + <literal>:</literal> and a hash algorithm name (specifying the PCR bank), optionally followed by + <literal>=</literal> and a hash digest value. Multiple PCR entries are separated by + <literal>+</literal>. If not specified, the default is to use PCR 7 only. If an empty string is + specified, binds the enrollment to no PCRs at all. See the table above for a list of available + PCRs.</para> + + <para>Example: <option>--tpm2-pcrs=boot-loader-code+platform-config+boot-loader-config</option> + specifies that PCR registers 4, 1, and 5 should be used.</para> + <para>Example: <option>--tpm2-pcrs=7:sha256</option> specifies that PCR register 7 from the SHA256 + bank should be used.</para> + <para>Example: <option>--tpm2-pcrs=4:sha1=3a3f780f11a4b49969fcaa80cd6e3957c33b2275</option> + specifies that PCR register 4 from the SHA1 bank should be used, and a hash digest value of + 3a3f780f11a4b49969fcaa80cd6e3957c33b2275 will be used instead of reading the current PCR + value.</para> + + <xi:include href="version-info.xml" xpointer="v248"/> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--tpm2-with-pin=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>When enrolling a TPM2 device, controls whether to require the user to enter a PIN + when unlocking the volume in addition to PCR binding, based on TPM2 policy authentication. Defaults + to <literal>no</literal>. Despite being called PIN, any character can be used, not just numbers. + </para> + + <para>Note that incorrect PIN entry when unlocking increments the TPM dictionary attack lockout + mechanism, and may lock out users for a prolonged time, depending on its configuration. The lockout + mechanism is a global property of the TPM, <command>systemd-cryptenroll</command> does not control or + configure the lockout mechanism. You may use tpm2-tss tools to inspect or configure the dictionary + attack lockout, with <citerefentry + project='mankier'><refentrytitle>tpm2_getcap</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and <citerefentry + project='mankier'><refentrytitle>tpm2_dictionarylockout</refentrytitle><manvolnum>1</manvolnum></citerefentry> + commands, respectively.</para> + + <xi:include href="version-info.xml" xpointer="v251"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--tpm2-public-key=</option><arg>PATH</arg></term> + <term><option>--tpm2-public-key-pcrs=</option><arg rep="repeat">PCR</arg></term> + <term><option>--tpm2-signature=</option><arg>PATH</arg></term> + + <listitem><para>Configures a TPM2 signed PCR policy to bind encryption to. The + <option>--tpm2-public-key=</option> option accepts a path to a PEM encoded RSA public key, to bind + the encryption to. If this is not specified explicitly, but a file + <filename>tpm2-pcr-public-key.pem</filename> exists in one of the directories + <filename>/etc/systemd/</filename>, <filename>/run/systemd/</filename>, + <filename>/usr/lib/systemd/</filename> (searched in this order), it is automatically used. The + <option>--tpm2-public-key-pcrs=</option> option takes a list of TPM2 PCR indexes to bind to (same + syntax as <option>--tpm2-pcrs=</option> described above). If not specified defaults to 11 (i.e. this + binds the policy to any unified kernel image for which a PCR signature can be provided).</para> + + <para>Note the difference between <option>--tpm2-pcrs=</option> and + <option>--tpm2-public-key-pcrs=</option>: the former binds decryption to the current, specific PCR + values; the latter binds decryption to any set of PCR values for which a signature by the specified + public key can be provided. The latter is hence more useful in scenarios where software updates shell + be possible without losing access to all previously encrypted LUKS2 volumes. Like with + <option>--tpm2-pcrs=</option>, names defined in the table above can also be used to specify the + registers, for instance + <option>--tpm2-public-key-pcrs=boot-loader-code+system-identity</option>.</para> + + <para>The <option>--tpm2-signature=</option> option takes a path to a TPM2 PCR signature file as + generated by the + <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool. If this is not specified explicitly, a suitable signature file + <filename>tpm2-pcr-signature.json</filename> is searched for in <filename>/etc/systemd/</filename>, + <filename>/run/systemd/</filename>, <filename>/usr/lib/systemd/</filename> (in this order) and used. + If a signature file is specified or found it is used to verify if the volume can be unlocked with it + given the current PCR state, before the new slot is written to disk. This is intended as safety net + to ensure that access to a volume is not lost if a public key is enrolled for which no valid + signature for the current PCR state is available. If the supplied signature does not unlock the + current PCR state and public key combination, no slot is enrolled and the operation will fail. If no + signature file is specified or found no such safety verification is done.</para> + + <xi:include href="version-info.xml" xpointer="v252"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--tpm2-pcrlock=</option><arg>PATH</arg></term> + + <listitem><para>Configures a TPM2 pcrlock policy to bind encryption to. Expects a path to a pcrlock + policy file as generated by the + <citerefentry><refentrytitle>systemd-pcrlock</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool. If a TPM2 device is enrolled and this option is not used but a file + <filename>pcrlock.json</filename> is found in <filename>/run/systemd/</filename> or + <filename>/var/lib/systemd/</filename> it is automatically used. Assign an empty string to turn this + behaviour off.</para> + + <xi:include href="version-info.xml" xpointer="v255"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--wipe-slot=</option><arg rep="repeat">SLOT</arg></term> + + <listitem><para>Wipes one or more LUKS2 key slots. Takes a comma separated list of numeric slot + indexes, or the special strings <literal>all</literal> (for wiping all key slots), + <literal>empty</literal> (for wiping all key slots that are unlocked by an empty passphrase), + <literal>password</literal> (for wiping all key slots that are unlocked by a traditional passphrase), + <literal>recovery</literal> (for wiping all key slots that are unlocked by a recovery key), + <literal>pkcs11</literal> (for wiping all key slots that are unlocked by a PKCS#11 token), + <literal>fido2</literal> (for wiping all key slots that are unlocked by a FIDO2 token), + <literal>tpm2</literal> (for wiping all key slots that are unlocked by a TPM2 chip), or any + combination of these strings or numeric indexes, in which case all slots matching either are + wiped. As safety precaution an operation that wipes all slots without exception (so that the volume + cannot be unlocked at all anymore, unless the volume key is known) is refused.</para> + + <para>This switch may be used alone, in which case only the requested wipe operation is executed. It + may also be used in combination with any of the enrollment options listed above, in which case the + enrollment is completed first, and only when successful the wipe operation executed — and the newly + added slot is always excluded from the wiping. Combining enrollment and slot wiping may thus be used to + update existing enrollments:</para> + + <programlisting>systemd-cryptenroll /dev/sda1 --wipe-slot=tpm2 --tpm2-device=auto</programlisting> + + <para>The above command will enroll the TPM2 chip, and then wipe all previously created TPM2 + enrollments on the LUKS2 volume, leaving only the newly created one. Combining wiping and enrollment + may also be used to replace enrollments of different types, for example for changing from a PKCS#11 + enrollment to a FIDO2 one:</para> + + <programlisting>systemd-cryptenroll /dev/sda1 --wipe-slot=pkcs11 --fido2-device=auto</programlisting> + + <para>Or for replacing an enrolled empty password by TPM2:</para> + + <programlisting>systemd-cryptenroll /dev/sda1 --wipe-slot=empty --tpm2-device=auto</programlisting> + + <xi:include href="version-info.xml" xpointer="v248"/> + </listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code otherwise.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para><citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> and + <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> + contain various examples employing <command>systemd-cryptenroll</command>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |