systemd-creds(1)

NAME#

systemd-creds - Lists, shows, encrypts and decrypts service credentials

SYNOPSIS#

systemd-creds [OPTIONS...] COMMAND [ARGS...]

DESCRIPTION#

systemd-creds is a tool for listing, showing, encrypting and decrypting unit credentials. Credentials are limited-size binary or textual objects that may be passed to unit processes. They are primarily used for passing cryptographic keys (both public and private) or certificates, user account information or identity information from the host to services.

Credentials are configured in unit files via the ImportCredential=, LoadCredential=, SetCredential=, LoadCredentialEncrypted=, and SetCredentialEncrypted= settings, see systemd.exec(5) for details.

For further information see System and Service Credentials[1] documentation.

COMMANDS#

The following commands are understood:

list

Along with each credential name, the size and security state is shown. The latter is one of "secure" (in case the credential is backed by unswappable memory, i.e. "ramfs"), "weak" (in case it is backed by any other type of memory), or "insecure" (if having any access mode that is not 0400, i.e. if readable by anyone but the owner).

Added in version 250.

catcredential...

When combined with --json= or --transcode= the output is transcoded in simple ways before outputting.

Added in version 250.

setup

Added in version 250.

encryptinput|-output|-

Takes two file system paths. The file name part of the output path is embedded as name in the encrypted credential, to ensure encrypted credentials cannot be renamed and reused for different purposes without this being noticed. The credential name to embed may be overridden with the --name= setting. The input or output paths may be specified as "-", in which case the credential data is read from/written to standard input and standard output. If the output path is specified as "-" the credential name cannot be derived from the file system path, and thus should be specified explicitly via the --name= switch.

The credential data is encrypted and authenticated symmetrically with one of the following encryption keys:

Which of the three keys shall be used for encryption may be configured with the --with-key= switch. Depending on the use-case for the encrypted credential the key to use may differ. For example, for credentials that shall be accessible from the initrd, encryption with the host key is not appropriate, since access to the host key is typically not available from the initrd. Thus, for such credentials only the TPM2 key should be used.

Encrypted credentials are always encoded in Base64.

Use decrypt (see below) to undo the encryption operation, and acquire the decrypted plaintext credential from the encrypted ciphertext credential.

The credential data is encrypted using AES256-GCM, i.e. providing both confidentiality and integrity, keyed by a SHA256 hash of one or both of the secret keys described above.

Added in version 250.

decryptinput|- [output|-]

Takes one or two file system paths. The file name part of the input path is compared with the credential name embedded in the encrypted file. If it does not match decryption fails. This is done in order to ensure that encrypted credentials are not re-purposed without this being detected. The credential name to compare with the embedded credential name may also be overridden with the --name= switch. If the input path is specified as "-", the encrypted credential is read from standard input. If only one path is specified or the output path specified as "-", the decrypted credential is written to standard output. In this mode, the expected name embedded in the credential cannot be derived from the path and should be specified explicitly with --name=.

Decrypting credentials requires access to the original TPM2 chip and/or credentials host key, see above. Information about which keys are required is embedded in the encrypted credential data, and thus decryption is entirely automatic.

Added in version 250.

-h, --help

--version

OPTIONS#

--system

Added in version 250.

--user

Internally, this ensures that the selected user's numeric UID and username, as well as the system's machine-id(5) are incorporated into the encryption key.

Added in version 256.

--uid=

Added in version 256.

--transcode=

Note that this has no effect on the encrypt command, as encrypted credentials are unconditionally encoded in Base64.

Added in version 250.

--newline=

Added in version 250.

--pretty, -p

Added in version 250.

--name=name

When specified with the decrypt command control the credential name to validate the credential name embedded in the encrypted credential with. If not specified, the name is chosen automatically from the filename component of the specified input path. If no credential name is embedded in the encrypted credential file (i.e. the --name= with an empty string was used when encrypted) the specified name has no effect as no credential name validation is done.

Embedding the credential name in the encrypted credential is done in order to protect against reuse of credentials for purposes they were not originally intended for, under the assumption the credential name is chosen carefully to encode its intended purpose.

Added in version 250.

