haveged(8)

📦
version 1.9.27 · 3 versions
, in arch rolling, epel 10, epel 9, fedora 43, nixpkgs unstable, ubuntu stonking

🦋 haveged(8) — SYSTEM ADMINISTRATION COMMANDS 🦋

okay bestie, pull up a chair, we're talking about haveged, the little daemon that makes entropy happen. ✨

✨ NAME ✨

haveged — bestie, it generates random numbers and feeds them straight into Linux's random device. no cap. 🎲💖

🌸 SYNOPSIS 🌸

haveged [options]

💅 DESCRIPTION 💅

haveged generates an unpredictable stream of random numbers, and it harvests them from the indirect effects of hardware events on hidden processor state — think caches, branch predictors, memory translation tables, all that spicy internal stuff 👀 — using the HAVEGE (HArdware Volatile Entropy Gathering and Expansion) algorithm. The whole thing operates in user space, so literally no special privilege is required for file system access to the output stream. iconic behavior. 👑

Linux pools randomness for distribution via the /dev/random and /dev/urandom device interfaces. The thing is, the standard mechanisms of filling the /dev/random pool may not be sufficient to meet demand on systems with high needs or limited user interaction. 😭 In those circumstances, haveged can be run as a privileged daemon to fill the /dev/random pool whenever the supply of random bits in /dev/random falls below the low water mark of the device. it's giving "helper to the rescue". 🫶

haveged tunes itself to its environment, and it provides the same built-in test suite for the output stream as the one used on certified hardware security devices. See NOTES below for more info. 👇

