man: document the systemd-random-seed rework

6 files changed, 243 insertions, 31 deletions

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 @@
       <varlistentry>
         <term><option>--esp-path=</option></term>
         <listitem><para>Path to the EFI System Partition (ESP). If not specified, <filename>/efi/</filename>,
-        <filename>/boot/</filename>, and <filename>/boot/efi</filename> are checked in turn.  It is recommended to mount
-        the ESP to <filename>/efi/</filename>, if possible.</para></listitem>
+        <filename>/boot/</filename>, and <filename>/boot/efi/</filename> are checked in turn.  It is
+        recommended to mount the ESP to <filename>/efi/</filename>, if possible.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><option>--boot-path=</option></term>
         <listitem><para>Path to the Extended Boot Loader partition, as defined in the <ulink
         url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>. If not
-        specified, <filename>/boot/</filename> are checked.  It is recommended to mount the Extended Boot
+        specified, <filename>/boot/</filename> is checked.  It is recommended to mount the Extended Boot
         Loader partition to <filename>/boot/</filename>, if possible.</para></listitem>
       </varlistentry>
 
@@ -125,6 +125,19 @@
       </varlistentry>
 
       <varlistentry>
+        <term><option>random-seed</option></term>
+
+        <listitem><para>Generates a random seed and stores it in the EFI System Partition, for use by the
+        <command>systemd-boot</command> 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
+        <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><option>list</option></term>
 
         <listitem><para>Shows all available boot loader entries implementing the <ulink
@@ -165,7 +178,8 @@
     <para>
       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
       <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>,
-      <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>
+      <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>,
+      <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     </para>
   </refsect1>
 </refentry>
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 @@
         <listitem><para>Takes a boolean argument. Enable (the default) or disable
         the "Reboot into firmware" entry.</para></listitem>
       </varlistentry>
+
+      <varlistentry>
+        <term>random-seed-mode</term>
+
+        <listitem><para>Takes one of <literal>off</literal>, <literal>with-system-token</literal> and
+        <literal>always</literal>. If <literal>off</literal> no random seed data is read off the ESP, nor
+        passed to the OS. If <literal>with-system-token</literal> (the default)
+        <command>systemd-boot</command> will read a random seed from the ESP (from the file
+        <filename>/loader/random-seed</filename>) only if the <varname>LoaderSystemToken</varname> EFI
+        variable is set, and then derive the random seed to pass to the OS from the combination. If
+        <literal>always</literal> the boot loader will do so even if <varname>LoaderSystemToken</varname> 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 <command>bootctl
+        random-seed</command> to initialize both the random seed file in the ESP and the system token EFI
+        variable.</para></listitem>
+      </varlistentry>
     </variablelist>
   </refsect1>
 
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 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="systemd-boot-system-token.service" conditional='ENABLE_EFI'
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>systemd-boot-system-token.service</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd-boot-system-token.service</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd-boot-system-token.service</refname>
+    <refpurpose>Generate an initial boot loader system token and random seed</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>systemd-boot-system-token.service</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><filename>systemd-boot-system-token.service</filename> 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.</para>
+
+    <para>The <filename>systemd-boot-system-token.service</filename> unit invokes the <command>bootctl
+    random-seed</command> 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:</para>
+
+    <itemizedlist>
+      <listitem><para>A boot loader is used that implements the <ulink
+      url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink> (which defines the 'system
+      token' concept).</para></listitem>
+
+      <listitem><para>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).</para></listitem>
+
+      <listitem><para>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
+      <command>bootctl random-seed</command> acknowledging these restrictions.</para></listitem>
+    </itemizedlist>
+
+    <para>For further details see
+    <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, regarding
+    the command this service invokes.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
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. <command>systemd-boot</command> supports systems with UEFI firmware only.</para>
 
-    <para>systemd-boot loads boot entry information from the EFI system partition (ESP), usually mounted at
-    <filename>/efi/</filename>, <filename>/boot/</filename>, or <filename>/boot/efi/</filename> during OS
-    runtime, as well as from the Extended Boot Loader partition if it exists (usually mounted to
-    <filename>/boot/</filename>). 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 <option>CONFIG_EFI_STUB</option> 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:</para>
+    <para><command>systemd-boot</command> loads boot entry information from the EFI system partition (ESP),
+    usually mounted at <filename>/efi/</filename>, <filename>/boot/</filename>, or
+    <filename>/boot/efi/</filename> during OS runtime, as well as from the Extended Boot Loader partition if
+    it exists (usually mounted to <filename>/boot/</filename>). 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 <option>CONFIG_EFI_STUB</option> to be able to be directly
+    executed as an EFI image. During boot <command>systemd-boot</command> automatically assembles a list of
+    boot entries from the following sources:</para>
 
     <itemizedlist>
       <listitem><para>Boot entries defined with <ulink