--timestamp=timestamp

When specified with the decrypt command controls the timestamp to use to validate the "not-after" timestamp that was configured with --not-after= during encryption. If not specified, defaults to the current system time.

Added in version 250.

--not-after=timestamp

Added in version 250.

--with-key=, -H, -T

The -H switch is a shortcut for --with-key=host. Similar, -T is a shortcut for --with-key=tpm2.

When encrypting credentials that shall be used in the initrd (where /var/lib/systemd/ is typically not available) make sure to use --with-key=auto-initrd mode, to disable binding against the host secret.

This switch has no effect on the decrypt command, as information on which key to use for decryption is included in the encrypted credential already.

Added in version 250.

--tpm2-device=PATH

Added in version 250.

--tpm2-pcrs=PCR[+PCR...]

Added in version 250.

--tpm2-public-key=PATH, --tpm2-public-key-pcrs=PCR[+PCR...]

Note the difference between --tpm2-pcrs= and --tpm2-public-key-pcrs=: the former binds decryption to the current, specific PCR values; the latter binds decryption to any set of PCR values for which a signature by the specified public key can be provided. The latter is hence more useful in scenarios where software updates shall be possible without losing access to all previously encrypted secrets.

Added in version 252.

--tpm2-signature=PATH

Added in version 252.

--allow-null

Added in version 256.

--quiet, -q

Added in version 251.

--no-pager

--no-legend

--json=MODE

EXIT STATUS#

On success, 0 is returned.

EXAMPLES#

Example 1. Encrypt a password for use as credential

The following command line encrypts the specified password "hunter2", writing the result to a file password.cred.

# echo -n hunter2 | systemd-creds encrypt - password.cred

This decrypts the file password.cred again, revealing the literal password:

# systemd-creds decrypt password.cred
hunter2

Example 2. Encrypt a password and include it in a unit file

The following command line prompts the user for a password and generates a SetCredentialEncrypted= line from it for a credential named "mysql-password", suitable for inclusion in a unit file.

# systemd-ask-password -n | systemd-creds encrypt --name=mysql-password -p - -
🔐 Password: ****
SetCredentialEncrypted=mysql-password: \
\n
        k6iUCUh0RJCQyvL8k8q1UyAAAAABAAAADAAAABAAAAASfFsBoPLIm/dlDoGAAAAAAAAAA \
\n
        NAAAAAgAAAAAH4AILIOZ3w6rTzYsBy9G7liaCAd4i+Kpvs8mAgArzwuKxd0ABDjgSeO5k \
\n
        mKQc58zM94ZffyRmuNeX1lVHE+9e2YD87KfRFNoDLS7F3YmCb347gCiSk2an9egZ7Y0Xs \
\n
        700Kr6heqQswQEemNEc62k9RJnEl2q7SbcEYguegnPQUATgAIAAsAAAASACA/B90W7E+6 \
\n
        yAR9NgiIJvxr9bpElztwzB5lUJAxtMBHIgAQACCaSV9DradOZz4EvO/LSaRyRSq2Hj0ym \
\n
        gVJk/dVzE8Uxj8H3RbsT7rIBH02CIgm/Gv1ukSXO3DMHmVQkDG0wEciyageTfrVEer8z5 \
\n
        9cUQfM5ynSaV2UjeUWEHuz4fwDsXGLB9eELXLztzUU9nsAyLvs3ZRR+eEK/A==

The generated line can be pasted 1:1 into a unit file, and will ensure the acquired password will be made available in the $CREDENTIALS_DIRECTORY/mysql-password credential file for the started service.

Utilizing the unit file drop-in logic this can be used to securely pass a password credential to a unit. A similar, more comprehensive set of commands to insert a password into a service xyz.service:

# mkdir -p /etc/systemd/system/xyz.service.d
# systemd-ask-password -n | ( echo "[Service]" && systemd-creds encrypt --name=mysql-password -p - - ) >/etc/systemd/system/xyz.service.d/50-password.conf
# systemctl daemon-reload
# systemctl restart xyz.service

SEE ALSO#

systemd(1), systemd.exec(5), systemd-measure(1)

NOTES#

1.

System and Service Credentials