systemd-creds

systemd-creds
is a utility and service provided by
systemd
, designed to securely store and retrieve credentials used by
systemd
units. It aims to simplify the management of sensitive information, such as usernames, passwords, API keys, and other authentication data, required by various services and applications.
See
https://systemd.io/CREDENTIALS/
and
systemd-creds(1)
for more information.
Credential encryption
Credentials may optionally be encrypted and authenticated, either with a key derived from a local
TPM
2 chip, or one stored in
/var/
, or both (the default) if available. To check if your system uses TPM2 encryption or only the key stored in
/var/
, run
$ systemd-analyze has-tpm2
yes
+firmware
+driver
+system
+subsystem
To encrypt a secret stored in
plaintext.txt
, run
# systemd-creds --name=
foobar
encrypt
plaintext.txt ciphertext.cred
Note
In case of sensitive credentials, consider using a tmpfs for
plaintext.txt
Encrypted credentials carry the intended name in them, so they cannot be mispurposed. If you omit
--name
, then the filename will be used as credential name.
You can check that encryption was successful with
# shred -u
plaintext.txt
# systemd-run --pipe --wait --property=LoadCredentialEncrypted=
foobar
:$(pwd)/
ciphertext.cred
systemd-creds cat
foobar
Without using
--name
above, the correct command would be
# systemd-run --pipe --wait --property=LoadCredentialEncrypted=
ciphertext.cred
:$(pwd)/
ciphertext.cred
systemd-creds cat
ciphertext.cred
Alternatively, you can use
systemd-ask-password
to provide the secret without first writing it to disk. The
-p
switch allows outputting a credential in a format ready to be included in a service file:
# systemd-ask-password -n | systemd-creds encrypt --name=mysql-password -p - -
🔐 Password: ***************         
SetCredentialEncrypted=mysql-password: \
       k6iUCUh0RJCQyvL8k8q1UyAAAAABAAAADAAAABAAAAD42X4T5h86ynMHG5MAAAAAgAAAA \
       AAAAAALACMA8AAAACAAAAAAngAgws4cwpkrOvpxVf4/GSyOYCoQ4dmPs3Vcfg3D0eH/Ov \
       cAEC/U9JTyeHgktYBDl8U5jOq/NqFX3IPc24EX7aeTevsL6OKwlTDcF04W1M6eodqngRo \
       1JfRqHWnSfVHHYVXgMjIkWT4AcC0OoqAzQobK5e5G1zjTPygiG/ewGttY9sueKCL/INUu \
       n1e6/QB6D9T0x9Sl18CeBtoASepCAE4ACAALAAAAEgAgY9RHOefBR+mMgV/Frr+UzQX1S \
       IsLFItIbfB6Ep76It0AEAAgKH2Tduip205Dw0GVkME+yvOUNYVhnSHYqWHQoxelKrdj1E \
       c558FH6YyBX8Wuv5TNBfVIiwsUi0ht8HoSnvoi3QAAAAA3WzuXTYG2OFX9wFo740b3YjE \
       ZtiCWakoAOxzX+D/vIFyB3INROxpfXUCV7LY4eRITI9PJZiE6lGn4kjZBnbUf47yo1WDG \
       Wg==
Edit
the service file to include the relevant credential
User credential encryption
The systemd-creds utility can also be used by a regular user.
$ echo -n
hunter2
| systemd-creds --user encrypt -
ciphertext.cred
$ systemd-creds --user decrypt
ciphertext.cred
hunter2
As mentioned in
systemd-creds(1)
, the user's scope and the
/etc/machine-id
are used to encrypt the credential. For example, a root user may decrypt it, but only matching the
user
scope:
$ systemd-creds --uid
anotheruser
decrypt
ciphertext.cred
Failed to decrypt: io.systemd.InteractiveAuthenticationRequired
# systemd-creds decrypt
ciphertext.cred
Encrypted file is scoped to a user, but no user selected.
# systemd-creds --uid
user
decrypt
ciphertext.cred
hunter2