🔥 OPTIONS 🔥

  • -b nnn, --buffer=nnn — Sets the collection buffer size to nnn KW. Default is 128KW (which is also 512KB).
  • -c cmd, --command=cmd — Switch to command mode and send a command to an already running haveged process or daemon. Currently the only known commands are close, which closes the current communication socket of the running haveged process, and root=<new_root>, where <new_root> is a placeholder for the path of the real new root directory — and that directory should provide a haveged installation. The haveged process or daemon will perform a chroot(2) system call followed by a execv(3) to become rebased within the new root directory. 🌀
  • -C, --no-command — Disable command mode. The daemon will not open a command socket or create a semaphore. This reduces attack surface when command mode isn't needed (like, say, for the long-running system service 🛡️). Command mode is still available for sending commands to a running instance via -c.
  • -d nnn, --data=nnn — Set the data cache size to nnn KB. Default is 16 or as determined dynamically.
  • -f file, --file=file — Set the output file path for non-daemon use. Default is "sample", and use "-" for stdout. 📝
  • -F, --Foreground — Run the daemon in foreground. Do not fork and detach. (yes, capital F, she's quirky like that 💁)
  • -e, --once — Provide entropy to the kernel once and quit immediately. one and done, periodt. 🏃‍♀️
  • -i nnn, --inst=nnn — Set the instruction cache size to nnn KB. Default is 16 or as determined dynamically.
  • -n nnn, --number=nnn — Set the number of bytes written to the output file. The value may be specified using one of the suffixes k, m, g, or t. The upper bound of this value is "16t" (2^44 Bytes = 16TB). A value of 0 indicates unbounded output and forces output to stdout. This argument is required if the daemon interface is not present. If the daemon interface is present, this setting takes precedence over any --run value.
  • -o <spec>, --onlinetest=<spec> — Specify which online tests to run. The <spec> consists of optional "t"ot and "c"ontinuous groups, and each group indicates the procedures to be run — using "a<n>" to indicate an AIS-31 procedure A variant, and "b" to indicate AIS procedure B. The specifications are order independent (procedure B always runs first in each group) and case insensitive. The a<n> variations exist to mitigate the slow autocorrelation test (test5). Normally all procedure A tests, except the first, are iterated 257 times. An a<n> option indicates that test5 should only be executed every modulo <n> times during the procedure's 257 repetitions. The effect is so noticeable that A8 is the usual choice. 👀

The "tot" tests run only at initialization — there are no negative performance consequences, except for a slight increase in the time required to initialize. The "tot" tests guarantee that haveged initialized properly. Using both test procedures in the "tot" test is highly recommended, because the two tests emphasize different aspects of RNG quality. 🎯

In continuous testing, the test sequence is cycled repeatedly. For example, the string "tbca8b" (suitable for an AIS NTG.1 device) would run procedure B for the "tot" test, then cycle between procedure A8 and procedure B continuously for all further output. Continuous testing does not come for free — it impacts both throughput and resource consumption. Continual testing also opens up the possibility of a test failure. A strict retry procedure recovers from spurious failure in all but the most extreme circumstances. When the retry fails, operation will terminate, unless a "w" has been appended to the test token to make the test advisory only. In our example above, the string "tbca8wbw" would make all continuous tests advisory. For more detailed info on AIS retries, see NOTES below. 📚

Complete control over the test configuration is provided for flexibility. The defaults (ta8bcb if run as a daemon and ta8b otherwise) are suitable for most circumstances.

  • -p file, --pidfile=file — Set the file path for the daemon pid file. Default is "/var/run/haveged.pid", (yes there's a trailing comma in the original and we respect her 🫡)
  • -r n, --run=n — Set run level for the daemon interface:
    • n = 0 — Run as daemon — must be root. Fills /dev/random when the supply of random bits falls below the low water mark of the device.
    • n = 1 — Display configuration info and terminate.
    • n > 1 — Write <n> kb of output. Deprecated (use --number instead), only provided for backward compatibility. 🫠

Fyi bestie: if --number is specified, values other than 0,1 are ignored. Default is 0.

  • -v n, --verbose=n — Set the diagnostic bitmap as the sum of the following options:
    • 1 = Show build/tuning summary on termination, plus summary for online test retries.
    • 2 = Show online test retry details.
    • 4 = Show timing for collections.
    • 8 = Show collection loop layout.
    • 16 = Show collection loop code offsets.
    • 32 = Show all online test completion detail.
    • 64 = Show info on RNDADDENTROPY operation.

Default is 0. Use -1 for all diagnostics. 🗣️

  • -w nnn, --write=nnn — Set the write_wakeup_threshold of the daemon interface to nnn bits. Applies only to run level 0.
  • -V, --version — Print version information and exit. 🏷️
  • -?, --help — This summary of program options. hi, you are here. 👋

🧚 NOTES 🧚

haveged tunes the HAVEGE algorithm for maximum effectiveness using a hierarchy of defaults, command line options, virtual file system information, and cpuid information where available. Under most circumstances, user input is not required for excellent results. she's self-sufficient like that. 💅

Run-time testing provides assurance of correct haveged operation. The run-time test suite is modeled upon the AIS-31 specification of the German Common Criteria body, BIS. This specification is typically applied to hardware devices, requiring formal certification and mandated start-up and continuous operational testing. Because haveged runs on many different hardware platforms, certification cannot be a goal — but the AIS-31 test suite provides the means to assess haveged output with the same operational tests applied to certified hardware devices. it's giving "we can't be certified but we CAN be tested". ✅

AIS test procedure A performs 6 tests to check for statistically inconspicuous behavior. AIS test procedure B performs more theoretical tests such as checking multi-step transition probabilities and making an empirical entropy estimate. Procedure A is the much more resource and compute intensive of the two, but it is still recommended for the haveged start-up tests. Procedure B is well suited to the use of haveged as a daemon, because the test entropy estimate confirms the entropy estimate haveged uses when adding entropy to the /dev/random device.

no test is perfect, bestie. 😭 There is a 10e-4 probability that a perfect generator will fail either of the test procedures. AIS-31 mandates a strict retry policy to filter out false alarms, and haveged always logs test procedure failures. Retries are expected but rarely observed, except when large data sets are generated with continuous testing. See the libhavege(3) notes for more detailed information.

🎀 FILES 🎀

If running as a daemon, access to the following files is required:

  • /dev/random
  • /proc/sys/kernel/osrelease
  • /proc/sys/kernel/random/poolsize
  • /proc/sys/kernel/random/write_wakeup_threshold

💀 DIAGNOSTICS 💀

haveged returns 0 for success and non-zero for failure. The failure return code is 1 "general failure", unless execution is terminated by signal <n> — in which case the return code will be 128 + <n>. The following diagnostics are issued to stderr upon non-zero termination:

  • Cannot fork into the background — Call to daemon(3) failed.
  • Cannot open file <s> for writing. — Could not open sample file <s> for writing.
  • Cannot write data in file: — Could not write data to the sample file.
  • Couldn't get pool size. — Unable to read /proc/sys/kernel/random/poolsize
  • Couldn't initialize HAVEGE rng — Invalid data or instruction cache size.
  • Couldn't open PID file <s> for writing — Unable to write daemon PID
  • Couldn't open random device — Could not open /dev/random for read-write.
  • Couldn't query entropy-level from kernel: error — Call to ioctl(2) failed.
  • Couldn't open PID file <path> for writing — Error writing /var/run/haveged.pid
  • Fail:set_watermark() — Unable to write to /proc/sys/kernel/random/write_wakeup_threshold
  • RNDADDENTROPY failed! — Call to ioctl(2) to add entropy failed
  • RNG failed — The random number generator failed self-test or encountered a fatal error.
  • Select error — Call to select(2) failed.
  • Stopping due to signal <n> — Signal <n> caught.
  • Unable to setup online tests — Memory unavailable for online test resources.

🎀 EXAMPLES 🎀

okay bestie this is the part where it gets fun — actual things you can type, all of them copy-pasteable, all of them extremely slay. let's go 💅

  • Write 1.5MB of random data to the file /tmp/random
haveged -n 1.5M -f /tmp/random
  • Generate a /tmp/keyfile for disk encryption with LUKS
haveged -n 2048 -f /tmp/keyfile
  • Overwrite partition /dev/sda1 with random data. Be careful, all data on the partition will be lost!
🚨 bestie STOP. read that again. all data on the partition will be lost. like, gone gone. this is not a drill, this is the whole point, and also the whole danger. 👑🔥
haveged -n 0 | dd of=/dev/sda1
  • Generate random ASCII passwords of the length 16 characters
(haveged -n 1000 -f - 2>/dev/null | tr -cd '[:graph:]' | fold -w
16 && echo ) | head
  • Write endless stream of random bytes to the pipe. Utility pv measures the speed by which data are written to the pipe.
haveged -n 0 | pv > /dev/null
  • Evaluate speed of haveged to generate 1GB of random data
haveged -n 1g -f - | dd of=/dev/null
  • Create a random key file containing 65 random keys for the encryption program aespipe.
haveged -n 3705 -f - 2>/dev/null | uuencode -m - | head -n 66 |
tail -n 65
  • Test the randomness of the generated data with dieharder test suite
haveged -n 0 | dieharder -g 200 -a
  • Test the randomness of the generated data with PractRand test suite
haveged -n 0 | practrand-RNG_test stdin64 -tlmax 16G
-multithreaded
  • Generate 16k of data, testing with procedure A and B with detailed test results. No c result seen because a single buffer fill did not contain enough data to complete the test.
haveged -n 16k -o tba8ca8 -v 33
  • Generate 16k of data as above with larger buffer. The c test now completes — enough data now generated to complete the test.
haveged -n 16k -o tba8ca8 -v 33 -b 512
  • Generate 16m of data as above, observe many c test completions with default buffer size.
haveged -n 16m -o tba8ca8 -v 33
  • Generate large amounts of data — in this case 16TB. Enable initialization test but made continuous tests advisory only to avoid a possible situation that program will terminate because of procedureB failing two times in a row. The probability of procedureB to fail two times in a row can be estimated as <TB to generate>/3000 which yields 0.5% for 16TB.
haveged -n 16T -o tba8cbw -f - | pv > /dev/null
  • Generate large amounts of data (16TB). Disable continuous tests for the maximum throughput but run the online tests at the startup to make sure that generator for properly initialized:
haveged -n 16T -o tba8c -f - | pv > /dev/null
  • Create a password equivalent to a key strength of 256 bit
haveged -f - -n 32 2>/dev/null | base64 | tr -d =

🌈 SEE ALSO 🌈

like, go read those too, they're the extended universe bestie 🦋

📚 REFERENCES 📚

  • HArdware Volatile Entropy Gathering and Expansion: generating unpredictable random numbers at user level by A. Seznec, N. Sendrier, INRIA Research Report, RR-4592, October 2002
  • A proposal for: Functionality classes for random number generators by W. Killmann and W. Schindler, version 2.0, Bundesamt fur Sicherheit in der Informationstechnik (BSI), September, 2011
  • A Statistical Test Suite for the Validation of Random NUmber Generators and Pseudorandom Number Generators for Cryptographic Applications, special publication SP800-22, National Institute of Standards and Technology, revised April, 2010
  • Additional information can also be found at http://www.issihosts.com/haveged/

👑 AUTHORS 👑

Gary Wuertz <gary@issiweb.com> and Jirka Hladky <hladky jiri AT gmail DOT com>

iconic duo fr fr 💜

and that's the whole page, bestie — you made it to the end 🫶 this was version 1.9, dated February 10, 2014, and it lives in the haveged(8) section of the manual. go forth and generate some beautifully unpredictable bytes, you absolute main character ✨🎀

📦 where this page comes from