The first two fields are mandatory, the remaining two are
optional.</para>
- <para>Setting up encrypted block devices using this file supports
- three encryption modes: LUKS, TrueCrypt and plain. See
- <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- for more information about each mode. When no mode is specified in
- the options field and the block device contains a LUKS signature,
- it is opened as a LUKS device; otherwise, it is assumed to be in
- raw dm-crypt (plain mode) format.</para>
+ <para>Setting up encrypted block devices using this file supports four encryption modes: LUKS, TrueCrypt,
+ BitLocker and plain. See <citerefentry
+ project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
+ more information about each mode. When no mode is specified in the options field and the block device
+ contains a LUKS signature, it is opened as a LUKS device; otherwise, it is assumed to be in raw dm-crypt
+ (plain mode) format.</para>
<para>The four fields of <filename>/etc/crypttab</filename> are defined as follows:</para>
<literal>UUID=</literal> followed by the UUID.</para></listitem>
<listitem><para>The third field specifies an absolute path to a file with the encryption
- key. Optionally, the path may be followed by <literal>:</literal> and an fstab device specification
- (e.g. starting with <literal>LABEL=</literal> or similar); in which case the path is taken relative to
- the device file system root. If the field is not present or is <literal>none</literal> or
+ key. Optionally, the path may be followed by <literal>:</literal> and an
+ <filename>/etc/fstab</filename> style device specification (e.g. starting with
+ <literal>LABEL=</literal> or similar); in which case the path is taken relative to the specified
+ device's file system root. If the field is not present or is <literal>none</literal> or
<literal>-</literal>, a key file named after the volume to unlock (i.e. the first column of the line),
suffixed with <filename>.key</filename> is automatically loaded from the
<filename>/etc/cryptsetup-keys.d/</filename> and <filename>/run/cryptsetup-keys.d/</filename>
<listitem><para>The fourth field, if present, is a comma-delimited list of options. The supported
options are listed below.</para></listitem>
</orderedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>Key Acquisition</title>
+
+ <para>Six different mechanisms for acquiring the decryption key or passphrase unlocking the encrypted
+ volume are supported. Specifically:</para>
+
+ <orderedlist>
+
+ <listitem><para>Most prominently, the user may be queried interactively during volume activation
+ (i.e. typically at boot), asking them to type in the necessary passphrase(s).</para></listitem>
+
+ <listitem><para>The (unencrypted) key may be read from a file on disk, possibly on removable media. The third field
+ of each line encodes the location, for details see above.</para></listitem>
+
+ <listitem><para>The (unencrypted) key may be requested from another service, by specifying an
+ <constant>AF_UNIX</constant> file system socket in place of a key file in the third field. For details
+ see above and below.</para></listitem>
+
+ <listitem><para>The key may be acquired via a PKCS#11 compatible hardware security token or
+ smartcard. In this case an encrypted key is stored on disk/removable media, acquired via
+ <constant>AF_UNIX</constant>, or stored in the LUKS2 JSON token metadata header. The encrypted key is
+ then decrypted by the PKCS#11 token with an RSA key stored on it, and then used to unlock the encrypted
+ volume. Use the <option>pkcs11-uri=</option> option described below to use this mechanism.</para></listitem>
+
+ <listitem><para>Similar, the key may be acquired via a FIDO2 compatible hardware security token (which
+ must implement the "hmac-secret" extension). In this case a (during enrollment) randomly generated key
+ is stored on disk/removable media, acquired via <constant>AF_UNIX</constant>, or stored in the LUKS2
+ JSON token metadata header. The random key is hashed via a keyed hash function (HMAC) on the FIDO2
+ token, using a secret key stored on the token that never leaves it. The resulting hash value is then
+ used as key to unlock the encrypted volume. Use the <option>fido2-device=</option> option described
+ below to use this mechanism.</para></listitem>
+
+ <listitem><para>Similar, the key may be acquired via a TPM2 security chip. In this case a (during
+ enrollment) randomly generated key — encrypted by an asymmetric key derived from the TPM2 chip's seed
+ key — is stored on disk/removable media, acquired via <constant>AF_UNIX</constant>, or stored in the
+ LUKS2 JSON token metadata header. Use the <option>tpm2-device=</option> option described below to use
+ this mechanism.</para></listitem>
+ </orderedlist>
+
+ <para>For the latter five mechanisms the source for the key material used for unlocking the volume is
+ primarily configured in the third field of each <filename>/etc/crypttab</filename> line, but may also
+ configured in <filename>/etc/cryptsetup-keys.d/</filename> and
+ <filename>/run/cryptsetup-keys.d/</filename> (see above) or in the LUKS2 JSON token header (in case of
+ the latter three). Use the
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ tool to enroll PKCS#11, FIDO2 and TPM2 devices in LUKS2 volumes.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Supported Options</title>
+
+ <para>The following options may be used in the fourth field of each line:</para>
<variablelist class='fstab-options'>
for possible values and the default value of this
option.</para>
- <para>Optionally, the path may be followed by <literal>:</literal> and an fstab device specification
- (e.g. starting with <literal>UUID=</literal> or similar); in which case, the path is relative to the
- device file system root. The device gets mounted automatically for LUKS device activation duration only.
- </para></listitem>
+ <para>Optionally, the path may be followed by <literal>:</literal> and an
+ <filename>/etc/fstab</filename> device specification (e.g. starting with <literal>UUID=</literal> or
+ similar); in which case, the path is relative to the device file system root. The device gets mounted
+ automatically for LUKS device activation duration only.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><option>bitlk</option></term>
- <listitem><para>Decrypt Bitlocker drive. Encryption parameters
- are deduced by cryptsetup from Bitlocker header.</para></listitem>
+ <listitem><para>Decrypt BitLocker drive. Encryption parameters
+ are deduced by cryptsetup from BitLocker header.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><option>same-cpu-crypt</option></term>
- <listitem><para>Perform encryption using the same cpu that IO was submitted on. The default is to use
+ <listitem><para>Perform encryption using the same CPU that IO was submitted on. The default is to use
an unbound workqueue so that encryption work is automatically balanced between available CPUs.</para>
<para>This requires kernel 4.0 or newer.</para>
<varlistentry>
<term><option>pkcs11-uri=</option></term>
- <listitem><para>Takes a <ulink url="https://tools.ietf.org/html/rfc7512">RFC7512 PKCS#11 URI</ulink>
- pointing to a private RSA key which is used to decrypt the key specified in the third column of the
- line. This is useful for unlocking encrypted volumes through security tokens or smartcards. See below
- for an example how to set up this mechanism for unlocking a LUKS volume with a YubiKey security
- token. The specified URI can refer directly to a private RSA key stored on a token or alternatively
+ <listitem><para>Takes either the special value <literal>auto</literal> or an <ulink
+ url="https://tools.ietf.org/html/rfc7512">RFC7512 PKCS#11 URI</ulink> pointing to a private RSA key
+ which is used to decrypt the encrypted key specified in the third column of the line. This is useful
+ for unlocking encrypted volumes through PKCS#11 compatible security tokens or smartcards. See below
+ for an example how to set up this mechanism for unlocking a LUKS2 volume with a YubiKey security
+ token.</para>
+
+ <para>If specified as <literal>auto</literal> the volume must be of type LUKS2 and must carry PKCS#11
+ security token metadata in its LUKS2 JSON token section. In this mode the URI and the encrypted key
+ are automatically read from the LUKS2 JSON token header. Use
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ as simple tool for enrolling PKCS#11 security tokens or smartcards in a way compatible with
+ <literal>auto</literal>. In this mode the third column of the line should remain empty (that is,
+ specified as <literal>-</literal>).</para>
+
+ <para>The specified URI can refer directly to a private RSA key stored on a token or alternatively
just to a slot or token, in which case a search for a suitable private RSA key will be performed. In
- this case if multiple suitable objects are found the token is refused. The key configured in the
- third column is passed as is to RSA decryption. The resulting decrypted key is then base64 encoded
- before it is used to unlock the LUKS volume.</para></listitem>
+ this case if multiple suitable objects are found the token is refused. The encrypted key configured
+ in the third column of the line is passed as is (i.e. in binary form, unprocessed) to RSA
+ decryption. The resulting decrypted key is then Base64 encoded before it is used to unlock the LUKS
+ volume.</para>
+
+ <para>Use <command>systemd-cryptenroll --pkcs11-token-uri=list</command> to list all suitable PKCS#11
+ security tokens currently plugged in, along with their URIs.</para>
+
+ <para>Note that many newer security tokens that may be used as PKCS#11 security token typically also
+ implement the newer and simpler FIDO2 standard. Consider using <option>fido2-device=</option>
+ (described below) to enroll it via FIDO2 instead. Note that a security token enrolled via PKCS#11
+ cannot be used to unlock the volume via FIDO2, unless also enrolled via FIDO2, and vice
+ versa.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>fido2-device=</option></term>
+
+ <listitem><para>Takes either the special value <literal>auto</literal> or the path to a
+ <literal>hidraw</literal> device node (e.g. <filename>/dev/hidraw1</filename>) referring to a FIDO2
+ security token that implements the <literal>hmac-secret</literal> extension (most current hardware
+ security tokens do). See below for an example how to set up this mechanism for unlocking an encrypted
+ volume with a FIDO2 security token.</para>
+
+ <para>If specified as <literal>auto</literal> the FIDO2 token device is automatically discovered, as
+ it is plugged in.</para>
+
+ <para>FIDO2 volume unlocking requires a client ID hash (CID) to be configured via
+ <option>fido2-cid=</option> (see below) and a key to pass to the security token's HMAC functionality
+ (configured in the line's third column) to operate. If not configured and the volume is of type
+ LUKS2, the CID and the key are read from LUKS2 JSON token metadata instead. Use
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ as simple tool for enrolling FIDO2 security tokens, compatible with this automatic mode, which is
+ only available for LUKS2 volumes.</para>
+
+ <para>Use <command>systemd-cryptenroll --fido2-device=list</command> to list all suitable FIDO2
+ security tokens currently plugged in, along with their device nodes.</para>
+
+ <para>This option implements the following mechanism: the configured key is hashed via they HMAC
+ keyed hash function the FIDO2 device implements, keyed by a secret key embedded on the device. The
+ resulting hash value is Base64 encoded and used to unlock the LUKS2 volume. As it should not be
+ possible to extract the secret from the hardware token, it should not be possible to retrieve the
+ hashed key given the configured key — without possessing the hardware token.</para>
+
+ <para>Note that many security tokens that implement FIDO2 also implement PKCS#11, suitable for
+ unlocking volumes via the <option>pkcs11-uri=</option> option described above. Typically the newer,
+ simpler FIDO2 standard is preferable.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>fido2-cid=</option></term>
+
+ <listitem><para>Takes a Base64 encoded FIDO2 client ID to use for the FIDO2 unlock operation. If
+ specified, but <option>fido2-device=</option> is not, <option>fido2-device=auto</option> is
+ implied. If <option>fido2-device=</option> is used but <option>fido2-cid=</option> is not, the volume
+ must be of LUKS2 type, and the CID is read from the LUKS2 JSON token header. Use
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ for enrolling a FIDO2 token in the LUKS2 header compatible with this automatic
+ mode.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>fido2-rp=</option></term>
+
+ <listitem><para>Takes a string, configuring the FIDO2 Relying Party (rp) for the FIDO2 unlock
+ operation. If not specified <literal>io.systemd.cryptsetup</literal> is used, except if the the LUKS2
+ JSON token header contains a different value. It should normally not be necessary to override
+ this.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>tpm2-device=</option></term>
+
+ <listitem><para>Takes either the special value <literal>auto</literal> or the path to a device node
+ (e.g. <filename>/dev/tpmrm0</filename>) referring to a TPM2 security chip. See below for an example
+ how to set up this mechanism for unlocking an encrypted volume with a TPM2 chip.</para>
+
+ <para>Use <option>tpm2-pcrs=</option> (see below) to configure the set of TPM2 PCRs to bind the
+ volume unlocking to. Use
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ as simple tool for enrolling TPM2 security chips in LUKS2 volumes.</para>
+
+ <para>If specified as <literal>auto</literal> the TPM2 device is automatically discovered. Use
+ <command>systemd-cryptenroll --tpm2-device=list</command> to list all suitable TPM2 devices currently
+ available, along with their device nodes.</para>
+
+ <para>This option implements the following mechanism: when enrolling a TPM2 device via
+ <command>systemd-cryptenroll</command> on a LUKS2 volume, a randomized key unlocking the volume is
+ generated on the host and loaded into the TPM2 chip where it is encrypted with an asymmetric
+ "primary" key pair derived from the TPM2's internal "seed" key. Neither the seed key nor the primary
+ key are permitted to ever leave the TPM2 chip — however, the now encrypted randomized key may. It is
+ saved in the LUKS2 volume JSON token header. When unlocking the encrypted volume, the primary key
+ pair is generated on the TPM2 chip again (which works as long as the chip's seed key is correctly
+ maintained by the TPM2 chip), which is then used to decrypt (on the TPM2 chip) the encrypted key from
+ the LUKS2 volume JSON token header saved there during enrollment. The resulting decrypted key is then
+ used to unlock the volume. When the randomized key is encrypted the current values of the selected
+ PCRs (see below) are included in the operation, so that different PCR state results in different
+ encrypted keys and the decrypted key can only be recovered if the same PCR state is
+ reproduced.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>tpm2-pcrs=</option></term>
+
+ <listitem><para>Takes a comma separated list of numeric TPM2 PCR (i.e. "Platform Configuration
+ Register") indexes to bind the TPM2 volume unlocking to. This option is only useful when TPM2
+ enrollment metadata is not available in the LUKS2 JSON token header already, the way
+ <command>systemd-cryptenroll</command> writes it there. If not used (and no metadata in the LUKS2
+ JSON token header defines it), defaults to a list of a single entry: PCR 7. Assign an empty string to
+ encode a policy that binds the key to no PCRs, making the key accessible to local programs regardless
+ of the current PCR state.</para></listitem>
</varlistentry>
<varlistentry>
<programlisting><constant>NUL</constant> <replaceable>RANDOM</replaceable> <literal>/cryptsetup/</literal> <replaceable>VOLUME</replaceable></programlisting>
<para>In other words: a <constant>NUL</constant> byte (as required for abstract namespace sockets),
- followed by a random string (consisting of alphabenumeric characters only), followed by the literal
+ followed by a random string (consisting of alphanumeric characters only), followed by the literal
string <literal>/cryptsetup/</literal>, followed by the name of the volume to acquire they key
for. Example (for a volume <literal>myvol</literal>):</para>
name with <citerefentry
project='man-pages'><refentrytitle>getpeername</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
and use it to determine which key to send, allowing a single listening socket to serve keys for a
- multitude of volumes. If the PKCS#11 logic is used (see below) the socket source name is picked in
- identical fashion, except that the literal string <literal>/cryptsetup-pkcs11/</literal> is used. This is
+ multitude of volumes. If the PKCS#11 logic is used (see above) the socket source name is picked in
+ identical fashion, except that the literal string <literal>/cryptsetup-pkcs11/</literal> is used (similar
+ for FIDO2: <literal>/cryptsetup-fido2/</literal> and TPM2: <literal>/cryptsetup-tpm2/</literal>). This is
done so that services providing key material know that not a secret key is requested but an encrypted key
- that will be decrypted via the PKCS#11 logic to acquire the final secret key.</para>
+ that will be decrypted via the PKCS#11/FIDO2/TPM2 logic to acquire the final secret key.</para>
</refsect1>
+
<refsect1>
<title>Examples</title>
<example>
</example>
<example>
- <title>Yubikey-based Volume Unlocking Example</title>
+ <title>Yubikey-based PKCS#11 Volume Unlocking Example</title>
<para>The PKCS#11 logic allows hooking up any compatible security token that is capable of storing RSA
- decryption keys. Here's an example how to set up a Yubikey security token for this purpose, using
- <citerefentry project='debian'><refentrytitle>ykmap</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- from the yubikey-manager project:</para>
+ decryption keys for unlocking an encrypted volume. Here's an example how to set up a Yubikey security
+ token for this purpose on a LUKS2 volume, using <citerefentry
+ project='debian'><refentrytitle>ykmap</refentrytitle><manvolnum>1</manvolnum></citerefentry> from the
+ yubikey-manager project to initialize the token and
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ to add it in the LUKS2 volume:</para>
<programlisting><xi:include href="yubikey-crypttab.sh" parse="text" /></programlisting>
-<para>A few notes on the above:</para>
+ <para>A few notes on the above:</para>
+
+ <itemizedlist>
+ <listitem><para>We use RSA2048, which is the longest key size current Yubikeys support</para></listitem>
+ <listitem><para>We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes,
+ <ulink url="https://developers.yubico.com/PIV/Introduction/Certificate_slots.html">see
+ documentation</ulink>.</para></listitem>
+ </itemizedlist>
+ </example>
+
+ <example>
+ <title>FIDO2 Volume Unlocking Example</title>
+
+ <para>The FIDO2 logic allows using any compatible FIDO2 security token that implements the
+ <literal>hmac-secret</literal> extension for unlocking an encrypted volume. Here's an example how to
+ set up a FIDO2 security token for this purpose for a LUKS2 volume, using
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>:</para>
+
+<programlisting><xi:include href="fido2-crypttab.sh" parse="text" /></programlisting>
+ </example>
+
+ <example>
+ <title>TPM2 Volume Unlocking Example</title>
-<itemizedlist>
- <listitem><para>We use RSA2048, which is the longest key size current Yubikeys support</para></listitem>
- <listitem><para>LUKS key size must be shorter than 2048bit due to RSA padding, hence we use 128 bytes</para></listitem>
- <listitem><para>We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes,
- <ulink url="https://developers.yubico.com/PIV/Introduction/Certificate_slots.html">see
- documentation</ulink>.</para></listitem>
-</itemizedlist>
+ <para>The TPM2 logic allows using any TPM2 chip supported by the Linux kernel for unlocking an
+ encrypted volume. Here's an example how to set up a TPM2 chip for this purpose for a LUKS2 volume,
+ using
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>:</para>
+<programlisting><xi:include href="tpm2-crypttab.sh" parse="text" /></programlisting>
</example>
</refsect1>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
--- /dev/null
+# Enroll the security token in the LUKS2 volume. Replace /dev/sdXn by the
+# partition to use (e.g. /dev/sda1).
+sudo systemd-cryptenroll --fido2-device=auto /dev/sdXn
+
+# Test: Let's run systemd-cryptsetup to test if this worked.
+sudo /usr/lib/systemd/systemd-cryptsetup attach mytest /dev/sdXn - fido2-device=auto
+
+# If that worked, let's now add the same line persistently to /etc/crypttab,
+# for the future.
+sudo bash -c 'echo "mytest /dev/sdXn - fido2-device=auto" >> /etc/crypttab'
<varlistentry>
<term><varname>Encrypt=</varname></term>
- <listitem><para>Takes a boolean parameter, defaulting to false. If true the partition will be
+ <listitem><para>Takes one of <literal>off</literal>, <literal>key-file</literal>,
+ <literal>tpm2</literal> and <literal>key-file+tpm2</literal> (alternatively, also accepts a boolean
+ value, which is mapped to <literal>off</literal> when false, and <literal>key-file</literal> when
+ true). Defaults to <literal>off</literal>. If not <literal>off</literal> the partition will be
formatted with a LUKS2 superblock, before the blocks configured with <varname>CopyBlocks=</varname>
are copied in or the file system configured with <varname>Format=</varname> is created.</para>
- <para>The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion. A single
- key is added to the LUKS2 superblock, configurable with the <option>--key-file=</option> switch to
+ <para>The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion. If
+ <literal>key-file</literal> or <literal>key-file+tpm2</literal> is used a key is added to the LUKS2
+ superblock, configurable with the <option>--key-file=</option> switch to
+ <command>systemd-repart</command>. If <literal>tpm2</literal> or <literal>key-file+tpm2</literal> is
+ used a key is added to the LUKS2 superblock that is enrolled to the local TPM2 chip, as configured
+ with the <option>--tpm2-device=</option> and <option>--tpm2-pcrs=</option> options to
<command>systemd-repart</command>.</para>
<para>When used this slightly alters the size allocation logic as the implicit, minimal size limits
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
- <citerefentry project='man-pages'><refentrytitle>sfdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ <citerefentry project='man-pages'><refentrytitle>sfdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
'8',
['systemd-coredump.socket', 'systemd-coredump@.service'],
'ENABLE_COREDUMP'],
+ ['systemd-cryptenroll', '1', [], 'HAVE_LIBCRYPTSETUP'],
['systemd-cryptsetup-generator', '8', [], 'HAVE_LIBCRYPTSETUP'],
['systemd-cryptsetup@.service',
'8',
--- /dev/null
+<?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 <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">DEVICE</arg></command>
+ </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>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>
+
+ <listitem><para>Regular passphrases</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>
+ </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></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--recovery-key</option></term>
+
+ <listitem><para>Enroll a recovery key. Recovery keys are most identical to passphrases, but are
+ computer generated instead of human chosen, 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></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
+ smart card 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></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). 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></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></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 the enrollment
+ requested via <option>--tpm2-device=</option> to. Takes a comma separated list of numeric PCR indexes
+ in the range 0…23. If not used, defaults to PCR 7 only. If an empty string is specified, binds the
+ enrollment to no PCRs at all. PCRs allow binding the enrollment to specific software versions and
+ system state, so that the enrolled unlocking key is only accessible (may be "unsealed") if specific
+ trusted software and/or configuration is used.</para></listitem>
+
+ <table>
+ <title>Well-known PCR Definitions</title>
+
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname="pcr" />
+ <colspec colname="definition" />
+
+ <thead>
+ <row>
+ <entry>PCR</entry>
+ <entry>Explanation</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>Core system firmware executable code; changes on firmware updates</entry>
+ </row>
+
+ <row>
+ <entry>1</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>Extended or pluggable executable code; includes option ROMs on pluggable hardware</entry>
+ </row>
+
+ <row>
+ <entry>3</entry>
+ <entry>Extended or pluggable firmware data; includes information about pluggable hardware</entry>
+ </row>
+
+ <row>
+ <entry>4</entry>
+ <entry>Boot loader; changes on boot loader updates</entry>
+ </row>
+
+ <row>
+ <entry>5</entry>
+ <entry>GPT/Partition table; changes when the partitions are added, modified or removed</entry>
+ </row>
+
+ <row>
+ <entry>6</entry>
+ <entry>Power state events; changes on system suspend/sleep</entry>
+ </row>
+
+ <row>
+ <entry>7</entry>
+ <entry>Secure boot state; changes when UEFI SecureBoot mode is enabled/disabled</entry>
+ </row>
+
+ <row>
+ <entry>8</entry>
+ <entry><citerefentry><refentrytitle>sd-boot</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures the kernel command line in this PCR.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </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 crated 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>
+ </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>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>
+ </para>
+ </refsect1>
+
+</refentry>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
<orderedlist>
<listitem><para>If a key file is explicitly configured (via the third column in
- <filename>/etc/crypttab</filename>), a key read from it is used. If a PKCS#11 token is configured
- (using the <varname>pkcs11-uri=</varname> option) the key is decrypted before use.</para></listitem>
+ <filename>/etc/crypttab</filename>), a key read from it is used. If a PKCS#11 token, FIDO2 token or
+ TPM2 device is configured (using the <varname>pkcs11-uri=</varname>, <varname>fido2-device=</varname>,
+ <varname>tpm2-device=</varname> options) the key is decrypted before use.</para></listitem>
<listitem><para>If no key file is configured explicitly this way, a key file is automatically loaded
from <filename>/etc/cryptsetup-keys.d/<replaceable>volume</replaceable>.key</filename> and
<filename>/run/cryptsetup-keys.d/<replaceable>volume</replaceable>.key</filename>, if present. Here
- too, if a PKCS#11 token is configured, any key found this way is decrypted before
+ too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before
use.</para></listitem>
<listitem><para>If the <varname>try-empty-password</varname> option is specified it is then attempted
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>
<term><option>--key-file=</option></term>
<listitem><para>Takes a file system path. Configures the encryption key to use when setting up LUKS2
- volumes configured with the <varname>Encrypt=</varname> setting in partition files. Should refer to a
- regular file containing the key, or an <constant>AF_UNIX</constant> stream socket in the file
- system. In the latter case a connection is made to it and the key read from it. If this switch is not
- specified the empty key (i.e. zero length key) is used. This behaviour is useful for setting up encrypted
- partitions during early first boot that receive their user-supplied password only in a later setup
- step.</para></listitem>
+ volumes configured with the <varname>Encrypt=key-file</varname> setting in partition files. Should
+ refer to a regular file containing the key, or an <constant>AF_UNIX</constant> stream socket in the
+ file system. In the latter case a connection is made to it and the key read from it. If this switch
+ is not specified the empty key (i.e. zero length key) is used. This behaviour is useful for setting
+ up encrypted partitions during early first boot that receive their user-supplied password only in a
+ later setup step.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--tpm2-device=</option></term>
+ <term><option>--tpm2-pcrs=</option></term>
+
+ <listitem><para>Configures the TPM2 device and list of PCRs to use for LUKS2 volumes configured with
+ the <varname>Encrypt=tpm2</varname> option. These options take the same parameters as the identically
+ named options to
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ and have the same effect on partitions where TPM2 enrollment is requested.</para></listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="help" />
</variablelist>
</refsect1>
+ <refsect1>
+ <title>Exit status</title>
+
+ <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
+ </refsect1>
+
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
--- /dev/null
+# Enroll the TPM2 security chip in the LUKS2 volume, and bind it to PCR 7
+# only. Replace /dev/sdXn by the partition to use (e.g. /dev/sda1).
+sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=7 /dev/sdXn
+
+# Test: Let's run systemd-cryptsetup to test if this worked.
+sudo /usr/lib/systemd/systemd-cryptsetup attach mytest /dev/sdXn - tpm2-device=auto
+
+# If that worked, let's now add the same line persistently to /etc/crypttab,
+# for the future.
+sudo bash -c 'echo "mytest /dev/sdXn - tpm2-device=auto" >> /etc/crypttab'
-# Make sure no one can read the files we generate but us
-umask 077
-
# Destroy any old key on the Yubikey (careful!)
ykman piv reset
-# Generate a new private/public key pair on the device, store the public key in 'pubkey.pem'.
+# Generate a new private/public key pair on the device, store the public key in
+# 'pubkey.pem'.
ykman piv generate-key -a RSA2048 9d pubkey.pem
# Create a self-signed certificate from this public key, and store it on the
-# device. The "subject" should be an arbitrary string to identify the token in
-# the p11tool output below.
+# device. The "subject" should be an arbitrary user-chosen string to identify
+# the token with.
ykman piv generate-certificate --subject "Knobelei" 9d pubkey.pem
-# Check if the newly create key on the Yubikey shows up as token in PKCS#11. Have a look at the output, and
-# copy the resulting token URI to the clipboard.
-p11tool --list-tokens
-
-# Generate a (secret) random key to use as LUKS decryption key.
-dd if=/dev/urandom of=plaintext.bin bs=128 count=1
-
-# Encode the secret key also as base64 text (with all whitespace removed)
-base64 < plaintext.bin | tr -d '\n\r\t ' > plaintext.base64
-
-# Encrypt this newly generated (binary) LUKS decryption key using the public key whose private key is on the
-# Yubikey, store the result in /etc/cryptsetup-keys.d/mytest.key, where we'll look for it during boot.
-mkdir -p /etc/cryptsetup-keys.d
-sudo openssl rsautl -encrypt -pubin -inkey pubkey.pem -in plaintext.bin -out /etc/cryptsetup-keys.d/mytest.key
-
-# Configure the LUKS decryption key on the LUKS device. We use very low pbkdf settings since the key already
-# has quite a high quality (it comes directly from /dev/urandom after all), and thus we don't need to do much
-# key derivation. Replace /dev/sdXn by the partition to use (e.g. sda1)
-sudo cryptsetup luksAddKey /dev/sdXn plaintext.base64 --pbkdf=pbkdf2 --pbkdf-force-iterations=1000
-
-# Now securely delete the plain text LUKS key, we don't need it anymore, and since it contains secret key
-# material it should be removed from disk thoroughly.
-shred -u plaintext.bin plaintext.base64
-
-# We don't need the public key anymore either, let's remove it too. Since this one is not security
-# sensitive we just do a regular "rm" here.
+# We don't need the public key anymore, let's remove it. Since it is not
+# security sensitive we just do a regular "rm" here.
rm pubkey.pem
-# Test: Let's run systemd-cryptsetup to test if this all worked. The option string should contain the full
-# PKCS#11 URI we have in the clipboard; it tells the tool how to decipher the encrypted LUKS key. Note that
-# systemd-cryptsetup automatically searches for the encrypted key in /etc/cryptsetup-keys.d/, hence we do
-# not need to specify the key file path explicitly here.
-sudo systemd-cryptsetup attach mytest /dev/sdXn - 'pkcs11-uri=pkcs11:…'
+# Enroll the freshly initialized security token in the LUKS2 volume. Replace
+# /dev/sdXn by the partition to use (e.g. /dev/sda1).
+sudo systemd-cryptenroll --pkcs11-token-uri=auto /dev/sdXn
+
+# Test: Let's run systemd-cryptsetup to test if this all worked.
+sudo /usr/lib/systemd/systemd-cryptsetup attach mytest /dev/sdXn - pkcs11-uri=auto
-# If that worked, let's now add the same line persistently to /etc/crypttab, for the future.
-sudo bash -c 'echo "mytest /dev/sdXn - \'pkcs11-uri=pkcs11:…\'" >> /etc/crypttab'
+# If that worked, let's now add the same line persistently to /etc/crypttab,
+# for the future.
+sudo bash -c 'echo "mytest /dev/sdXn - pkcs11-uri=auto" >> /etc/crypttab'
projects / thirdparty / systemd.git / commitdiff
