Adding upstream version 255.4.upstream/255.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 101 insertions, 0 deletions

diff --git a/man/systemd-boot-random-seed.service.xml b/man/systemd-boot-random-seed.service.xml
new file mode 100644
index 0000000..87e2e27
--- /dev/null
+++ b/man/systemd-boot-random-seed.service.xml
@@ -0,0 +1,101 @@
+<?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-or-later -->
+
+<refentry id="systemd-boot-random-seed.service" conditional='ENABLE_BOOTLOADER'
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>systemd-boot-random-seed.service</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd-boot-random-seed.service</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd-boot-random-seed.service</refname>
+    <refpurpose>Refresh boot loader random seed at boot</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>systemd-boot-random-seed.service</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><filename>systemd-boot-random-seed.service</filename> is a system service that automatically
+    refreshes the boot loader random seed stored in the EFI System Partition (ESP), from the Linux kernel
+    entropy pool. The boot loader random seed is primarily consumed and updated by
+    <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> from the
+    UEFI environment (or
+    <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> if the
+    former is not used, but the latter is), and passed as initial RNG seed to the OS. It is an effective way
+    to ensure the OS comes up with a random pool that is fully initialized.</para>
+
+    <para>The service also automatically generates a 'system token' to store in an EFI variable in the
+    system's NVRAM. The boot loader may then combine the on-disk random seed and the system token by
+    cryptographic hashing, and pass it to the OS it boots as initialization seed for its entropy pool. Note:
+    the random seed stored in the ESP is refreshed on <emphasis>every</emphasis> reboot ensuring that
+    multiple subsequent boots will boot with different seeds. On the other hand, the system token is
+    generated randomly <emphasis>once</emphasis>, and then persistently stored in the system's EFI variable
+    storage, ensuring the same disk image won't result in the same series of boot loader seed values if used
+    on multiple systems in parallel.</para>
+
+    <para>The <filename>systemd-boot-random-seed.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 a boot
+    loader is used that implements the <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader
+    Interface</ulink>.</para> <para>For further details see
+    <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, regarding
+    the command this service invokes.</para>
+
+    <para>Note the relationship between <filename>systemd-boot-random-seed.service</filename> and
+    <citerefentry><refentrytitle>systemd-random-seed</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The
+    former maintains the random seed consumed and updated by the boot environment (i.e. by
+    <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> or
+    <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>), the
+    latter maintains a random seed consumed and updated by the OS itself. The former ensures that the OS has
+    a filled entropy pool already during earliest boot when regular disk access is not available yet
+    (i.e. when the OS random seed cannot be loaded yet). The latter is processed much later, once writable
+    disk access is available. Thus it cannot be used to seed the initial boot phase, but typically has much
+    higher quality of entropy. Both files are consumed and updated at boot, but at different
+    times. Specifically:</para>
+
+    <orderedlist>
+      <listitem><para>In UEFI mode, the
+      <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> or
+      <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+      components load the boot loader random seed from the ESP, hash it with available entropy and the system
+      token, and then update it on disk. A derived seed is passed to the kernel which writes it to its
+      entropy pool.</para></listitem>
+
+      <listitem><para>In userspace the <filename>systemd-random-seed.service</filename> service loads the OS
+      random seed, writes it to the kernel entropy pool, and then updates it on disk with a new value derived
+      from the kernel entropy pool.</para></listitem>
+
+      <listitem><para>In userspace the <filename>systemd-boot-random-seed.service</filename> service updates
+      the boot loader random seed with a new value derived from the kernel entropy pool.</para></listitem>
+    </orderedlist>
+
+    <para>This logic should ensure that the kernel's entropy pool is seeded during earliest bool already, if
+    possible, but the highest quality entropy is propagated back to both on-disk seeds.</para>
+  </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>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-random-seed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>