|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | CREDENTIALS | SEE ALSO | NOTES | COLOPHON |
|
|
|
SYSTEMD-CRYPTSETUP(8) systemd-cryptsetup SYSTEMD-CRYPTSETUP(8)
systemd-cryptsetup, systemd-cryptsetup@.service - Full disk
decryption logic
systemd-cryptsetup [OPTIONS...] attach VOLUME SOURCE-DEVICE
[KEY-FILE] [CONFIG]
systemd-cryptsetup [OPTIONS...] detach VOLUME
systemd-cryptsetup@.service
system-systemd\x2dcryptsetup.slice
systemd-cryptsetup is used to set up (with attach) and tear down
(with detach) access to an encrypted block device. It is
primarily used via systemd-cryptsetup@.service during early boot,
but may also be called manually. The positional arguments VOLUME,
SOURCE-DEVICE, KEY-FILE, and CRYPTTAB-OPTIONS have the same
meaning as the fields in crypttab(5).
systemd-cryptsetup@.service is a service responsible for
providing access to encrypted block devices. It is instantiated
for each device that requires decryption.
systemd-cryptsetup@.service instances are part of the
system-systemd\x2dcryptsetup.slice slice, which is destroyed only
very late in the shutdown procedure. This allows the encrypted
devices to remain up until filesystems have been unmounted.
systemd-cryptsetup@.service will ask for hard disk passwords via
the password agent logic[1], in order to query the user for the
password using the right mechanism at boot and during runtime.
At early boot and when the system manager configuration is
reloaded, /etc/crypttab is translated into
systemd-cryptsetup@.service units by
systemd-cryptsetup-generator(8).
In order to unlock a volume a password or binary key is required.
systemd-cryptsetup@.service tries to acquire a suitable password
or binary key via the following mechanisms, tried in order:
1. 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, FIDO2 token or TPM2 device is configured (using the
pkcs11-uri=, fido2-device=, tpm2-device= options) the key is
decrypted before use.
2. 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/FIDO2/TPM2 token/device is configured, any key found
this way is decrypted before use.
3. If the try-empty-password option is specified then unlocking
the volume with an empty password is attempted.
4. The kernel keyring is then checked for a suitable cached
password from previous attempts.
5. Finally, the user is queried for a password, possibly
multiple times, unless the headless option is set.
If no suitable key may be acquired via any of the mechanisms
describes above, volume activation fails.
systemd-cryptsetup supports the service credentials logic as
implemented by ImportCredential=/LoadCredential=/SetCredential=
(see systemd.exec(5) for details). The following credentials are
used by "systemd-crypsetup@root.service" (generated by
systemd-gpt-auto-generator) when passed in:
cryptsetup.passphrase
This credential specifies the passphrase of the LUKS volume.
Added in version 256.
cryptsetup.tpm2-pin
This credential specifies the TPM pin.
Added in version 256.
cryptsetup.fido2-pin
This credential specifies the FIDO2 token pin.
Added in version 256.
cryptsetup.pkcs11-pin
This credential specifies the PKCS11 token pin.
Added in version 256.
cryptsetup.luks2-pin
This credential specifies the PIN requested by generic LUKS2
token modules.
Added in version 256.
systemd(1), systemd-cryptsetup-generator(8), crypttab(5),
systemd-cryptenroll(1), cryptsetup(8), TPM2 PCR Measurements Made
by systemd[2]
1. password agent logic
https://systemd.io/PASSWORD_AGENTS/
2. TPM2 PCR Measurements Made by systemd
https://systemd.io/TPM2_PCR_MEASUREMENTS
This page is part of the systemd (systemd system and service
manager) project. Information about the project can be found at
⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have
a bug report for this manual page, see
⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
This page was obtained from the project's upstream Git repository
⟨https://github.com/systemd/systemd.git⟩ on 2024-06-14. (At that
time, the date of the most recent commit that was found in the
repository was 2024-06-13.) If you discover any rendering
problems in this HTML version of the page, or you believe there
is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
systemd 257~devel SYSTEMD-CRYPTSETUP(8)
Pages that refer to this page: systemd-cryptenroll(1), systemd-measure(1), crypttab(5), systemd.directives(7), systemd.index(7), systemd-stub(7), systemd.system-credentials(7), pam_systemd_loadkey(8), systemd-cryptsetup-generator(8), systemd-gpt-auto-generator(8), systemd-pcrlock(8)
|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|