From 18d9cee002fdbce61cadc85ade57af7bca176509 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 11 Jun 2020 10:04:41 +0200 Subject: [PATCH] man: document systemd.random-seed= --- docs/RANDOM_SEEDS.md | 23 +++++++++++++++++++---- man/kernel-command-line.xml | 28 ++++++++++++++++++++++++++-- 2 files changed, 45 insertions(+), 6 deletions(-) diff --git a/docs/RANDOM_SEEDS.md b/docs/RANDOM_SEEDS.md index c1735b1ac9e..e4b4a7a9cb6 100644 --- a/docs/RANDOM_SEEDS.md +++ b/docs/RANDOM_SEEDS.md @@ -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?* diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index 52939deec0b..4e431aaefd6 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -468,8 +468,32 @@ systemd.clock-usec= Takes a decimal, numeric timestamp in µs since January 1st 1970, 00:00am, to set the - system clock to. The system time is set to the specified timestamp early during - boot. It is not propagated to the hardware clock (RTC). + system clock to. The system time is set to the specified timestamp early during boot. It is not + propagated to the hardware clock (RTC). + + + + systemd.random-seed= + + Takes a base64 encoded random seed value to credit with full entropy to the kernel's + random pool during early service manager initialization. This option is useful in testing + environments where delays due to random pool initialization in entropy starved virtual machines shall + be avoided. + + Note that if this option is used the seed is accessible to unprivileged programs from + /proc/cmdline. This option is hence a security risk when used outside of test + systems, since the (possibly) only seed used for initialization of the kernel's entropy pool might be + easily acquired by unprivileged programs. + + It is recommended to pass 512 bytes of randomized data (as that matches the Linux kernel pool + size), which may be generated with a command like the following: + + dd if=/dev/urandom bs=512 count=1 status=none | base64 -w 0 + + Again: do not use this option outside of testing environments, it's a security risk elsewhere, + as secret key material derived from the entropy pool can possibly be reconstructed by unprivileged + programs. + -- 2.39.2