]>
Commit | Line | Data |
---|---|---|
921fc451 LP |
1 | <?xml version='1.0'?> <!--*-nxml-*--> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
921fc451 LP |
4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
5 | ||
dfca5587 | 6 | <refentry id="systemd-boot-random-seed.service" conditional='ENABLE_BOOTLOADER' |
921fc451 LP |
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 | |
d09df6b9 | 35 | UEFI environment (or |
921fc451 LP |
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> | |
8fb35004 ZJS |
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> | |
921fc451 LP |
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 | |
30fd9a2d | 82 | the boot loader random seed with a new value derived from the kernel entropy pool.</para></listitem> |
921fc451 LP |
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> | |
13a69c12 DT |
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> | |
921fc451 LP |
99 | </refsect1> |
100 | ||
101 | </refentry> |