diff --git a/man/rules/meson.build b/man/rules/meson.build index 0f6519106a4..6dea1b76fbc 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -833,6 +833,7 @@ manpages = [ '8', ['systemd-coredump.socket', 'systemd-coredump@.service'], 'ENABLE_COREDUMP'], + ['systemd-creds', '1', [], ''], ['systemd-cryptenroll', '1', [], 'HAVE_LIBCRYPTSETUP'], ['systemd-cryptsetup-generator', '8', [], 'HAVE_LIBCRYPTSETUP'], ['systemd-cryptsetup@.service', diff --git a/man/systemd-creds.xml b/man/systemd-creds.xml new file mode 100644 index 00000000000..8ed96ca1401 --- /dev/null +++ b/man/systemd-creds.xml @@ -0,0 +1,378 @@ + + + + + + + + systemd-creds + systemd + + + + systemd-creds + 1 + + + + systemd-creds + Lists, shows, encrypts and decrypts service credentials + + + + + systemd-creds + OPTIONS + + + + + 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 LoadCredential=, + SetCredential=, LoadCredentialEncrypted= and + SetCredentialEncrypted= settings, see + systemd.exec5 for + details. + + + + Commands + + The following commands are understood: + + + + list + + Show a list of credentials passed into the current execution context. This command + shows the files in the directory referenced by the $CREDENTIALS_DIRECTORY + environment variable, and is intended to be executed from within service context. + + 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). + + + + cat credential... + + Show contents of specified credentials passed into the current execution + context. Takes one or more credential names, whose contents shall be written to standard + output. + + When combined with or the output is + transcoded in simple ways before outputting. + + + + setup + + Generates a host encryption key for credentials, if none has been generated + before. This ensures the /var/lib/systemd/credential.secret file is initialized + with a random secret key if it doesn't exist yet. This secret key is used when encrypting/decrypting + credentials with encrypt or decrypt, and is only accessible to + the root user. Note that there's typically no need to invoke this command explicitly as it is + implicitly called when encrypt is invoked, and credential host key encryption + selected. + + + + encrypt input output + + Loads the specified (unencrypted plaintext) input credential file, encrypts it and + writes the (encrypted ciphertext) version to the specified output credential file. The resulting file + may be referenced in the LoadCredentialEncrypted= setting in unit files, or its + contents used literally in SetCredentialEncrypted= settings. + + 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 + 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 switch. + + The credential data is encrypted symmetrically with one of the following encryption + keys: + + + A secret key automatically derived from the system's TPM2 chip. This encryption key + is not stored on the host system and thus decryption is only possible with access to the original + TPM2 chip. Or in other words, the credential secured in this way can only be decrypted again by the + local machine. + + A secret key stored in the /var/lib/systemd/credential.secret + file which is only accessible to the root user. This "host" encryption key is stored on the host + file system, and thus decryption is possible with access to the host file system and sufficient + privileges. The key is automatically generated when needed, but can also be created explicitly with + the setup command, see above. + + A combination of the above: an encryption key derived from both the TPM2 chip and + the host file system. This means decryption requires both access to the original TPM2 chip and the + OS installation. This is the default mode of operation if a TPM2 chip is available and + /var/lib/systemd/ resides on persistent media. + + + Which of the three keys shall be used for encryption may be configured with the + 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 initial RAM disk + (initrd) of the system 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. + + + + + decrypt input + output + + Undoes the effect of the encrypt operation: loads the specified + (encrypted ciphertext) input credential file, decrypts it and writes the (decrypted plaintext) + version to the specified output credential file. + + 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 + switch. If only one path is specified (or the output path specified as + -) it is taken as input path and the decrypted credential is written to standard + output. If the input path is specified as - the encrypted credential is read from + standard input. In this mode, the expected name embedded in the credential cannot be derived from the + path and should be specified explicitly with . + + 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. + + + + + + + + + Options + + + + + + + When specified with the list and cat commands + operates on the credentials passed to system as a whole instead of on those passed to the current + execution context. This is useful in container environments where credentials may be passed in from + the container manager. + + + + + + When specified with the cat or decrypt + commands, transcodes the output before showing it. Takes one of base64, + unbase64, hex or unhex as argument, in order + to encode/decode the credential data with Base64 or as series of hexadecimal values. + + Note that this has no effect on the encrypt command, as encrypted + credentials are unconditionally encoded in Base64. + + + + + + When specified with cat or decrypt controls + whether to add a trailing newline character to the end of the output if it doesn't end in one, + anyway. Takes one of auto, yes or no. The + default mode of auto will suffix the output with a single newline character only + when writing credential data to a TTY. + + + + + + + When specified with encrypt controls whether to show the encrypted + credential as SetCredentialEncrypted= setting that may be pasted directly into a + unit file. + + + + name + + When specified with the encrypt command controls the credential + name to embed in the encrypted credential data. If not specified the name is chosen automatically + from the filename component of the specified output path. If specified as empty string no + credential name is embedded in the encrypted credential, and no verification of credential name is + done when the credential is decrypted. + + 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 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 weren't originally intended for, under the assumption the + credential name is chosen carefully to encode its intended purpose. + + + + timestamp + + When specified with the encrypt command controls the timestamp to + embed into the encrypted credential. Defaults to the current time. Takes a timestamp specification in + the format described in + systemd.time5. + + When specified with the decrypt command controls the timestamp to use to + validate the "not-after" timestamp that was configured with during + encryption. If not specified defaults to the current system time. + + + + timestamp + + When specified with the encrypt command controls the time when the + credential shall not be used anymore. This embeds the specified timestamp in the encrypted + credential. During decryption the timestamp is checked against the current system clock, and if the + timestamp is in the past the decryption will fail. By default no such timestamp is set. Takes a + timestamp specification in the format described in + systemd.time5. + + + + + + + + When specified with the encrypt command controls the encryption + key to use. Takes one of host, tpm2, + host+tpm2 or auto. See above for details on the three key + types. If set to auto (which is the default) the TPM2 key is used if a TPM2 device + is found and not running in a container. The host key is used if + /var/lib/systemd/ is on persistent media. This means on typical systems the + encryption is by default bound to both the TPM2 chip and the OS installation, and both need to be + available to decrypt the credential again. If auto is selected but neither TPM2 is + available (or running in container) nor /var/lib/systemd/ is on persistent + media, encryption will fail. + + The switch is a shortcut for . Similar, + is a shortcut for . + + When encrypting credentials that shall be used in the initial RAM disk (initrd) where + /var/lib/systemd/ is typically not available make sure to use + 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. + + + + PATH + + Controls the TPM2 device to use. 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 suitable TPM2 device (of + which there must be exactly one). The special value list may be used to enumerate + all suitable TPM2 devices currently discovered. + + + + PCR + + Configures the TPM2 PCRs (Platform Configuration Registers) to bind the encryption + key to. Takes a + 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 encryption key to no PCRs at + all. For details about the PCRs available, see the documentation of the switch of the same name for + systemd-cryptenroll1. + + + + + + + + + + Exit status + + On success, 0 is returned. + + + + Examples + + + 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 + + + + 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: \ + k6iUCUh0RJCQyvL8k8q1UyAAAAABAAAADAAAABAAAAASfFsBoPLIm/dlDoGAAAAAAAAAA \ + NAAAAAgAAAAAH4AILIOZ3w6rTzYsBy9G7liaCAd4i+Kpvs8mAgArzwuKxd0ABDjgSeO5k \ + mKQc58zM94ZffyRmuNeX1lVHE+9e2YD87KfRFNoDLS7F3YmCb347gCiSk2an9egZ7Y0Xs \ + 700Kr6heqQswQEemNEc62k9RJnEl2q7SbcEYguegnPQUATgAIAAsAAAASACA/B90W7E+6 \ + yAR9NgiIJvxr9bpElztwzB5lUJAxtMBHIgAQACCaSV9DradOZz4EvO/LSaRyRSq2Hj0ym \ + gVJk/dVzE8Uxj8H3RbsT7rIBH02CIgm/Gv1ukSXO3DMHmVQkDG0wEciyageTfrVEer8z5 \ + 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 | 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 + + systemd1, + systemd.exec5 + + + +