From: Lennart Poettering Date: Mon, 22 Jul 2019 12:19:33 +0000 (+0200) Subject: man: document the systemd-random-seed rework X-Git-Tag: v243-rc1~32^2~5 X-Git-Url: http://git.ipfire.org/?p=thirdparty%2Fsystemd.git;a=commitdiff_plain;h=39867bb9fbeb3c1a421404caa2aa2438bbfdd81b man: document the systemd-random-seed rework --- diff --git a/man/bootctl.xml b/man/bootctl.xml index 46b9738b148..28826d621cf 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -45,15 +45,15 @@ Path to the EFI System Partition (ESP). If not specified, /efi/, - /boot/, and /boot/efi are checked in turn. It is recommended to mount - the ESP to /efi/, if possible. + /boot/, and /boot/efi/ are checked in turn. It is + recommended to mount the ESP to /efi/, if possible. Path to the Extended Boot Loader partition, as defined in the Boot Loader Specification. If not - specified, /boot/ are checked. It is recommended to mount the Extended Boot + specified, /boot/ is checked. It is recommended to mount the Extended Boot Loader partition to /boot/, if possible. @@ -124,6 +124,19 @@ and the firmware's boot loader list. + + + + Generates a random seed and stores it in the EFI System Partition, for use by the + systemd-boot boot loader. Also, generates a random 'system token' and stores it + persistently as an EFI variable, if one has not been set before. If the boot loader finds the random + seed in the ESP and the system token in the EFI variable it will derive a random seed to pass to the + OS and a new seed to store in the ESP from the combination of both. The random seed passed to the OS + is credited to the kernel's entropy pool by the system manager during early boot, and permits + userspace to boot up with an entropy pool fully initialized very early on. Also see + systemd-boot-system-token.service8. + + @@ -165,7 +178,8 @@ systemd-boot7, Boot Loader Specification, - Boot Loader Interface + Boot Loader Interface, + systemd-boot-system-token.service8 diff --git a/man/loader.conf.xml b/man/loader.conf.xml index 38a80861b8c..cef20b59d89 100644 --- a/man/loader.conf.xml +++ b/man/loader.conf.xml @@ -153,6 +153,22 @@ Takes a boolean argument. Enable (the default) or disable the "Reboot into firmware" entry. + + + random-seed-mode + + Takes one of off, with-system-token and + always. If off no random seed data is read off the ESP, nor + passed to the OS. If with-system-token (the default) + systemd-boot will read a random seed from the ESP (from the file + /loader/random-seed) only if the LoaderSystemToken EFI + variable is set, and then derive the random seed to pass to the OS from the combination. If + always the boot loader will do so even if LoaderSystemToken is + not set. This mode is useful in environments where protection against OS image reuse is not a + concern, and the random seed shall be used even with no further setup in place. User bootctl + random-seed to initialize both the random seed file in the ESP and the system token EFI + variable. + diff --git a/man/rules/meson.build b/man/rules/meson.build index 7e32e732c13..3b63311d7b5 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -655,6 +655,7 @@ manpages = [ ['systemd-bless-boot-generator', '8', [], 'ENABLE_EFI'], ['systemd-bless-boot.service', '8', [], 'ENABLE_EFI'], ['systemd-boot-check-no-failures.service', '8', [], ''], + ['systemd-boot-system-token.service', '8', [], 'ENABLE_EFI'], ['systemd-boot', '7', ['sd-boot'], 'ENABLE_EFI'], ['systemd-cat', '1', [], ''], ['systemd-cgls', '1', [], ''], diff --git a/man/systemd-boot-system-token.service.xml b/man/systemd-boot-system-token.service.xml new file mode 100644 index 00000000000..b2948a5c4b5 --- /dev/null +++ b/man/systemd-boot-system-token.service.xml @@ -0,0 +1,76 @@ + + + + + + + + systemd-boot-system-token.service + systemd + + + + systemd-boot-system-token.service + 8 + + + + systemd-boot-system-token.service + Generate an initial boot loader system token and random seed + + + + systemd-boot-system-token.service + + + + Description + + systemd-boot-system-token.service is a system service that automatically + generates a 'system token' to store in an EFI variable in the system's NVRAM and a random seed to store + on the EFI System Partition ESP on disk. The boot loader may then combine these two randomized data + fields by cryptographic hashing, and pass it to the OS it boots as initialization seed for its entropy + pool. The random seed stored in the ESP is refreshed on each reboot ensuring that multiple subsequent + boots will boot with different seeds. The 'system token' is generated randomly once, and then + persistently stored in the system's EFI variable storage. + + The systemd-boot-system-token.service unit invokes the bootctl + random-seed command, which updates the random seed in the ESP, and initializes the 'system + token' if it's not initialized yet. The service is conditionalized so that it is run only when all of the + below apply: + + + A boot loader is used that implements the Boot Loader Interface (which defines the 'system + token' concept). + + Either a 'system token' was not set yet, or the boot loader has not passed the OS a + random seed yet (and thus most likely has been missing the random seed file in the + ESP). + + The system is not running in a VM environment. This case is explicitly excluded since + on VM environments the ESP backing storage and EFI variable storage is typically not physically + separated and hence booting the same OS image in multiple instances would replicate both, thus reusing + the same random seed and 'system token' among all instances, which defeats its purpose. Note that it's + still possible to use boot loader random seed provisioning in this mode, but the automatic logic + implemented by this service has no effect then, and the user instead has to manually invoke the + bootctl random-seed acknowledging these restrictions. + + + For further details see + bootctl1, regarding + the command this service invokes. + + + + See Also + + systemd1, + bootctl1, + systemd-boot7 + + + + diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml index 2575ab3fe5e..3142b56d661 100644 --- a/man/systemd-boot.xml +++ b/man/systemd-boot.xml @@ -28,13 +28,14 @@ manager. It provides a graphical menu to select the entry to boot and an editor for the kernel command line. systemd-boot supports systems with UEFI firmware only. - systemd-boot loads boot entry information from the EFI system partition (ESP), usually mounted at - /efi/, /boot/, or /boot/efi/ during OS - runtime, as well as from the Extended Boot Loader partition if it exists (usually mounted to - /boot/). Configuration file fragments, kernels, initrds and other EFI images to boot - generally need to reside on the ESP or the Extended Boot Loader partition. Linux kernels must be built - with to be able to be directly executed as an EFI image. During boot - systemd-boot automatically assembles a list of boot entries from the following sources: + systemd-boot loads boot entry information from the EFI system partition (ESP), + usually mounted at /efi/, /boot/, or + /boot/efi/ during OS runtime, as well as from the Extended Boot Loader partition if + it exists (usually mounted to /boot/). Configuration file fragments, kernels, + initrds and other EFI images to boot generally need to reside on the ESP or the Extended Boot Loader + partition. Linux kernels must be built with to be able to be directly + executed as an EFI image. During boot systemd-boot automatically assembles a list of + boot entries from the following sources: Boot entries defined with A reboot into the UEFI firmware setup option, if supported by the firmware - kernel-install8 - may be used to copy kernel images onto the ESP or the Extended Boot Loader Partition and to generate - description files compliant with the Boot Loader - Specification. bootctl1 + systemd-boot supports the following features: + + + Basic boot manager configuration changes (such as timeout + configuration, default boot entry selection, …) may be made directly from the boot loader UI at + boot-time, as well as during system runtime with EFI variables. + + The boot manager integrates with the systemctl command to implement + features such as systemctl reboot --boot-loader-entry=… (for rebooting into a + specific boot menu entry, i.e. "reboot into Windows") and systemctl reboot + --boot-loader-menu=… (for rebooting into the boot loader menu), by implementing the Boot Loader Interface. See + systemctl1 for + details. + + An EFI variable set by the boot loader informs the OS about the ESP partition used + during boot. This is then used to automatically mount the correct ESP partition to + /efi/ or /boot/ during OS runtime. See + systemd-gpt-auto-generator8 + for details. + + The boot manager provides information about the boot time spent in UEFI firmware using + the Boot Loader Interface. This + information can be displayed using + systemd-analyze1. + + + The boot manager implements boot counting and automatic fallback to older, working boot + entries on failure. See Automatic Boot + Assessment. + + The boot manager optionally reads a random seed from the ESP partition, combines it + with a 'system token' stored in a persistant EFI variable and derives a random seed to use by the OS as + entropy pool initializaton, providing a full entropy pool during early boot. + + + bootctl1 may be used from a running system to locate the ESP and the Extended Boot Loader Partition, list available entries, and install systemd-boot itself. - systemd-boot will provide information about the time spent in UEFI firmware using the Boot Loader Interface. This information can be displayed - using systemd-analyze1. - + kernel-install8 + may be used to copy kernel images onto the ESP or the Extended Boot Loader Partition and to generate + description files compliant with the Boot Loader + Specification. @@ -238,7 +272,9 @@ Loader Specification are read from /loader/entries/ on the ESP and the Extended Boot Loader partition. Unified kernel boot entries following the Boot Loader Specification are read from - /EFI/Linux/ on the ESP and the Extended Boot Loader partition. + /EFI/Linux/ on the ESP and the Extended Boot Loader partition. Optionally, a random + seed for early boot entropy pool provisioning is stored in /loader/random-seed in + the ESP. @@ -346,10 +382,39 @@ Information about the time spent in various parts of the boot loader. Set by the boot loader. Use systemd-analyze1 - to view this data. These variables are defined by the Boot Loader Interface. + to view this data. + + + + LoaderRandomSeed + + A binary random seed systemd-boot may optionally pass to the + OS. This is a volatile EFI variable that is hashed at boot from the combination of a random seed + stored in the ESP (in /loader/random-seed) and a "system token" persistently + stored in the EFI variable LoaderSystemToken (see below). During early OS boot the + system manager reads this variable and passes it to the OS kernel's random pool, crediting the full + entropy it contains. This is an efficient way to ensure the system starts up with a fully initialized + kernel random pool — as early as the initial RAM disk phase. systemd-boot reads + the random seed from the ESP, combines it with the "system token", and both derives a new random seed + to update in-place the seed stored in the ESP, and the random seed to pass to the OS from it via + SHA256 hashing in counter mode. This ensures that different physical systems that boot the same + "golden" OS image — i.e. containing the same random seed file in the ESP — will still pass a + different random seed to the OS. It is made sure the random seed stored in the ESP is fully + overwritten before the OS is booted, to ensure different random seed data is used between subsequent + boots. + + + + LoaderSystemToken + + A binary random data field, that is used for generating the random see to pass to the + OS (see above). Note that this random data is generally only generated once, during OS installation, + and is then never updated again. + + Many of these variables are defined by the Boot Loader Interface. @@ -413,6 +478,7 @@ bootctl1, loader.conf5, systemd-bless-boot.service8, + systemd-boot-system-token.service8, kernel-install8, Boot Loader Specification, Boot Loader Interface diff --git a/man/systemd-random-seed.service.xml b/man/systemd-random-seed.service.xml index 35c6e2fd0b7..8714c4280d2 100644 --- a/man/systemd-random-seed.service.xml +++ b/man/systemd-random-seed.service.xml @@ -29,21 +29,60 @@ Description - systemd-random-seed.service is a - service that restores the random seed of the system at early boot - and saves it at shutdown. See - random4 - for details. Saving/restoring the random seed across boots - increases the amount of available entropy early at boot. On disk - the random seed is stored in - /var/lib/systemd/random-seed. + systemd-random-seed.service is a service that loads an on-disk random seed + into the kernel entropy pool during boot and saves it at shutdown. See + random4 for + details. By default, no entropy is credited when the random seed is written into the kernel entropy pool, + but this may be changed with $SYSTEMD_RANDOM_SEED_CREDIT, see below. On disk the random + seed is stored in /var/lib/systemd/random-seed. + + Note that this service runs relatively late during the early boot phase, i.e. generally after the + initial RAM disk (initrd) completed its work, and the /var/ file system has been + mounted writable. Many system services require entropy much earlier than this — this service is hence of + limited use for complex system. It is recommended to use a boot loader that can pass an initial random + seed to the kernel to ensure that entropy is available from earliest boot on, for example + systemd-boot7, with + its bootctl random-seed functionality. + + When loading the random seed from disk its file is immediately updated with a new seed retrieved + from the kernel, in order to ensure no two boots operate with the same random seed. This new seed is + retrieved synchronously from the kernel, which means the service will not complete start-up until the + random pool is fully initialized. On entropy-starved systems this may take a while. This functionality is + intended to be used as synchronization point for ordering services that require an initialized entropy + pool to function securely (i.e. services that access /dev/urandom without any + further precautions). + + Care should be taken when creating OS images that are replicated to multiple systems: if the random + seed file is included unmodified each system will initialize its entropy pool with the same data, and + thus — if otherwise entropy-starved — generate the same or at least guessable random seed streams. As a + safety precaution crediting entropy is thus disabled by default. It is recommended to remove the random + seed from OS images intended for replication on multiple systems, in which case it is safe to enable + entropy crediting, see below. + + + + Environment + + + + $SYSTEMD_RANDOM_SEED_CREDIT + By default, systemd-random-seed.service does not credit any + entropy when loading the random seed. With this option this behaviour may be changed: it either takes + a boolean parameter or the special string force. Defaults to false, in which case + no entropy is credited. If true, entropy is credited if the random seed file and system state pass + various superficial concisistency checks. If set to force entropy is credited, + regardless of these checks, as long as the random seed file exists. + + See Also systemd1, - random4 + random4, + systemd-boot7, + bootctl4