man: document systemd.random-seed=

[thirdparty/systemd.git] / docs / RANDOM_SEEDS.md

diff --git a/docs/RANDOM_SEEDS.md b/docs/RANDOM_SEEDS.md
index d3b68e967aa09d85c42633eca23cf8770610f10e..e4b4a7a9cb6e1ec5cd9b375b5dd1d01105cf11a7 100644 (file)
--- a/docs/RANDOM_SEEDS.md
+++ b/docs/RANDOM_SEEDS.md
@@ -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
@@ -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?*