From 39867bb9fbeb3c1a421404caa2aa2438bbfdd81b Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 22 Jul 2019 14:19:33 +0200 Subject: man: document the systemd-random-seed rework --- man/bootctl.xml | 22 +++++-- man/loader.conf.xml | 16 +++++ man/rules/meson.build | 1 + man/systemd-boot-system-token.service.xml | 76 ++++++++++++++++++++++ man/systemd-boot.xml | 102 ++++++++++++++++++++++++------ man/systemd-random-seed.service.xml | 57 ++++++++++++++--- 6 files changed, 243 insertions(+), 31 deletions(-) create mode 100644 man/systemd-boot-system-token.service.xml (limited to 'man') diff --git a/man/bootctl.xml b/man/bootctl.xml index 46b9738b14..28826d621c 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 38a80861b8..cef20b59d8 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 7e32e732c1..3b63311d7b 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 0000000000..b2948a5c4b --- /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 2575ab3fe5..3142b56d66 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 35c6e2fd0b..8714c4280d 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 -- cgit v1.2.3 From a2aa605d220b2b12eabd2974a947af603171b90c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 22 Jul 2019 15:05:29 +0200 Subject: bootctl: add is-installed verb Fixes: #9428 --- man/bootctl.xml | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'man') diff --git a/man/bootctl.xml b/man/bootctl.xml index 28826d621c..0c9fa80d09 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -137,6 +137,15 @@ systemd-boot-system-token.service8. + + + + Checks whether systemd-boot is installed in the ESP. Note that a + single ESP might host multiple boot loaders; this hence checks whether + systemd-boot is one (of possibly many) installed boot loaders — and neither + whether it is the default nor whether it is registered in any EFI variables. + + -- cgit v1.2.3 From 7fb0c615807cdcc2d509e4d719763f2b196c6e72 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 22 Jul 2019 15:24:49 +0200 Subject: man: extend on the --print-boot-path description a bit --- man/bootctl.xml | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) (limited to 'man') diff --git a/man/bootctl.xml b/man/bootctl.xml index 0c9fa80d09..070a31d09c 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -70,8 +70,17 @@ This option modifies the behaviour of status. Only prints the path to the Extended Boot Loader partition if it exists, and the path to the ESP otherwise to standard output and exit. This command is useful to determine where to place boot loader entries, as they are - preferably placed in the Extended Boot Loader partition if it exists and in the ESP otherwise. - + preferably placed in the Extended Boot Loader partition if it exists and in the ESP otherwise. + + Boot Loader Specification Type #1 entries should generally be placed in the directory + $(bootctl -x)/loader/entries/. Existence of that directory may also be used as + indication that boot loader entry support is available on the system. Similarly, Boot Loader + Specification Type #2 entries should be placed in the directory $(bootctl + -x)/EFI/Linux/. + + Note that this option (similar to the option mentioned + above), is available independently from the boot loader used, i.e. also without + systemd-boot being installed. -- cgit v1.2.3 From 93f5910078f9f6d34183ea4df8a842ad7b8a83e6 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 22 Jul 2019 18:13:26 +0200 Subject: docs: add longer document about systemd and random number seeds --- man/bootctl.xml | 5 ++++- man/loader.conf.xml | 5 ++++- man/systemd-boot.xml | 5 ++++- man/systemd-random-seed.service.xml | 3 +++ 4 files changed, 15 insertions(+), 3 deletions(-) (limited to 'man') diff --git a/man/bootctl.xml b/man/bootctl.xml index 070a31d09c..822d07a606 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -143,7 +143,10 @@ 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. + systemd-boot-system-token.service8. + + See Random Seeds for further + information. diff --git a/man/loader.conf.xml b/man/loader.conf.xml index cef20b59d8..14f84c13ee 100644 --- a/man/loader.conf.xml +++ b/man/loader.conf.xml @@ -167,7 +167,10 @@ 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. + variable. + + See Random Seeds for further + information. diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml index 3142b56d66..da8ddb5f84 100644 --- a/man/systemd-boot.xml +++ b/man/systemd-boot.xml @@ -401,7 +401,10 @@ "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. + boots. + + See Random Seeds for + further information. diff --git a/man/systemd-random-seed.service.xml b/man/systemd-random-seed.service.xml index 8714c4280d..28783a15e9 100644 --- a/man/systemd-random-seed.service.xml +++ b/man/systemd-random-seed.service.xml @@ -58,6 +58,9 @@ 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. + + See Random Seeds for further + information. -- cgit v1.2.3