systemd-creds

Encrypt a file and set a specific name

$ systemd-creds encrypt --name [name] [path/to/input_file] [path/to/output]

$ systemd-creds decrypt [path/to/input_file] [path/to/output_file]

$ echo -n [text] | systemd-creds encrypt --name [name] - [path/to/output]

$ echo -n [text] | systemd-creds encrypt --name [name] --pretty - - >> [service]

$ systemd-creds encrypt --not-after "[timestamp]" [path/to/input_file] [path/to/output_file]

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

COMMAND
    Specifies the operation to perform. Common commands include:
list: Lists all available credentials.
get NAME: Retrieves the value of a specific credential by its name.
set NAME: Sets or updates the value of a credential. If not specified via --file, it reads from standard input.
rm NAME: Removes a specific credential.

--file=PATH
    Used with the set command to specify a file from which to read the credential's value. If omitted, the value is read from standard input.

--raw
    When used with get, outputs the raw credential value without any metadata. When used with set, indicates that the input is a raw credential value, bypassing any automatic JSON parsing.

--json=pretty|yes|no
    Controls JSON output. pretty formats output for readability. yes outputs compact JSON. no (default) uses plain text for relevant commands.

--no-pager
    Do not pipe output into a pager.

--no-legend
    Do not print the legend (column headers) for table output.

--help
    Shows a short help text and exits.

--version
    Shows a short version string and exits.

The systemd-creds command-line utility is designed to manage sensitive credentials (such as API keys, passwords, and certificates) within the systemd ecosystem. It provides a secure mechanism for services to access this data without hardcoding it or relying on less secure methods like environment variables.

Credentials are stored in an encrypted format, typically in /etc/systemd/creds for system-wide services or ~/.config/systemd/creds for user services. Services declare their need for specific credentials in their unit files using the Credential= option, allowing systemd to provide the decrypted data to the service at runtime, often via a temporary file descriptor.

This tool helps enforce the principle of least privilege and reduces the attack surface by centralizing credential management and ensuring sensitive data is not exposed unnecessarily.

Permissions: Managing system-wide credentials typically requires root privileges. User-specific credentials can be managed by the respective user.

Encryption: Credentials are encrypted using system-specific or user-specific keys. This means credentials might not be easily portable between different systems or users without manual decryption and re-encryption.

Security Implications: While systemd-creds enhances security by centralizing management, the underlying system's security (e.g., key protection, physical access) remains paramount. Credentials are only as secure as the system hosting them.

System-wide credentials are typically stored in /etc/systemd/creds/, while user-specific credentials reside in ~/.config/systemd/creds/. These directories contain encrypted blobs of data, which systemd-creds decrypts and manages.

Services declare their need for specific credentials in their .service unit files using the Credential= directive (e.g., Credential=api-key:/path/to/api-key.txt). systemd then provides the decrypted credential to the service, often via a temporary file descriptor or a file path in a secure, ephemeral filesystem, which the service can then read.

systemd-creds was introduced as part of the systemd suite in version 249 (released around 2021). Its development aimed to provide a more robust and standardized method for managing sensitive data used by services, addressing limitations of prior approaches like environment variables or hardcoded paths, and integrating credential management directly into the systemd ecosystem.

systemd(1), systemd.exec(5), systemd.unit(5), systemd-creds-secrets(7)