]> git.ipfire.org Git - thirdparty/systemd.git/blobdiff - docs/RANDOM_SEEDS.md
Merge pull request #16697 from yuwata/network-fix-suspend-issue
[thirdparty/systemd.git] / docs / RANDOM_SEEDS.md
index d3b68e967aa09d85c42633eca23cf8770610f10e..da3fe40baad1418683e64cab1c245d087738e31b 100644 (file)
@@ -118,7 +118,7 @@ requires random numbers as well, including for the following uses:
 
 * systemd maintains various hash tables internally. In order to harden them
   against [collision
-  attacks](https://rt.perl.org/Public/Bug/Display.html?CSRF_Token=165691af9ddaa95f653402f1b68de728)
+  attacks](https://www.cs.auckland.ac.nz/~mcw/Teaching/refs/misc/denial-of-service.pdf)
   they are seeded with random numbers.
 
 * At various places systemd needs random bytes for temporary file name
@@ -212,10 +212,10 @@ boot, in order to ensure the entropy pool is filled up quickly.
    random-seed`](https://www.freedesktop.org/software/systemd/man/bootctl.html#random-seed))
    a seed file with an initial seed is placed in a file `/loader/random-seed`
    in the ESP. In addition, an identically sized randomized EFI variable called
-   the the 'system token' is set, which is written to the machine's firmware
-   NVRAM. During boot, when `systemd-boot` finds both the random seed file and
-   the system token they are combined and hashed with SHA256 (in counter mode,
-   to generate sufficient data), to generate a new random seed file to store in
+   the 'system token' is set, which is written to the machine's firmware NVRAM.
+   During boot, when `systemd-boot` finds both the random seed file and the
+   system token they are combined and hashed with SHA256 (in counter mode, to
+   generate sufficient data), to generate a new random seed file to store in
    the ESP as well as a random seed to pass to the OS kernel. The new random
    seed file for the ESP is then written to the ESP, ensuring this is completed
    before the OS is invoked. Very early during initialization PID 1 will read
@@ -257,7 +257,16 @@ boot, in order to ensure the entropy pool is filled up quickly.
    file. If done, `systemd-boot` will use the random seed file even if no
    system token is found in EFI variables.
 
-With the three mechanisms described above it should be possible to provide
+4. A kernel command line option `systemd.random_seed=` may be used to pass in a
+   base64 encoded seed to initialize the kernel's entropy pool from during
+   early service manager initialization. This option is only safe in testing
+   environments, as the random seed passed this way is accessible to
+   unprivileged programs via `/proc/cmdline`. Using this option outside of
+   testing environments is a security problem since cryptographic key material
+   derived from the entropy pool initialized with a seed accessible to
+   unprivileged programs should not be considered secret.
+
+With the four mechanisms described above it should be possible to provide
 early-boot entropy in most cases. Specifically:
 
 1. On EFI systems, `systemd-boot`'s random seed logic should make sure good
@@ -267,7 +276,8 @@ early-boot entropy in most cases. Specifically:
 2. On virtualized systems, the early `virtio-rng` hookup should ensure entropy
    is available early on — as long as the VM environment provides virtualized
    RNG devices, which they really should all do in 2019. Complain to your
-   hosting provider if they don't.
+   hosting provider if they don't. For VMs used in testing environments,
+   `systemd.random_seed=` may be used as an alternative to a virtualized RNG.
 
 3. On Intel/AMD systems systemd's own reliance on the kernel entropy pool is
    minimal (as RDRAND is used on those for UUID generation). This only works if
@@ -286,8 +296,9 @@ This primarily leaves two kind of systems in the cold:
    boot. Alternatively, consider implementing a solution similar to
    systemd-boot's random seed concept in your platform's boot loader.
 
-2. Virtualized environments that lack both virtio-rng and RDRAND. Tough
-   luck. Talk to your hosting provider, and ask them to fix this.
+2. Virtualized environments that lack both virtio-rng and RDRAND, outside of
+   test environments. Tough luck. Talk to your hosting provider, and ask them
+   to fix this.
 
 3. Also note: if you deploy an image without any random seed and/or without
    installing any 'system token' in an EFI variable, as described above, this
@@ -410,6 +421,10 @@ This primarily leaves two kind of systems in the cold:
     information to possibly gain too much information about the current state
     of the kernel's entropy pool.
 
+    That said, we actually do implement this with the `systemd.random_seed=`
+    kernel command line option. Don't use this outside of testing environments,
+    however, for the aforementioned reasons.
+
 12. *Why doesn't `systemd-boot` rewrite the 'system token' too each time
     when updating the random seed file stored in the ESP?*