| <?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='HAVE_GNU_EFI' |
| 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 <filename>systemd-boot</filename> or |
| <filename>systemd-stub</filename> components load the boot loader random seed off 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> |