--- /dev/null
+---
+title: Credentials
+category: Concepts
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# System and Service Credentials
+
+The `systemd` service manager supports a "credential" concept for securely
+acquiring and passing credential data to systems and services. The precise
+nature of the credential data is up to applications, but the concept is
+intended to provide systems and services with potentially security sensitive
+cryptographic keys, certificates, passwords, identity information and similar
+types of information. It may also be used as generic infrastructure for
+parameterizing systems and services.
+
+Traditionally, data of this nature has often been provided to services via
+environment variables (which is problematic because by default they are
+inherited down the process tree, have size limitations, and issues with binary
+data) or simple, unencrypted files on disk. `systemd`'s system and service
+credentials are supposed to provide a better alternative for this
+purpose. Specifically, the following features are provided:
+
+1. Service credentials are acquired at the moment of service activation, and
+ released on service deactivation. They are immutable during the service
+ runtime.
+
+2. Service credentials are accessible to service code as regular files, the
+ path to access them is derived from the environment variable
+ `$CREDENTIALS_DIRECTORY`.
+
+3. Access to credentials is restricted to the service's user. Unlike
+ environment variables the credential data is not propagated down the process
+ tree. Instead each time a credential is accessed an access check is enforced
+ by the kernel. If the service is using file system namespacing the loaded
+ credential data is invisble to any other services.
+
+4. Service credentials may be acquired from files on disk, specified as literal
+ strings in unit files, acquired from another service dynamically via an
+ `AF_UNIX` socket, or inherited from the system credentials the system itself
+ received.
+
+5. Credentials may optionally be encrypted and authenticated, either with a key
+ derived from a local TPM2 chip, or one stored in `/var/`, or both. This
+ encryption is supposed to *just* *work*, and requires no manual setup. (That
+ is besides first encrypting relevant credentials with one simple command,
+ see below.)
+
+6. Service credentials are placed in non-swappable memory. (If permissions
+ allow it, via `ramfs`.)
+
+7. Credentials may be acquired from a hosting VM hypervisor (qemu `fw_cfg`), a
+ hosting container manager, the kernel command line, or from the UEFI
+ environment and the EFI System Partition (via `systemd-stub`). Such system
+ credentials may then be propagated into individual services as needed.
+
+8. Credentials are an effective way to pass parameters into services that run
+ with `RootImage=` or `RootDirectory=` and thus cannot read these resources
+ directly from the host directory tree. Specifically, [Portable
+ Services](https://systemd.io/PORTABLE_SERVICES) may be parameterized this
+ way securely and robustly.
+
+9. Credentials can be binary and relatively large (though currently an overall
+ size limit of 1M per service is enforced).
+
+## Configuring per-Service Credentials
+
+Within unit files, there are four settings to configure service credentials.
+
+1. `LoadCredential=` may be used to load a credential from disk, from an
+ `AF_UNIX` socket, or propagate them from a system credential.
+
+2. `SetCredential=` may be used to set a credential to a literal string encoded
+ in the unit file. Because unit files are world-readable (both on disk and
+ via D-Bus), this should only be used for credentials that aren't sensitive,
+ i.e. public keys/certificates – but not private keys.
+
+3. `LoadCredentialEncrypted=` is similar to `LoadCredential=` but will load an
+ encrypted credential, and decrypt it before passing it to the service. For
+ details on credential encryption, see below.
+
+4. `SetCredentialEncrypted=` is similar to `SetCredential=` but expects an
+ encrypted credential to be specified literally. Unlike `SetCredential=` it
+ is thus safe to be used even for sensitive information, because even though
+ unit files are world readable, the ciphertext included in them cannot be
+ decoded unless access to TPM2/encryption key is available.
+
+Each credential configured with these options carries a short name (suitable
+for inclusion in a filename) in the unit file, under which the invoked service
+code can then retrieve it. Each name should only be specified once.
+
+For details about these four settings [see the man
+page](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Credentials).
+
+It is a good idea to also enable mount namespacing for services that process
+credentials configured this way. If so, the runtime credential directory of the
+specific service is not visible to any other service. Use `PrivateMounts=` as
+minimal option to enable such namespacing. Note that many other sandboxing
+settings (e.g. `ProtectSystem=`, `ReadOnlyPaths=` and similar) imply
+`PrivateMounts=`, hence oftentimes it's not necessary to set this option
+explicitly.
+
+## Programming Interface from Service Code
+
+When a service is invoked with one or more credentials set it will have an
+environment variable `$CREDENTIALS_DIRECTORY` set. It contains an absolute path
+to a directory the credentials are placed in. In this directory for each
+configured credential one file is placed. In addition to the
+`$CREDENTIALS_DIRECTORY` environment variable passed to the service processes
+the `%d` specifier in unit files resolves to the service's credential
+directory.
+
+Example unit file:
+
+```
+…
+[Service]
+ExecStart=/usr/bin/myservice.sh
+LoadCredential=foobar:/etc/myfoobarcredential.txt
+Environment=FOOBARPATH=%d/foobar
+…
+```
+
+Associated service shell script `/usr/bin/myservice.sh`:
+
+```sh
+#!/bin/sh
+
+sha256sum $CREDENTIAL_PATH/foobar
+sha256sum $FOOBARPATH
+
+```
+
+A service defined like this will get the contents of the file
+`/etc/myfoobarcredential.txt` passed as credential `foobar`, which is hence
+accessible under `$CREDENTIALS_DIRECTORY/foobar`. Since we additionally pass
+the path to it as environment variable `$FOOBARPATH` the credential is also
+accessible as the path in that environment variable. When invoked, the service
+will hence show the same SHA256 hash value of `/etc/myfoobarcredential.txt`
+twice.
+
+In an ideal world, well-behaved service code would directly support credentials
+passed this way, i.e. look for `$CREDENTIALS_DIRECTORY` and load the credential
+data it needs from there. For daemons that do not support this but allow
+passing credentials via a path supplied over the command line use
+`${CREDENTIAL_PATH}` in the `ExecStart=` command line to reference the
+credentials directory. For daemons that allow passing credentials via a path
+supplied as environment variabe, use the `%d` specifier in the `Environment=`
+setting to build valid paths to specific credentials.
+
+## Tools
+
+The
+[`systemd-creds`](https://www.freedesktop.org/software/systemd/man/systemd-creds.html)
+tool is provided to work with system and service credentials. It may be used to
+access and enumerate system and service credentials, or to encrypt/decrypt credentials
+(for details about the latter, see below).
+
+When invoked from service context, `systemd-creds` passed without further
+parameters will list passed credentials. The `systemd-creds cat xyz` command
+may be used to write the contents of credential `xyz` to standard output. If
+these calls are combined with the `--system` switch credentials passed to the
+system as a whole are shown, instead of the those passed to the service the
+command is invoked from.
+
+Example use:
+
+```sh
+systemd-run -P --wait -p LoadCredential=abc:/etc/hosts systemd-creds cat abc
+```
+
+This will invoke a transient service with a credential `abc` sourced from the
+system's `/etc/hosts` file. This credential is then written to standard output
+via `systemd-creds cat`.
+
+## Encryption
+
+Credentials are supposed to be useful for carrying sensitive information, such
+as cryptographic key material. For this kind of data (symmetric) encryption and
+authentication is provided to make storage of the data at rest safer. The data
+may be encrypted and authenticated with AES256-GCM. The encryption key can
+either be one derived from the local TPM2 device, or one stored in
+`/var/lib/systemd/credential.secret`, or a combination of both. If a TPM2
+device is available and `/var/` resides on persistent storage the default
+behaviour is to use the combination of both for encryption, thus ensuring that
+credentials protected this way can only be decrypted and validated on the
+local hardware and OS installation. Encrypted credentials stored on disk thus
+cannot be decrypted without access to the TPM2 chip and the aforementioned key
+file `/var/lib/systemd/credential.secret`. Moreover, credentials cannot be
+prepared on another machine than the local one.
+
+The `systemd-creds` tool provides the commands `encrypt` and `decrypt` to
+encrypt and decrypt/authenticate credentials. Example:
+
+```sh
+systemd-creds encrypt plaintext.txt ciphertext.cred
+shred -u plaintext-txt
+systemd-run -P --wait -p LoadCredentialEncrypted=foobar:$(pwd)/ciphertext.cred systemd-creds cat foobar
+```
+
+This will first create an encrypted copy of the file `plaintext.txt` in the
+encrypted credential file `ciphertext.cred`. It then securely removes the
+source file. It then runs a transient service, that reads the encrypted file
+and passes it as decrypted credential `foobar` to the invoked service binary
+(which here is the `systemd-creds` tool, which just writes the data
+it received to standard output).
+
+Instead of storing the encrypted credential as a separate file on disk, it can
+also be embedded in the unit file. Example:
+
+```
+systemd-creds encrypt -p --name=foobar plaintext.txt -
+```
+
+This will output a `SetCredentialEncrypted=` line that can directly be used in
+a unit file. e.g.:
+
+```
+…
+[Service]
+ExecStart=/usr/bin/systemd-creds cat foobar
+SetCredentialEncrypted=foobar: \
+ k6iUCUh0RJCQyvL8k8q1UyAAAAABAAAADAAAABAAAAC1lFmbWAqWZ8dCCQkAAAAAgAAAA \
+ AAAAAALACMA0AAAACAAAAAAfgAg9uNpGmj8LL2nHE0ixcycvM3XkpOCaf+9rwGscwmqRJ \
+ cAEO24kB08FMtd/hfkZBX8PqoHd/yPTzRxJQBoBsvo9VqolKdy9Wkvih0HQnQ6NkTKEdP \
+ HQ08+x8sv5sr+Mkv4ubp3YT1Jvv7CIPCbNhFtag1n5y9J7bTOKt2SQwBOAAgACwAAABIA \
+ ID8H3RbsT7rIBH02CIgm/Gv1ukSXO3DMHmVQkDG0wEciABAAII6LvrmL60uEZcp5qnEkx \
+ SuhUjsDoXrJs0rfSWX4QAx5PwfdFuxPusgEfTYIiCb8a/W6RJc7cMweZVCQMbTARyIAAA \
+ AAJt7Q9F/Gz0pBv1Lc4Dpn1WpebyBBm+vQ5N/lSKW2XSm8cONwCopxpDc7wJjXg7OTR6r \
+ xGCpIvGXLt3ibwJl81woLya2RRjIvc/R2zNm/yWzZAjiOLPih4SuHthqiX98ey8PUmZJB \
+ VGXglCZFjBx+d7eCqTIdghtp5pkDGwMJT6pjw4FfyFK2nJPawFKPAqzw9DK2iYttFeXi5 \
+ 19xCfLBH9NKS/idlYXrhp+XIEtsr26s4lx5y10Goyc3qDOR3RD2cuZj0gHwV35hhhhcCz \
+ JaYytef1X/YL+7fYH5kuE4rxSksoUuA/LhtjszBeGbcbIT+O8SuvBJHLKTSHxPL8FTyk3 \
+ L4FSkEHs0rYwUIkKmnGohDdsYrMJ2fjH3yDNBP16aD1+f/Nuh75cjhUnGsDLt9K4hGg== \
+…
+```
+
+## Inheritance from Container Managers, Hypervisors, Kernel Command Line, or the UEFI Boot Environment
+
+Sometimes it is useful to parameterize whole systems the same way as services,
+via `systemd` credentials. In particular, it might make sense to boot a
+system with a set of credentials that are then propagated to individual
+services where they are ultimately consumed.
+
+`systemd` supports four ways to pass credentials to systems:
+
+1. A container manager may set the `$CREDENTIALS_DIRECTORY` environment
+ variable for systemd running as PID 1 in the container, the same way as
+ systemd would set it for a service it
+ invokes. [`systemd-nspawn(1)`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#Credentials)'s
+ `--set-credential=` and `--load-credential=` switches implement this, in
+ order to pass arbitrary credentials from host to container payload. Also see
+ the [Container Interface](https://systemd.io/CONTAINER_INTERFACE)
+ documentation.
+
+2. Quite similar, qemu VMs can be invoked with `-fw_cfg
+ name=opt/io.systemd.credentials/foo,string=bar` to pass credentials from
+ host through the hypervisor into the VM. (This specific switch would set
+ credential `foo` to `bar`.)
+
+3. Credentials can also be passed into a system via the kernel command line,
+ via the `systemd.set-credential=` kernel command line option. Note though
+ that any data specified here is visible to any userspace application via
+ `/proc/cmdline`. This is hence typically not useful to pass sensitive
+ information.
+
+4. Credentials may also be passed from the UEFI environment to userspace, if
+ the
+ [`systemd-stub`](https://www.freedesktop.org/software/systemd/man/systemd-stub.html)
+ UEFI kernel stub is used. This allows placing encrypted credentials in the
+ EFI System Partition, which are then picked up by `systemd-stub` and passed
+ to the kernel and ultimately userpace where systemd receives them. This is
+ useful to implement secure parameterization of vendor-built and signed
+ initial RAM disks, as userspace can place credentials next to these EFI
+ kernels, and be sure they can be accessed securely from initrd context.
+
+Credentials passed to the system may be enumerated/displayed via `systemd-creds
+--system`. They may also be propagated down to services, via the
+`LoadCredential=` setting. Example:
+
+```
+systemd-nspawn --set-credential=mycred:supersecret -i test.raw -b
+```
+
+or
+
+```
+qemu-system-x86_64 \
+ -machine type=q35,accel=kvm,smm=on \
+ -smp 2 \
+ -m 1G \
+ -cpu host \
+ -nographic \
+ -nodefaults \
+ -serial mon:stdio \
+ -drive if=none,id=hd,file=test.raw,format=raw \
+ -device virtio-scsi-pci,id=scsi \
+ -device scsi-hd,drive=hd,bootindex=1 \
+ -fw_cfg name=opt/io.systemd.credentials/mycred,string=supersecret
+```
+
+Either of these lines will boot a disk image `test.raw`, once as container via
+`systemd-nspawn`, and once as VM via `qemu`. In each case the credential
+`mycred` is set to `supersecret`.
+
+Inside of the system invoked that way the credential may then be viewed:
+
+```sh
+systemd-creds --system cat mycred
+```
+
+Or propagated to services further down:
+
+```
+systemd-run -p LoadCredential=mycred -P --wait systemd-creds cat mycred
+```
+
+## Well-Known Credentials
+
+Various services shipped with `systemd` consume credentials for tweaking behaviour:
+
+* [`systemd-sysusers(8)`](https://www.freedesktop.org/software/systemd/man/systemd-sysusers.html)
+ will look for the credentials `passwd.hashed-password.<username>`,
+ `passwd.plaintext-password.<username>` and `passwd.shell.<username>` to
+ configure the password (either in UNIX hashed form, or plaintext) or shell of
+ system users created. Replace `<username>` with the system user of your
+ choice, for example `root`.
+
+* [`systemd-firstboot(1)`](https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html)
+ will look for the credentials `firstboot.locale`, `firstboot.locale-messages`,
+ `firstboot.keymap`, `firstboot.timezone`, that configure locale, keymap or
+ timezone settings in case the data is not yet set in `/etc/`.
+
+In future more services are likely to gain support for consuming credentials.
+
+Example:
+
+```
+systemd-nspawn -i test.raw \
+ --set-credential=passwd.hashed-password.root:$(mkpasswd mysecret) \
+ --set-credential=firstboot.locale:C.UTF-8 \
+ -b
+```
+
+This boots the specified disk image as `systemd-nspawn` container, and passes
+the root password `mysecret`and default locale `C.UTF-8` to use to it. This
+data is then propagated by default to `systemd-sysusers.service` and
+`systemd-firstboot.service`, where it is applied. (Note that these services
+will only do so if these settings in `/etc/` are so far unset, i.e. they only
+have an effect on *unprovisioned* systems, and will never override data already
+established in `/etc/`.) A similar line for qemu is:
+
+```
+qemu-system-x86_64 \
+ -machine type=q35,accel=kvm,smm=on \
+ -smp 2 \
+ -m 1G \
+ -cpu host \
+ -nographic \
+ -nodefaults \
+ -serial mon:stdio \
+ -drive if=none,id=hd,file=test.raw,format=raw \
+ -device virtio-scsi-pci,id=scsi \
+ -device scsi-hd,drive=hd,bootindex=1 \
+ -fw_cfg name=opt/io.systemd.credentials/passwd.hashed-password.root,string=$(mkpasswd mysecret) \
+ -fw_cfg name=opt/io.systemd.credentials/firstboot.locale,string=C.UTF-8
+```
+
+## Relevant Paths
+
+From *service* perspective the runtime path to find loaded credentials in is
+provided in the `$CREDENTIALS_DIRECTORY` environment variable.
+
+At runtime, credentials passed to the *system* are placed in
+`/run/credentials/@system/` (for regular credentials, such as those passed from
+a container manager or via qemu) and `/run/credentials/@encrypted/` (for
+credentials that must be decrypted/validated before use, such as those from
+`systemd-stub`).
+
+The `LoadCredential=` and `LoadCredentialEncrypted=` settings when configured
+with a relative source path will search for the source file to read the
+credential from automatically. Primarily, these credentials are searched among
+the credentials passed into the system. If not found there, they are searched
+in `/etc/credstore/`, `/run/credstore/`,
+`/usr/lib/credstore/`. `LoadCredentialEncrypted=` will also search
+`/etc/credstore.encrypted/` and similar directories. These directories are
+hence a great place to store credentials to load on the system.
projects / thirdparty / systemd.git / commitdiff
