diff options
Diffstat (limited to 'man/crypttab.xml')
| -rw-r--r-- | man/crypttab.xml | 97 |
1 files changed, 65 insertions, 32 deletions
diff --git a/man/crypttab.xml b/man/crypttab.xml index 126d3a0..955111f 100644 --- a/man/crypttab.xml +++ b/man/crypttab.xml @@ -1,7 +1,7 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <!-- SPDX-License-Identifier: LGPL-2.1-or-later @@ -104,10 +104,14 @@ 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> + smartcard. In this case a saved key used in unlock process is stored on disk/removable media, acquired via + <constant>AF_UNIX</constant>, or stored in the LUKS2 JSON token metadata header. For RSA, the saved key + is an encrypted volume key. The encrypted volume key is then decrypted by the PKCS#11 token with an RSA + private key stored on it, and used to unlock the encrypted volume. For elliptic-curve (EC) cryptography, + the saved key is the public key generated in enrollment process. The public key is then used to derive + a shared secret with a private key stored in the PKCS#11 token. The derived shared secret is then used + to unlock the volume. Use the <option>pkcs11-uri=</option> option described below to use this mechanism. + </para></listitem> <listitem><para>Similarly, the key may be acquired via a FIDO2 compatible hardware security token (which must implement the "hmac-secret" extension). In this case a key generated randomly during @@ -257,6 +261,29 @@ </varlistentry> <varlistentry> + <term><option>link-volume-key=</option></term> + + <listitem><para>Specifies the kernel keyring and key description + (see <citerefentry project='man-pages'><refentrytitle>keyrings</refentrytitle><manvolnum>7</manvolnum></citerefentry>) + where LUKS2 volume key gets linked during device activation. The kernel keyring + description and key description must be separated by <literal>::</literal>.</para> + + <para>The kernel keyring part can be a string description or a predefined + kernel keyring prefixed with <literal>@</literal> (e.g.: to use <literal>@s</literal> session or + <literal>@u</literal> user keyring directly). The type prefix text in the kernel keyring description + is not required. The specified kernel keyring must already exist at the time of device activation.</para> + + <para>The key part is a string description optionally prefixed by a <literal>%key_type:</literal>. + If no type is specified, the <literal>user</literal> type key is linked by default. See + <citerefentry project='man-pages'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for more information on key descriptions (KEY IDENTIFIERS section).</para> + + <para>Note that the linked volume key is not cleaned up automatically when the device is detached.</para> + + <xi:include href="version-info.xml" xpointer="v256"/></listitem> + </varlistentry> + + <varlistentry> <term><option>luks</option></term> <listitem><para>Force LUKS mode. When this mode is used, the @@ -322,7 +349,9 @@ unsuccessful. Note that other units that depend on the unlocked device may still fail. In particular, if the device is used for a mount point, the mount point itself also needs to have the <option>nofail</option> option, or the boot will fail if the device is not unlocked - successfully.</para> + successfully. If a keyfile and/or a <option>header</option> are specified, the dependencies on + their respective directories will also not be fatal, so that umounting said directories will + not cause the generated cryptset unit to be deactivated.</para> <xi:include href="version-info.xml" xpointer="v186"/></listitem> </varlistentry> @@ -452,10 +481,12 @@ <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This option implies <option>plain</option>.</para> - <para>WARNING: Using the <option>swap</option> option will - destroy the contents of the named partition during every boot, - so make sure the underlying block device is specified - correctly.</para> + <warning> + <para>Using the <option>swap</option> option will + destroy the contents of the named partition during every boot, + so make sure the underlying block device is specified + correctly.</para> + </warning> <xi:include href="version-info.xml" xpointer="v186"/></listitem> </varlistentry> @@ -585,8 +616,10 @@ <literal>btrfs</literal>. If no argument is specified defaults to <literal>ext4</literal>. This option implies <option>plain</option>.</para> - <para>WARNING: Using the <option>tmp</option> option will destroy the contents of the named partition - during every boot, so make sure the underlying block device is specified correctly.</para> + <warning> + <para>Using the <option>tmp</option> option will destroy the contents of the named partition + during every boot, so make sure the underlying block device is specified correctly.</para> + </warning> <xi:include href="version-info.xml" xpointer="v186"/></listitem> </varlistentry> @@ -641,7 +674,7 @@ <term><option>pkcs11-uri=</option></term> <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 + url="https://tools.ietf.org/html/rfc7512">RFC7512 PKCS#11 URI</ulink> pointing to a private 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 @@ -651,16 +684,16 @@ 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 + as a 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 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>The specified URI can refer directly to a private key stored on a token or alternatively + just to a slot or token, in which case a search for a suitable private key will be performed. In + this case if multiple suitable objects are found the token is refused. The keyfile configured + in the third column of the line is used as is (i.e. in binary form, unprocessed). The resulting + decrypted key (for RSA) or derived shared secret (for ECC) 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> @@ -967,8 +1000,8 @@ external /dev/sda3 keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchac <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 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 + or EC cryptographic 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> @@ -1012,16 +1045,16 @@ external /dev/sda3 keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchac <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>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>, - <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> + <para><simplelist type="inline"> + <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> + <member><citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + </simplelist></para> </refsect1> </refentry> |