shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-22 17:35:35 +03:00
Code

docs/CREDENTIALS: format text

Browse Source
This commit is contained in:
hulkoba 2024-02-26 14:01:10 +01:00
parent 77d47e6db4
commit f00b3a995f
No known key found for this signature in database
GPG Key ID: ACB6C4A3A4F2BE2F
1 changed files with 27 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
docs/CREDENTIALS.md
View File

@ -284,8 +284,8 @@ services where they are ultimately consumed.
1. A container manager may set the `$CREDENTIALS_DIRECTORY` environment 1. A container manager may set the `$CREDENTIALS_DIRECTORY` environment
variable for systemd running as PID 1 in the container, the same way as variable for systemd running as PID 1 in the container, the same way as
systemd would set it for a service it systemd would set it for a service it invokes.
invokes. [`systemd-nspawn(1)`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#Credentials)'s [`systemd-nspawn(1)`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#Credentials)'s
`--set-credential=` and `--load-credential=` switches implement this, in `--set-credential=` and `--load-credential=` switches implement this, in
order to pass arbitrary credentials from host to container payload. Also see order to pass arbitrary credentials from host to container payload. Also see
the [Container Interface](CONTAINER_INTERFACE) documentation. the [Container Interface](CONTAINER_INTERFACE) documentation.
@ -300,31 +300,27 @@ services where they are ultimately consumed.
host through the hypervisor into the VM via qemu's `fw_cfg` mechanism. (All host through the hypervisor into the VM via qemu's `fw_cfg` mechanism. (All
three of these specific switches would set credential `foo` to `bar`.) three of these specific switches would set credential `foo` to `bar`.)
Passing credentials via the SMBIOS mechanism is typically preferable over Passing credentials via the SMBIOS mechanism is typically preferable over
`fw_cfg` since it is faster and less specific to the chosen VMM `fw_cfg` since it is faster and less specific to the chosen VMM implementation.
implementation. Moreover, `fw_cfg` has a 55 character limitation on names Moreover, `fw_cfg` has a 55 character limitation on names passed that way. So some settings may not fit.
passed that way. So some settings may not fit.
3. Credentials may be passed from the initrd to the host during the initrd → 3. Credentials may be passed from the initrd to the host during the initrd → host transition.
host transition. Provisioning systems that run in the initrd may use this to Provisioning systems that run in the initrd may use this to install credentials on the system.
install credentials on the system. All files placed in All files placed in `/run/credentials/@initrd/` are imported into the set of file system credentials during the transition.
`/run/credentials/@initrd/` are imported into the set of file system The files (and their directory) are removed once this is completed.
credentials during the transition. The files (and their directory) are
removed once this is completed.
4. Credentials may also be passed from the UEFI environment to userspace, if 4. Credentials may also be passed from the UEFI environment to userspace, if
the the
[`systemd-stub`](https://www.freedesktop.org/software/systemd/man/systemd-stub.html) [`systemd-stub`](https://www.freedesktop.org/software/systemd/man/systemd-stub.html)
UEFI kernel stub is used. This allows placing encrypted credentials in the UEFI kernel stub is used.
EFI System Partition, which are then picked up by `systemd-stub` and passed 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 userspace where systemd receives them.
to the kernel and ultimately userspace where systemd receives them. This is This is useful to implement secure parameterization of vendor-built and signed
useful to implement secure parameterization of vendor-built and signed
initrds, as userspace can place credentials next to these EFI kernels, and initrds, as userspace can place credentials next to these EFI kernels, and
be sure they can be accessed securely from initrd context. be sure they can be accessed securely from initrd context.
5. Credentials can also be passed into a system via the kernel command line, 5. Credentials can also be passed into a system via the kernel command line,
via the `systemd.set_credential=` and `systemd.set_credential_binary=` via the `systemd.set_credential=` and `systemd.set_credential_binary=`
kernel command line options (the latter takes Base64 encoded binary kernel command line options (the latter takes Base64 encoded binary data).
data). Note though that any data specified here is visible to all userspace Note though that any data specified here is visible to all userspace
applications (even unprivileged ones) via `/proc/cmdline`. Typically, this applications (even unprivileged ones) via `/proc/cmdline`. Typically, this
is hence not useful to pass sensitive information, and should be avoided. is hence not useful to pass sensitive information, and should be avoided.
@ -376,20 +372,19 @@ Various services shipped with `systemd` consume credentials for tweaking behavio
* [`systemd(1)`](https://www.freedesktop.org/software/systemd/man/systemd.html) * [`systemd(1)`](https://www.freedesktop.org/software/systemd/man/systemd.html)
(I.E.: PID1, the system manager) will look for the credential `vmm.notify_socket` (I.E.: PID1, the system manager) will look for the credential `vmm.notify_socket`
and will use it to send a `READY=1` datagram when the system has finished and will use it to send a `READY=1` datagram when the system has finished
booting. This is useful for hypervisors/VMMs or other processes on the host booting.
to receive a notification via VSOCK when a virtual machine has finished booting. This is useful for hypervisors/VMMs or other processes on the host to receive a notification via VSOCK when a virtual machine has finished booting.
Note that in case the hypervisor does not support `SOCK_DGRAM` over `AF_VSOCK`, Note that in case the hypervisor does not support `SOCK_DGRAM` over `AF_VSOCK`,
`SOCK_SEQPACKET` will be tried instead. The credential payload should be in the `SOCK_SEQPACKET` will be tried instead.
form: `vsock:<CID>:<PORT>`. `vsock` may be replaced with `vsock-stream`, `vsock-dgram` or `vsock-seqpacket` The credential payload should be in the form: `vsock:<CID>:<PORT>`.
to force usage of the corresponding socket type. Also note that this requires support for VHOST to be Also note that this requires support for VHOST to be built-in both the guest and the host kernels, and the kernel modules to be loaded.
built-in both the guest and the host kernels, and the kernel modules to be loaded.
* [`systemd-sysusers(8)`](https://www.freedesktop.org/software/systemd/man/systemd-sysusers.html) * [`systemd-sysusers(8)`](https://www.freedesktop.org/software/systemd/man/systemd-sysusers.html)
will look for the credentials `passwd.hashed-password.<username>`, will look for the credentials `passwd.hashed-password.<username>`,
`passwd.plaintext-password.<username>` and `passwd.shell.<username>` to `passwd.plaintext-password.<username>` and `passwd.shell.<username>` to
configure the password (either in UNIX hashed form, or plaintext) or shell of configure the password (either in UNIX hashed form, or plaintext) or shell of
system users created. Replace `<username>` with the system user of your system users created.
choice, for example, `root`. 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) * [`systemd-firstboot(1)`](https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html)
will look for the credentials `firstboot.locale`, `firstboot.locale-messages`, will look for the credentials `firstboot.locale`, `firstboot.locale-messages`,
@ -489,17 +484,14 @@ credentials that must be decrypted/validated before use, such as those from
The `ImportCredential=` setting (and the `LoadCredential=` and The `ImportCredential=` setting (and the `LoadCredential=` and
`LoadCredentialEncrypted=` settings when configured with a relative source `LoadCredentialEncrypted=` settings when configured with a relative source
path) will search for the source file to read the credential from path) will search for the source file to read the credential from automatically.
automatically. Primarily, these credentials are searched among the credentials 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
passed into the system. If not found there, they are searched in `/etc/credstore.encrypted/` and similar directories.
`/etc/credstore/`, `/run/credstore/`, `ImportCredential=` will search both the non-encrypted and encrypted directories.
`/usr/lib/credstore/`. `LoadCredentialEncrypted=` will also search These directories are hence a great place to store credentials to load on the system.
`/etc/credstore.encrypted/` and similar directories. `ImportCredential=` will
search both the non-encrypted and encrypted directories. These directories are
hence a great place to store credentials to load on the system.
## Conditionalizing Services ## Conditionalizing Services
Sometimes it makes sense to conditionalize system services and invoke them only Sometimes it makes sense to conditionalize system services and invoke them only
if the right system credential is passed to the system. Use the if the right system credential is passed to the system.
`ConditionCredential=` and `AssertCredential=` unit file settings for that. Use the `ConditionCredential=` and `AssertCredential=` unit file settings for that.