|
HTML rendering created 2025-02-02 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 | COMMANDS | OPTIONS | EXIT STATUS | EXAMPLES | SEE ALSO | NOTES | COLOPHON |
|
|
|
SYSTEMD-CREDS(1) systemd-creds SYSTEMD-CREDS(1)
systemd-creds - Lists, shows, encrypts and decrypts service
credentials
systemd-creds [OPTIONS...] COMMAND [ARGS...]
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.
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).
Added in version 250.
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 --json= or --transcode= the output is
transcoded in simple ways before outputting.
Added in version 250.
setup
Generates a host encryption key for credentials, if one has
not been generated already. This ensures the
/var/lib/systemd/credential.secret file is initialized with a
random secret key if it does not 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.
Added in version 250.
encrypt input|- output|-
Loads the specified (unencrypted plaintext) input credential
file, encrypts it and writes the (encrypted ciphertext) output
to the specified target 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 --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:
1. 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.
2. 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.
3. 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 --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.
decrypt input|- [output|-]
Undoes the effect of the encrypt operation: loads the
specified (encrypted ciphertext) input credential file,
decrypts and authenticates it and writes the (decrypted
plaintext) output to the specified target 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 --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.
--no-ask-password
Do not query the user for authentication for privileged
operations.
-h, --help
Print a short help text and exit.
--version
Print a short version string and exit.
--system
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.
Added in version 250.
--user
When specified with the encrypt and decrypt commands encrypts
a user-scoped (rather than a system-scoped) credential. Use
--uid= to select which user the credential is from. Such
credentials may only be decrypted from the specified user's
context, except if privileges can be acquired. Generally, when
an encrypted credential shall be used in the per-user service
manager it should be encrypted with this option set, when it
shall be used in the system service manager it should be
encrypted without.
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=
Specifies the user to encrypt the credential for. Takes a user
name or numeric UID. If set, implies --user. If set to the
special string "self" sets the user to the user of the calling
process. If --user is used without --uid= then --uid=self is
implied, i.e. the credential is encrypted for the calling
user.
Added in version 256.
--transcode=
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. The special value "help" may be used to
list supported transcode types.
Note that this has no effect on the encrypt command, as
encrypted credentials are unconditionally encoded in Base64.
Added in version 250.
--newline=
When specified with cat or decrypt controls whether to add a
trailing newline character to the end of the output if it does
not 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.
Added in version 250.
--pretty, -p
When specified with encrypt controls whether to show the
encrypted credential as SetCredentialEncrypted= setting that
may be pasted directly into a unit file. Has effect only when
used together with --name= and "-" as the output file.
Added in version 250.
--name=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 --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 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.time(7).
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
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.time(7).
Added in version 250.
--with-key=, -H, -T
When specified with the encrypt command controls the
encryption/signature key to use. Takes one of "host", "tpm2",
"host+tpm2", "null", "auto", "auto-initrd". 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. If set to "null" a fixed zero length key
is used (thus, in this mode no confidentiality nor
authenticity are provided!). This logic is useful to cover for
systems that lack a TPM2 chip but where credentials shall be
generated. Note that decryption of such credentials is refused
on systems that have a TPM2 chip and where UEFI SecureBoot is
enabled (this is done so that such a locked down system cannot
be tricked into loading a credential generated this way that
lacks authentication information). If set to "auto-initrd" a
TPM2 key is used if a TPM2 is found. If not a fixed zero
length key is used, equivalent to "null" mode. This option is
particularly useful to generate credentials files that are
encrypted/authenticated against TPM2 where available but still
work on systems lacking support for this. The special value
"help" may be used to list supported key types.
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
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.
Added in version 250.
--tpm2-pcrs=PCR[+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 an empty string is
specified, binds the encryption key to no PCRs at all (this is
also the default if this option is not used). For details
about the PCRs available, see the documentation of the switch
of the same name for systemd-cryptenroll(1).
Added in version 250.
--tpm2-public-key=PATH, --tpm2-public-key-pcrs=PCR[+PCR...]
Configures a TPM2 signed PCR policy to bind encryption to, for
use with the encrypt command. The --tpm2-public-key= option
accepts a path to a PEM encoded RSA public key, to bind the
encryption to. If this is not specified explicitly, but a file
tpm2-pcr-public-key.pem exists in one of the directories
/etc/systemd/, /run/systemd/, /usr/lib/systemd/ (searched in
this order), it is automatically used. The
--tpm2-public-key-pcrs= option takes a list of TPM2 PCR
indexes to bind to (same syntax as --tpm2-pcrs= described
above). If not specified, defaults to 11 (i.e. this binds the
policy to any unified kernel image for which a PCR signature
can be provided).
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
Takes a path to a TPM2 PCR signature file as generated by the
systemd-measure(1) tool and that may be used to allow the
decrypt command to decrypt credentials that are bound to
specific signed PCR values. If this is not specified
explicitly, and a credential with a signed PCR policy is
attempted to be decrypted, a suitable signature file
tpm2-pcr-signature.json is searched for in /etc/systemd/,
/run/systemd/, /usr/lib/systemd/ (in this order) and used.
Added in version 252.
--allow-null
Allow decrypting credentials that use an empty key.
Added in version 256.
--quiet, -q
Suppress additional output.
Added in version 251.
--no-pager
Do not pipe output into a pager.
--no-legend
Do not print the legend, i.e. column headers and the footer
with hints.
--json=MODE
Shows output formatted as JSON. Expects one of "short" (for
the shortest possible output without any redundant whitespace
or line breaks), "pretty" (for a pretty version of the same,
with indentation and line breaks) or "off" (to turn off JSON
output, the default).
On success, 0 is returned.
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: \
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 | ( 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
systemd(1), systemd.exec(5), systemd-measure(1)
1. System and Service Credentials
https://systemd.io/CREDENTIALS
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 2025-02-02. (At that
time, the date of the most recent commit that was found in the
repository was 2025-02-02.) 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 258~devel SYSTEMD-CREDS(1)
Pages that refer to this page: systemd(1), systemd-measure(1), systemd.exec(5), systemd.directives(7), systemd.generator(7), systemd.index(7), systemd-stub(7), systemd-pcrlock(8)
|
HTML rendering created 2025-02-02 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. |
|