'\" t
.TH "SYSTEMD\-CRYPTSETUP" "8" "" "systemd 259.6" "systemd-cryptsetup"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd-cryptsetup, systemd-cryptsetup@.service \- Full disk decryption logic
.SH "SYNOPSIS"
.HP \w'\fBsystemd\-cryptsetup\fR\ 'u
\fBsystemd\-cryptsetup\fR [OPTIONS...] attach VOLUME SOURCE\-DEVICE [KEY\-FILE] [CRYPTTAB\-OPTIONS]
.HP \w'\fBsystemd\-cryptsetup\fR\ 'u
\fBsystemd\-cryptsetup\fR [OPTIONS...] detach VOLUME
.PP
systemd\-cryptsetup@\&.service
.PP
system\-systemd\ex2dcryptsetup\&.slice
.SH "DESCRIPTION"
.PP
\fBsystemd\-cryptsetup\fR
is used to set up (with
\fBattach\fR) and tear down (with
\fBdetach\fR) 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
\fIVOLUME\fR,
\fISOURCE\-DEVICE\fR,
\fIKEY\-FILE\fR, and
\fICRYPTTAB\-OPTIONS\fR
have the same meaning as the fields in
\fBcrypttab\fR(5)\&.
.PP
systemd\-cryptsetup@\&.service
is a service responsible for providing access to encrypted block devices\&. It is instantiated for each device that requires decryption\&.
.PP
systemd\-cryptsetup@\&.service
instances are part of the
system\-systemd\ex2dcryptsetup\&.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\&.
.PP
systemd\-cryptsetup@\&.service
will ask for hard disk passwords via the
\m[blue]\fBpassword agent logic\fR\m[]\&\s-2\u[1]\d\s+2, in order to query the user for the password using the right mechanism at boot and during runtime\&.
.PP
At early boot and when the system manager configuration is reloaded,
/etc/crypttab
is translated into
systemd\-cryptsetup@\&.service
units by
\fBsystemd-cryptsetup-generator\fR(8)\&.
.PP
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:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
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
\fIpkcs11\-uri=\fR,
\fIfido2\-device=\fR,
\fItpm2\-device=\fR
options) the key is decrypted before use\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
If no key file is configured explicitly this way, a key file is automatically loaded from
/etc/cryptsetup\-keys\&.d/\fIvolume\fR\&.key
and
/run/cryptsetup\-keys\&.d/\fIvolume\fR\&.key, if present\&. Here too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before use\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
If the
\fItry\-empty\-password\fR
option is specified then unlocking the volume with an empty password is attempted\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
If the
\fIpassword\-cache=\fR
option is set to
"yes"
or
"read\-only", the kernel keyring is then checked for a suitable cached password from previous attempts\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
Finally, the user is queried for a password, possibly multiple times, unless the
\fIheadless\fR
option is set\&.
.RE
.PP
If no suitable key may be acquired via any of the mechanisms describes above, volume activation fails\&.
.SH "CREDENTIALS"
.PP
\fBsystemd\-cryptsetup\fR
supports the service credentials logic as implemented by
\fIImportCredential=\fR/\fILoadCredential=\fR/\fISetCredential=\fR
(see
\fBsystemd.exec\fR(5)
for details)\&. The following credentials are used by
"systemd\-crypsetup@root\&.service"
(generated by
\fBsystemd\-gpt\-auto\-generator\fR) when passed in:
.PP
\fIcryptsetup\&.passphrase\fR
.RS 4
This credential specifies the passphrase of the LUKS volume\&.
.sp
Added in version 256\&.
.RE
.PP
\fIcryptsetup\&.tpm2\-pin\fR
.RS 4
This credential specifies the TPM pin\&.
.sp
Added in version 256\&.
.RE
.PP
\fIcryptsetup\&.fido2\-pin\fR
.RS 4
This credential specifies the FIDO2 token pin\&.
.sp
Added in version 256\&.
.RE
.PP
\fIcryptsetup\&.pkcs11\-pin\fR
.RS 4
This credential specifies the PKCS11 token pin\&.
.sp
Added in version 256\&.
.RE
.PP
\fIcryptsetup\&.luks2\-pin\fR
.RS 4
This credential specifies the pin requested by generic LUKS2 token modules\&.
.sp
Added in version 256\&.
.RE
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBsystemd-cryptsetup-generator\fR(8), \fBcrypttab\fR(5), \fBsystemd-cryptenroll\fR(1), \fBcryptsetup\fR(8), \m[blue]\fBTPM2 PCR Measurements Made by systemd\fR\m[]\&\s-2\u[2]\d\s+2
.SH "NOTES"
.IP " 1." 4
password agent logic
.RS 4
\%https://systemd.io/PASSWORD_AGENTS/
.RE
.IP " 2." 4
TPM2 PCR Measurements Made by systemd
.RS 4
\%https://systemd.io/TPM2_PCR_MEASUREMENTS
.RE
