From cf1e172d58b0c0fb3e09ba9b5e6c60093b5b896c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 7 Dec 2020 17:18:52 +0100 Subject: [PATCH] man: document new features --- man/crypttab.xml | 281 ++++++++++++++++++++++---- man/fido2-crypttab.sh | 10 + man/repart.d.xml | 16 +- man/rules/meson.build | 1 + man/systemd-cryptenroll.xml | 284 +++++++++++++++++++++++++++ man/systemd-cryptsetup-generator.xml | 1 + man/systemd-cryptsetup@.service.xml | 8 +- man/systemd-repart.xml | 32 ++- man/tpm2-crypttab.sh | 10 + man/yubikey-crypttab.sh | 54 ++--- 10 files changed, 603 insertions(+), 94 deletions(-) create mode 100644 man/fido2-crypttab.sh create mode 100644 man/systemd-cryptenroll.xml create mode 100644 man/tpm2-crypttab.sh diff --git a/man/crypttab.xml b/man/crypttab.xml index 0c0f091025d..2062a5b8e70 100644 --- a/man/crypttab.xml +++ b/man/crypttab.xml @@ -45,13 +45,12 @@ The first two fields are mandatory, the remaining two are optional. - Setting up encrypted block devices using this file supports - three encryption modes: LUKS, TrueCrypt and plain. See - cryptsetup8 - 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. + Setting up encrypted block devices using this file supports four encryption modes: LUKS, TrueCrypt, + BitLocker and plain. See cryptsetup8 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. The four fields of /etc/crypttab are defined as follows: @@ -65,9 +64,10 @@ UUID= followed by the UUID. The third field specifies an absolute path to a file with the encryption - key. Optionally, the path may be followed by : and an fstab device specification - (e.g. starting with LABEL= or similar); in which case the path is taken relative to - the device file system root. If the field is not present or is none or + key. Optionally, the path may be followed by : and an + /etc/fstab style device specification (e.g. starting with + LABEL= 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 none or -, a key file named after the volume to unlock (i.e. the first column of the line), suffixed with .key is automatically loaded from the /etc/cryptsetup-keys.d/ and /run/cryptsetup-keys.d/ @@ -83,6 +83,60 @@ The fourth field, if present, is a comma-delimited list of options. The supported options are listed below. + + + + Key Acquisition + + Six different mechanisms for acquiring the decryption key or passphrase unlocking the encrypted + volume are supported. Specifically: + + + + 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). + + 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. + + The (unencrypted) key may be requested from another service, by specifying an + AF_UNIX file system socket in place of a key file in the third field. For details + see above and below. + + 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 + AF_UNIX, 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 described below to use this mechanism. + + 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 AF_UNIX, 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 described + below to use this mechanism. + + 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 AF_UNIX, or stored in the + LUKS2 JSON token metadata header. Use the option described below to use + this mechanism. + + + 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 /etc/crypttab line, but may also + configured in /etc/cryptsetup-keys.d/ and + /run/cryptsetup-keys.d/ (see above) or in the LUKS2 JSON token header (in case of + the latter three). Use the + systemd-cryptenroll1 + tool to enroll PKCS#11, FIDO2 and TPM2 devices in LUKS2 volumes. + + + + Supported Options + + The following options may be used in the fourth field of each line: @@ -125,10 +179,10 @@ for possible values and the default value of this option. - Optionally, the path may be followed by : and an fstab device specification - (e.g. starting with UUID= 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. - + Optionally, the path may be followed by : and an + /etc/fstab device specification (e.g. starting with UUID= 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. @@ -198,8 +252,8 @@ - Decrypt Bitlocker drive. Encryption parameters - are deduced by cryptsetup from Bitlocker header. + Decrypt BitLocker drive. Encryption parameters + are deduced by cryptsetup from BitLocker header. @@ -269,7 +323,7 @@ - Perform encryption using the same cpu that IO was submitted on. The default is to use + 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. This requires kernel 4.0 or newer. @@ -451,15 +505,134 @@ - Takes a RFC7512 PKCS#11 URI - 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 + Takes either the special value auto or an RFC7512 PKCS#11 URI 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. + + If specified as auto 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 + systemd-cryptenroll1 + as simple tool for enrolling PKCS#11 security tokens or smartcards in a way compatible with + auto. In this mode the third column of the line should remain empty (that is, + specified as -). + + 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. + 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. + + Use systemd-cryptenroll --pkcs11-token-uri=list to list all suitable PKCS#11 + security tokens currently plugged in, along with their URIs. + + 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 + (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. + + + + + + Takes either the special value auto or the path to a + hidraw device node (e.g. /dev/hidraw1) referring to a FIDO2 + security token that implements the hmac-secret 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. + + If specified as auto the FIDO2 token device is automatically discovered, as + it is plugged in. + + FIDO2 volume unlocking requires a client ID hash (CID) to be configured via + (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 + systemd-cryptenroll1 + as simple tool for enrolling FIDO2 security tokens, compatible with this automatic mode, which is + only available for LUKS2 volumes. + + Use systemd-cryptenroll --fido2-device=list to list all suitable FIDO2 + security tokens currently plugged in, along with their device nodes. + + 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. + + Note that many security tokens that implement FIDO2 also implement PKCS#11, suitable for + unlocking volumes via the option described above. Typically the newer, + simpler FIDO2 standard is preferable. + + + + + + Takes a Base64 encoded FIDO2 client ID to use for the FIDO2 unlock operation. If + specified, but is not, is + implied. If is used but is not, the volume + must be of LUKS2 type, and the CID is read from the LUKS2 JSON token header. Use + systemd-cryptenroll1 + for enrolling a FIDO2 token in the LUKS2 header compatible with this automatic + mode. + + + + + + Takes a string, configuring the FIDO2 Relying Party (rp) for the FIDO2 unlock + operation. If not specified io.systemd.cryptsetup is used, except if the the LUKS2 + JSON token header contains a different value. It should normally not be necessary to override + this. + + + + + + Takes either the special value auto or the path to a device node + (e.g. /dev/tpmrm0) 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. + + Use (see below) to configure the set of TPM2 PCRs to bind the + volume unlocking to. Use + systemd-cryptenroll1 + as simple tool for enrolling TPM2 security chips in LUKS2 volumes. + + If specified as auto the TPM2 device is automatically discovered. Use + systemd-cryptenroll --tpm2-device=list to list all suitable TPM2 devices currently + available, along with their device nodes. + + This option implements the following mechanism: when enrolling a TPM2 device via + systemd-cryptenroll 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. + + + + + + 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 + systemd-cryptenroll 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. @@ -523,7 +696,7 @@ NUL RANDOM /cryptsetup/ VOLUME In other words: a NUL 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 /cryptsetup/, followed by the name of the volume to acquire they key for. Example (for a volume myvol): @@ -533,11 +706,13 @@ name with getpeername2, 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 /cryptsetup-pkcs11/ 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 /cryptsetup-pkcs11/ is used (similar + for FIDO2: /cryptsetup-fido2/ and TPM2: /cryptsetup-tpm2/). 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. + that will be decrypted via the PKCS#11/FIDO2/TPM2 logic to acquire the final secret key. + Examples @@ -556,25 +731,48 @@ external /dev/sda3 keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchac - Yubikey-based Volume Unlocking Example + Yubikey-based PKCS#11 Volume Unlocking Example 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 - ykmap1 - from the yubikey-manager project: + 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 ykmap1 from the + yubikey-manager project to initialize the token and + systemd-cryptenroll1 + to add it in the LUKS2 volume: -A few notes on the above: + A few notes on the above: - - We use RSA2048, which is the longest key size current Yubikeys support - LUKS key size must be shorter than 2048bit due to RSA padding, hence we use 128 bytes - We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes, - see - documentation. - + + We use RSA2048, which is the longest key size current Yubikeys support + We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes, + see + documentation. + + + + FIDO2 Volume Unlocking Example + + The FIDO2 logic allows using any compatible FIDO2 security token that implements the + hmac-secret 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 + systemd-cryptenroll1: + + + + + + TPM2 Volume Unlocking Example + + 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 + systemd-cryptenroll1: + + @@ -584,6 +782,7 @@ external /dev/sda3 keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchac systemd1, systemd-cryptsetup@.service8, systemd-cryptsetup-generator8, + systemd-cryptenroll1, fstab5, cryptsetup8, mkswap8, diff --git a/man/fido2-crypttab.sh b/man/fido2-crypttab.sh new file mode 100644 index 00000000000..49e536cae8d --- /dev/null +++ b/man/fido2-crypttab.sh @@ -0,0 +1,10 @@ +# 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' diff --git a/man/repart.d.xml b/man/repart.d.xml index 6e31843a083..66debd336f1 100644 --- a/man/repart.d.xml +++ b/man/repart.d.xml @@ -492,12 +492,19 @@ Encrypt= - Takes a boolean parameter, defaulting to false. If true the partition will be + Takes one of off, key-file, + tpm2 and key-file+tpm2 (alternatively, also accepts a boolean + value, which is mapped to off when false, and key-file when + true). Defaults to off. If not off the partition will be formatted with a LUKS2 superblock, before the blocks configured with CopyBlocks= are copied in or the file system configured with Format= is created. - 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 switch to + The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion. If + key-file or key-file+tpm2 is used a key is added to the LUKS2 + superblock, configurable with the switch to + systemd-repart. If tpm2 or key-file+tpm2 is + used a key is added to the LUKS2 superblock that is enrolled to the local TPM2 chip, as configured + with the and options to systemd-repart. When used this slightly alters the size allocation logic as the implicit, minimal size limits @@ -627,7 +634,8 @@ SizeMaxBytes=64M systemd1, systemd-repart8, - sfdisk8 + sfdisk8, + systemd-cryptenroll1 diff --git a/man/rules/meson.build b/man/rules/meson.build index 97136fe7585..cada4305a77 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -825,6 +825,7 @@ manpages = [ '8', ['systemd-coredump.socket', 'systemd-coredump@.service'], 'ENABLE_COREDUMP'], + ['systemd-cryptenroll', '1', [], 'HAVE_LIBCRYPTSETUP'], ['systemd-cryptsetup-generator', '8', [], 'HAVE_LIBCRYPTSETUP'], ['systemd-cryptsetup@.service', '8', diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml new file mode 100644 index 00000000000..17a546b2563 --- /dev/null +++ b/man/systemd-cryptenroll.xml @@ -0,0 +1,284 @@ + + + + + + + + systemd-cryptenroll + systemd + + + + systemd-cryptenroll + 1 + + + + systemd-cryptenroll + Enroll PKCS#11, FIDO2, TPM2 token/devices to LUKS2 encrypted volumes + + + + + systemd-cryptenroll OPTIONS DEVICE + + + + + Description + + systemd-cryptenroll 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: + + + PKCS#11 security tokens and smartcards that may carry an RSA key pair (e.g. various YubiKeys) + + FIDO2 security tokens that implement the hmac-secret extension (most FIDO2 keys, including YubiKeys) + + TPM2 security devices + + 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. + + Regular passphrases + + + 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. + + 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. + + + + Options + + The following options are understood: + + + + + + Enroll a regular password/passphrase. This command is mostly equivalent to + cryptsetup luksAddKey, however may be combined with + in one call, see below. + + + + + + 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. + + + + URI + + 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 auto 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 list 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. + + In order to unlock a LUKS2 volume with an enrolled PKCS#11 security token, specify the + option in the respective /etc/crypttab line: + + myvolume /dev/sda1 - pkcs11-uri=auto + + See + crypttab5 for a + more comprehensive example of a systemd-cryptenroll invocation and its matching + /etc/crypttab line. + + + + PATH + + Enroll a FIDO2 security token that implements the hmac-secret + extension (e.g. a YubiKey). Expects a hidraw device referring to the FIDO2 + device (e.g. /dev/hidraw1). Alternatively the special value + auto 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 + list 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. + + In order to unlock a LUKS2 volume with an enrolled FIDO2 security token, specify the + option in the respective /etc/crypttab line: + + myvolume /dev/sda1 - fido2-device=auto + + See + crypttab5 for a + more comprehensive example of a systemd-cryptenroll invocation and its matching + /etc/crypttab line. + + + + PATH + + Enroll a TPM2 security chip. Expects a device node path referring to the TPM2 chip + (e.g. /dev/tpmrm0). Alternatively the special value auto 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 list may be used to + enumerate all suitable TPM2 devices currently discovered. + + In order to unlock a LUKS2 volume with an enrolled TPM2 security chip, specify the + option in the respective /etc/crypttab line: + + myvolume /dev/sda1 - tpm2-device=auto + + See + crypttab5 for a + more comprehensive example of a systemd-cryptenroll invocation and its matching + /etc/crypttab line. + + Use (see below) to configure which TPM2 PCR indexes to bind the + enrollment to. + + + + PCR + + Configures the TPM2 PCRs (Platform Configuration Registers) to bind the enrollment + requested via 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. + + + Well-known PCR Definitions + + + + + + + + PCR + Explanation + + + + + + 0 + Core system firmware executable code; changes on firmware updates + + + + 1 + Core system firmware data/host platform configuration; typically contains serial and model numbers, changes on basic hardware/CPU/RAM replacements + + + + 2 + Extended or pluggable executable code; includes option ROMs on pluggable hardware + + + + 3 + Extended or pluggable firmware data; includes information about pluggable hardware + + + + 4 + Boot loader; changes on boot loader updates + + + + 5 + GPT/Partition table; changes when the partitions are added, modified or removed + + + + 6 + Power state events; changes on system suspend/sleep + + + + 7 + Secure boot state; changes when UEFI SecureBoot mode is enabled/disabled + + + + 8 + sd-boot8 measures the kernel command line in this PCR. + + + +
+ + + + + SLOT + + Wipes one or more LUKS2 key slots. Takes a comma separated list of numeric slot + indexes, or the special strings all (for wiping all key slots), + empty (for wiping all key slots that are unlocked by an empty passphrase), + password (for wiping all key slots that are unlocked by a traditional passphrase), + recovery (for wiping all key slots that are unlocked by a recovery key), + pkcs11 (for wiping all key slots that are unlocked by a PKCS#11 token), + fido2 (for wiping all key slots that are unlocked by a FIDO2 token), + tpm2 (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. + + 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: + + systemd-cryptenroll /dev/sda1 --wipe-slot=tpm2 --tpm2-device=auto + + 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: + + systemd-cryptenroll /dev/sda1 --wipe-slot=pkcs11 --fido2-device=auto + + Or for replacing an enrolled empty password by TPM2: + + systemd-cryptenroll /dev/sda1 --wipe-slot=empty --tpm2-device=auto + + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code otherwise. + + + + See Also + + systemd1, + systemd-cryptsetup@.service8, + crypttab5, + cryptsetup8 + + + + diff --git a/man/systemd-cryptsetup-generator.xml b/man/systemd-cryptsetup-generator.xml index 4284f78c4e0..e5c193f6920 100644 --- a/man/systemd-cryptsetup-generator.xml +++ b/man/systemd-cryptsetup-generator.xml @@ -228,6 +228,7 @@ systemd1, crypttab5, systemd-cryptsetup@.service8, + systemd-cryptenroll1, cryptsetup8, systemd-fstab-generator8 diff --git a/man/systemd-cryptsetup@.service.xml b/man/systemd-cryptsetup@.service.xml index 216db7467c4..c70d6a9d3ed 100644 --- a/man/systemd-cryptsetup@.service.xml +++ b/man/systemd-cryptsetup@.service.xml @@ -50,13 +50,14 @@ If a key file is explicitly configured (via the third column in - /etc/crypttab), a key read from it is used. If a PKCS#11 token is configured - (using the pkcs11-uri= option) the key is decrypted before use. + /etc/crypttab), a key read from it is used. If a PKCS#11 token, FIDO2 token or + TPM2 device is configured (using the pkcs11-uri=, fido2-device=, + tpm2-device= options) the key is decrypted before use. If no key file is configured explicitly this way, a key file is automatically loaded from /etc/cryptsetup-keys.d/volume.key and /run/cryptsetup-keys.d/volume.key, 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. If the try-empty-password option is specified it is then attempted @@ -77,6 +78,7 @@ systemd1, systemd-cryptsetup-generator8, crypttab5, + systemd-cryptenroll1, cryptsetup8 diff --git a/man/systemd-repart.xml b/man/systemd-repart.xml index 16add32b2d4..858b5be66d7 100644 --- a/man/systemd-repart.xml +++ b/man/systemd-repart.xml @@ -300,12 +300,23 @@ Takes a file system path. Configures the encryption key to use when setting up LUKS2 - volumes configured with the Encrypt= setting in partition files. Should refer to a - regular file containing the key, or an AF_UNIX 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. + volumes configured with the Encrypt=key-file setting in partition files. Should + refer to a regular file containing the key, or an AF_UNIX 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. + + + + + + + Configures the TPM2 device and list of PCRs to use for LUKS2 volumes configured with + the Encrypt=tpm2 option. These options take the same parameters as the identically + named options to + systemd-cryptenroll1 + and have the same effect on partitions where TPM2 enrollment is requested. @@ -313,12 +324,19 @@ + + Exit status + + On success, 0 is returned, a non-zero failure code otherwise. + + See Also systemd1, repart.d5, - machine-id5 + machine-id5, + systemd-cryptenroll1 diff --git a/man/tpm2-crypttab.sh b/man/tpm2-crypttab.sh new file mode 100644 index 00000000000..41db2aeddda --- /dev/null +++ b/man/tpm2-crypttab.sh @@ -0,0 +1,10 @@ +# 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' diff --git a/man/yubikey-crypttab.sh b/man/yubikey-crypttab.sh index 651246d6a1e..05e581b32b5 100644 --- a/man/yubikey-crypttab.sh +++ b/man/yubikey-crypttab.sh @@ -1,50 +1,26 @@ -# 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 -# 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' +# 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=auto" >> /etc/crypttab'