@@ -57,17 +58,50 @@
       <listitem><para>A reboot into the UEFI firmware setup option, if supported by the firmware</para></listitem>
     </itemizedlist>
 
-    <para><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    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. <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    <para><command>systemd-boot</command> supports the following features:</para>
+
+    <itemizedlist>
+      <listitem><para>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.</para></listitem>
+
+      <listitem><para>The boot manager integrates with the <command>systemctl</command> command to implement
+      features such as <command>systemctl reboot --boot-loader-entry=…</command> (for rebooting into a
+      specific boot menu entry, i.e. "reboot into Windows") and <command>systemctl reboot
+      --boot-loader-menu=…</command> (for rebooting into the boot loader menu), by implementing the <ulink
+      url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>. See
+      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
+      details.</para></listitem>
+
+      <listitem><para>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
+      <filename>/efi/</filename> or <filename>/boot/</filename> during OS runtime. See
+      <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      for details.</para></listitem>
+
+      <listitem><para>The boot manager provides information about the boot time spent in UEFI firmware using
+      the <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>. This
+      information can be displayed using
+      <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+      </para></listitem>
+
+      <listitem><para>The boot manager implements boot counting and automatic fallback to older, working boot
+      entries on failure. See <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot
+      Assessment</ulink>.</para></listitem>
+
+      <listitem><para>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.</para></listitem>
+    </itemizedlist>
+
+    <para><citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     may be used from a running system to locate the ESP and the Extended Boot Loader Partition, list
     available entries, and install <command>systemd-boot</command> itself.</para>
 
-    <para>systemd-boot will provide information about the time spent in UEFI firmware using the <ulink
-    url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>. This information can be displayed
-    using <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
-    </para>
+    <para><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    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.</para>
   </refsect1>
 
   <refsect1>
@@ -238,7 +272,9 @@
     Loader Specification</ulink> are read from <filename>/loader/entries/</filename> on the ESP and the
     Extended Boot Loader partition. Unified kernel boot entries following the <ulink
     url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> are read from
-    <filename>/EFI/Linux/</filename> on the ESP and the Extended Boot Loader partition.</para>
+    <filename>/EFI/Linux/</filename> on the ESP and the Extended Boot Loader partition. Optionally, a random
+    seed for early boot entropy pool provisioning is stored in <filename>/loader/random-seed</filename> in
+    the ESP.</para>
   </refsect1>
 
   <refsect1>
@@ -346,10 +382,39 @@
 
         <listitem><para>Information about the time spent in various parts of the boot loader. Set by the boot
         loader. Use <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-        to view this data. These variables are defined by the <ulink
-        url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.</para></listitem>
+        to view this data. </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>LoaderRandomSeed</varname></term>
+
+        <listitem><para>A binary random seed <command>systemd-boot</command> 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 <filename>/loader/random-seed</filename>) and a "system token" persistently
+        stored in the EFI variable <varname>LoaderSystemToken</varname> (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. <command>systemd-boot</command> 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.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>LoaderSystemToken</varname></term>
+
+        <listitem><para>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.</para></listitem>
       </varlistentry>
     </variablelist>
+
+    <para>Many of these variables are defined by the <ulink
+    url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.</para>
   </refsect1>
 
   <refsect1>
@@ -413,6 +478,7 @@
       <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>,
       <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>
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 @@
   <refsect1>
     <title>Description</title>
 
-    <para><filename>systemd-random-seed.service</filename> is a
-    service that restores the random seed of the system at early boot
-    and saves it at shutdown. See
-    <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>
-    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
-    <filename>/var/lib/systemd/random-seed</filename>.</para>
+    <para><filename>systemd-random-seed.service</filename> is a service that loads an on-disk random seed
+    into the kernel entropy pool during boot and saves it at shutdown. See
+    <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> 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 <varname>$SYSTEMD_RANDOM_SEED_CREDIT</varname>, see below.  On disk the random
+    seed is stored in <filename>/var/lib/systemd/random-seed</filename>.</para>
+
+    <para>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 <filename>/var/</filename> 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
+    <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, with
+    its <command>bootctl random-seed</command> functionality.</para>
+
+    <para>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 <filename>/dev/urandom</filename> without any
+    further precautions).</para>
+
+    <para>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.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Environment</title>
+
+    <variablelist class='environment-variables'>
+      <varlistentry>
+        <term><varname>$SYSTEMD_RANDOM_SEED_CREDIT</varname></term>
+        <listitem><para>By default, <filename>systemd-random-seed.service</filename> 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 <literal>force</literal>. 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 <literal>force</literal> entropy is credited,
+        regardless of these checks, as long as the random seed file exists.</para></listitem>
+      </varlistentry>
+    </variablelist>
   </refsect1>
 
   <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>4</manvolnum></citerefentry>
     </para>
   </refsect1>