# systemd-cryptsetup

## NAME



           systemd-cryptsetup, systemd-cryptsetup@.service - Full disk
           decryption logic
    


## SYNOPSIS



    
           **systemd-cryptsetup**[OPTIONS...] attach VOLUME SOURCE-DEVICE
                              [KEY-FILE] [CRYPTTAB-OPTIONS]
    
           **systemd-cryptsetup**[OPTIONS...] detach VOLUME
    
           systemd-cryptsetup@.service
    
           system-systemd\x2dcryptsetup.slice
    


## DESCRIPTION



           **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 bysystemd-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. If the _password-cache=_ option is set to "yes" or "read-only",
               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.
    


## CREDENTIALS



           **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.
    


## NOTES



            1. password agent logic
               https://systemd.io/PASSWORD_AGENTS/
    
            2. TPM2 PCR Measurements Made by systemd
               https://systemd.io/TPM2_PCR_MEASUREMENTS
    


* * *