man/systemd-boot-random-seed.service.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-boot-random-seed.service" conditional='ENABLE_BOOTLOADER'
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-boot-random-seed.service</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-boot-random-seed.service</refentrytitle>
  16     <manvolnum>8</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-boot-random-seed.service</refname>
  21     <refpurpose>Refresh boot loader random seed at boot</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <para><filename>systemd-boot-random-seed.service</filename></para>
  26   </refsynopsisdiv>
  27
  28   <refsect1>
  29     <title>Description</title>
  30
  31     <para><filename>systemd-boot-random-seed.service</filename> is a system service that automatically
  32     refreshes the boot loader random seed stored in the EFI System Partition (ESP), from the Linux kernel
  33     entropy pool. The boot loader random seed is primarily consumed and updated by
  34     <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> from the
  35     UEFI environment (or
  36     <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> if the
  37     former is not used, but the latter is), and passed as initial RNG seed to the OS. It is an effective way
  38     to ensure the OS comes up with a random pool that is fully initialized.</para>
  39
  40     <para>The service also automatically generates a 'system token' to store in an EFI variable in the
  41     system's NVRAM. The boot loader may then combine the on-disk random seed and the system token by
  42     cryptographic hashing, and pass it to the OS it boots as initialization seed for its entropy pool. Note:
  43     the random seed stored in the ESP is refreshed on <emphasis>every</emphasis> reboot ensuring that
  44     multiple subsequent boots will boot with different seeds. On the other hand, the system token is
  45     generated randomly <emphasis>once</emphasis>, and then persistently stored in the system's EFI variable
  46     storage, ensuring the same disk image won't result in the same series of boot loader seed values if used
  47     on multiple systems in parallel.</para>
  48
  49     <para>The <filename>systemd-boot-random-seed.service</filename> unit invokes the <command>bootctl
  50     random-seed</command> command, which updates the random seed in the ESP, and initializes the system
  51     token if it's not initialized yet. The service is conditionalized so that it is run only when a boot
  52     loader is used that implements the <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader
  53     Interface</ulink>.</para> <para>For further details see
  54     <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, regarding
  55     the command this service invokes.</para>
  56
  57     <para>Note the relationship between <filename>systemd-boot-random-seed.service</filename> and
  58     <citerefentry><refentrytitle>systemd-random-seed</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The
  59     former maintains the random seed consumed and updated by the boot environment (i.e. by
  60     <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> or
  61     <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>), the
  62     latter maintains a random seed consumed and updated by the OS itself. The former ensures that the OS has
  63     a filled entropy pool already during earliest boot when regular disk access is not available yet
  64     (i.e. when the OS random seed cannot be loaded yet). The latter is processed much later, once writable
  65     disk access is available. Thus it cannot be used to seed the initial boot phase, but typically has much
  66     higher quality of entropy. Both files are consumed and updated at boot, but at different
  67     times. Specifically:</para>
  68
  69     <orderedlist>
  70       <listitem><para>In UEFI mode, the
  71       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> or
  72       <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  73       components load the boot loader random seed from the ESP, hash it with available entropy and the system
  74       token, and then update it on disk. A derived seed is passed to the kernel which writes it to its
  75       entropy pool.</para></listitem>
  76
  77       <listitem><para>In userspace the <filename>systemd-random-seed.service</filename> service loads the OS
  78       random seed, writes it to the kernel entropy pool, and then updates it on disk with a new value derived
  79       from the kernel entropy pool.</para></listitem>
  80
  81       <listitem><para>In userspace the <filename>systemd-boot-random-seed.service</filename> service updates
  82       the boot loader random seed with a new value derived from the kernel entropy pool.</para></listitem>
  83     </orderedlist>
  84
  85     <para>This logic should ensure that the kernel's entropy pool is seeded during earliest bool already, if
  86     possible, but the highest quality entropy is propagated back to both on-disk seeds.</para>
  87   </refsect1>
  88
  89   <refsect1>
  90     <title>See Also</title>
  91     <para><simplelist type="inline">
  92       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
  93       <member><citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry></member>
  94       <member><citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
  95       <member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
  96       <member><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
  97       <member><citerefentry><refentrytitle>systemd-random-seed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
  98     </simplelist></para>
  99   </refsect1>
 100
 101 </refentry>