402 lines
15 KiB
HTML
402 lines
15 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of haveged</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>haveged</H1>
|
|
Section: SYSTEM ADMINISTRATION COMMANDS (8)<BR>Updated: February 10, 2014<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
haveged - Generate random numbers and feed Linux's random device.
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>haveged [options]</B>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>haveged</B>
|
|
|
|
generates an unpredictable stream of random numbers harvested from the indirect
|
|
effects of hardware events on hidden processor state (caches, branch predictors,
|
|
memory translation tables, etc) using the HAVEGE (HArdware Volatile Entropy
|
|
Gathering and Expansion) algorithm. The algorithm operates in user space, no
|
|
special privilege is required for file system access to the output stream.
|
|
<P>
|
|
|
|
Linux pools randomness for distribution by the /dev/random and /dev/urandom
|
|
device interfaces. 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,
|
|
<B>haveged</B>
|
|
|
|
may 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.
|
|
<P>
|
|
|
|
<B>haveged</B>
|
|
|
|
tunes itself to its environment and provides the same built-in test suite
|
|
for the output stream as used on certified hardware security devices. See
|
|
<B>NOTES</B>
|
|
|
|
below for further information.
|
|
<P>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">-b nnn, --buffer=nnn<DD>
|
|
Set collection buffer size to nnn KW. Default is 128KW (or 512KB).
|
|
<DT id="2">-d nnn, --data=nnn<DD>
|
|
Set data cache size to nnn KB. Default is 16 or as determined dynamically.
|
|
<DT id="3">-f file, --file=file<DD>
|
|
Set output file path for non-daemon use. Default is "sample",
|
|
use "-" for stdout.
|
|
<DT id="4">-F , --Foreground<DD>
|
|
Run daemon in foreground. Do not fork and detach.
|
|
<DT id="5">-i nnn, --inst=nnn<DD>
|
|
Set instruction cache size to nnn KB. Default is 16 or as determined dynamically.
|
|
<DT id="6">-n nnn, --number=nnn<DD>
|
|
Set 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.
|
|
<DT id="7">-o <spec>, --onlinetest=<spec><DD>
|
|
Specify online tests to run. The <spec> consists of optional "t"ot and
|
|
"c"ontinuous groups, each group indicates the procedures to be run, using "a<n>"
|
|
to indicate a 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 a slow
|
|
autocorrelation test (test5). Normally all procedure A tests, except the first
|
|
are iterated 257 times. An a<n> option indicates 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.
|
|
<P>
|
|
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 haveged has initialized properly. The use of both test
|
|
procedures in the "tot" test is highly recommended because the two test emphasize
|
|
different aspects of RNG quality.
|
|
<P>
|
|
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, impacting 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 information on AIS retries see
|
|
<B>NOTES</B>
|
|
|
|
below.
|
|
<P>
|
|
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>
|
|
<DT id="8">-p file, --pidfile=file<DD>
|
|
Set file path for the daemon pid file. Default is "/var/run/haveged.pid",
|
|
<DT id="9">-r n, --run=n<DD>
|
|
Set run level for daemon interface:
|
|
<P>
|
|
n = 0 Run as daemon - must be root. Fills /dev/random when the supply of random bits
|
|
<BR> falls below the low water mark of the device.
|
|
<P>
|
|
n = 1 Display configuration info and terminate.
|
|
<P>
|
|
n > 1 Write <n> kb of output. Deprecated (use --number instead), only provided for backward
|
|
compatibility.
|
|
<P>
|
|
If --number is specified, values other than 0,1 are ignored. Default is 0.
|
|
<DT id="10">-v n, --verbose=n<DD>
|
|
Set diagnostic bitmap as sum of following options:
|
|
<P>
|
|
1=Show build/tuning summary on termination, summary for online test retries.
|
|
<P>
|
|
2=Show online test retry details
|
|
<P>
|
|
4=Show timing for collections
|
|
<P>
|
|
8=Show collection loop layout
|
|
<P>
|
|
16=Show collection loop code offsets
|
|
<P>
|
|
32=Show all online test completion detail
|
|
<P>
|
|
Default is 0. Use -1 for all diagnostics.
|
|
<DT id="11">-w nnn, --write=nnn<DD>
|
|
Set write_wakeup_threshold of daemon interface to nnn bits. Applies only to run level 0.
|
|
<DT id="12">-?, --help<DD>
|
|
This summary of program options.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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 is
|
|
still recommended for the haveged start-up tests. Procedure B is well suited to
|
|
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.
|
|
<P>
|
|
|
|
No test is perfect. 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
|
|
<B><A HREF="/cgi-bin/man/man2html?3+libhavege">libhavege</A>(3)</B>
|
|
|
|
notes for more detailed information.
|
|
<P>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
<P>
|
|
If running as a daemon, access to the following files is required
|
|
<DL COMPACT><DT id="13"><DD>
|
|
<P>
|
|
|
|
<I>/dev/random</I>
|
|
|
|
<P>
|
|
|
|
<I>/proc/sys/kernel/osrelease</I>
|
|
|
|
<P>
|
|
|
|
<I>/proc/sys/kernel/random/poolsize</I>
|
|
|
|
<P>
|
|
|
|
<I>/proc/sys/kernel/random/write_wakeup_threshold</I>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>DIAGNOSTICS</H2>
|
|
|
|
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:
|
|
<P>
|
|
Cannot fork into the background
|
|
<DL COMPACT><DT id="14"><DD>
|
|
Call to <A HREF="/cgi-bin/man/man2html?3+daemon">daemon</A>(3) failed.
|
|
<P>
|
|
</DL>
|
|
|
|
Cannot open file <s> for writing.
|
|
<DL COMPACT><DT id="15"><DD>
|
|
Could not open sample file <s> for writing.
|
|
<P>
|
|
</DL>
|
|
|
|
Cannot write data in file:
|
|
<DL COMPACT><DT id="16"><DD>
|
|
Could not write data to the sample file.
|
|
<P>
|
|
</DL>
|
|
|
|
Couldn't get pool size.
|
|
<DL COMPACT><DT id="17"><DD>
|
|
Unable to read /proc/sys/kernel/random/poolsize
|
|
<P>
|
|
</DL>
|
|
|
|
Couldn't initialize HAVEGE rng
|
|
<DL COMPACT><DT id="18"><DD>
|
|
Invalid data or instruction cache size.
|
|
<P>
|
|
</DL>
|
|
|
|
Couldn't open PID file <s> for writing
|
|
<DL COMPACT><DT id="19"><DD>
|
|
Unable to write daemon PID
|
|
<P>
|
|
</DL>
|
|
|
|
Couldn't open random device
|
|
<DL COMPACT><DT id="20"><DD>
|
|
Could not open /dev/random for read-write.
|
|
<P>
|
|
</DL>
|
|
|
|
Couldn't query entropy-level from kernel: error
|
|
<DL COMPACT><DT id="21"><DD>
|
|
Call to <A HREF="/cgi-bin/man/man2html?2+ioctl">ioctl</A>(2) failed.
|
|
<P>
|
|
</DL>
|
|
|
|
Couldn't open PID file <path> for writing
|
|
<DL COMPACT><DT id="22"><DD>
|
|
Error writing /var/run/haveged.pid
|
|
<P>
|
|
</DL>
|
|
|
|
Fail:set_watermark()
|
|
<DL COMPACT><DT id="23"><DD>
|
|
Unable to write to /proc/sys/kernel/random/write_wakeup_threshold
|
|
<P>
|
|
</DL>
|
|
|
|
RNDADDENTROPY failed!
|
|
<DL COMPACT><DT id="24"><DD>
|
|
Call to <A HREF="/cgi-bin/man/man2html?2+ioctl">ioctl</A>(2) to add entropy failed
|
|
<P>
|
|
</DL>
|
|
|
|
RNG failed
|
|
<DL COMPACT><DT id="25"><DD>
|
|
The random number generator failed self-test or encountered a fatal error.
|
|
<P>
|
|
</DL>
|
|
|
|
Select error
|
|
<DL COMPACT><DT id="26"><DD>
|
|
Call to <A HREF="/cgi-bin/man/man2html?2+select">select</A>(2) failed.
|
|
<P>
|
|
</DL>
|
|
|
|
Stopping due to signal <n>
|
|
<DL COMPACT><DT id="27"><DD>
|
|
Signal <n> caught.
|
|
<P>
|
|
</DL>
|
|
|
|
Unable to setup online tests
|
|
<DL COMPACT><DT id="28"><DD>
|
|
Memory unavailable for online test resources.
|
|
<P>
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="29">Write 1.5MB of random data to the file /tmp/random<DD>
|
|
haveged -n 1.5M -f /tmp/random
|
|
<DT id="30">Generate a /tmp/keyfile for disk encryption with LUKS<DD>
|
|
haveged -n 2048 -f /tmp/keyfile
|
|
<DT id="31">Overwrite partition /dev/sda1 with random data. Be careful, all data on the partition will be lost!<DD>
|
|
haveged -n 0 | dd of=/dev/sda1
|
|
<DT id="32">Generate random ASCII passwords of the length 16 characters<DD>
|
|
(haveged -n 1000 -f - 2>/dev/null | tr -cd '[:graph:]' | fold -w 16 && echo ) | head
|
|
<DT id="33">Write endless stream of random bytes to the pipe. Utility pv measures the speed by which data are written to the pipe.<DD>
|
|
haveged -n 0 | pv > /dev/null
|
|
<DT id="34">Evaluate speed of haveged to generate 1GB of random data<DD>
|
|
haveged -n 1g -f - | dd of=/dev/null
|
|
<DT id="35">Create a random key file containing 65 random keys for the encryption program aespipe.<DD>
|
|
haveged -n 3705 -f - 2>/dev/null | uuencode -m - | head -n 66 | tail -n 65
|
|
<DT id="36">Test the randomness of the generated data with dieharder test suite<DD>
|
|
haveged -n 0 | dieharder -g 200 -a
|
|
<DT id="37">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.<DD>
|
|
haveged -n 16k -o tba8ca8 -v 33
|
|
<DT id="38">Generate 16k of data as above with larger buffer. The c test now completes - enough data now generated to complete the test.<DD>
|
|
haveged -n 16k -o tba8ca8 -v 33 -b 512
|
|
<DT id="39">Generate 16m of data as above, observe many c test completions with default buffer size.<DD>
|
|
haveged -n 16m -o tba8ca8 -v 33
|
|
<DT id="40">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.<DD>
|
|
haveged -n 16T -o tba8cbw -f - | pv > /dev/null
|
|
<DT id="41">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:<DD>
|
|
haveged -n 16T -o tba8c -f - | pv > /dev/null
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="42"><B><A HREF="/cgi-bin/man/man2html?3+libhavege">libhavege</A>(3),</B>
|
|
|
|
<DD>
|
|
<B><A HREF="/cgi-bin/man/man2html?8+cryptsetup">cryptsetup</A>(8),</B>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+aespipe">aespipe</A>(1),</B>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+pv">pv</A>(1),</B>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+openssl">openssl</A>(1),</B>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+uuencode">uuencode</A>(1)</B>
|
|
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>REFERENCES</H2>
|
|
|
|
<P>
|
|
<I>HArdware Volatile Entropy Gathering and Expansion: generating unpredictable random numbers at user level</I>
|
|
|
|
by A. Seznec, N. Sendrier, INRIA Research Report, RR-4592, October 2002
|
|
<P>
|
|
<I>A proposal for: Functionality classes for random number generators</I>
|
|
|
|
by W. Killmann and W. Schindler, version 2.0, Bundesamt fur Sicherheit in der
|
|
Informationstechnik (BSI), September, 2011
|
|
<P>
|
|
<I>A Statistical Test Suite for the Validation of Random NUmber Generators and Pseudorandom Number Generators for Cryptographic Applications,</I>
|
|
|
|
special publication SP800-22, National Institute of Standards and Technology, revised April, 2010
|
|
<P>
|
|
Additional information can also be found at
|
|
<B><A HREF="http://www.issihosts.com/haveged/">http://www.issihosts.com/haveged/</A></B>
|
|
|
|
<P>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
Gary Wuertz <<A HREF="mailto:gary@issiweb.com">gary@issiweb.com</A>> and Jirka Hladky <hladky jiri AT gmail DOT com>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="43"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="44"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="45"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="46"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="47"><A HREF="#lbAF">NOTES</A><DD>
|
|
<DT id="48"><A HREF="#lbAG">FILES</A><DD>
|
|
<DT id="49"><A HREF="#lbAH">DIAGNOSTICS</A><DD>
|
|
<DT id="50"><A HREF="#lbAI">EXAMPLES</A><DD>
|
|
<DT id="51"><A HREF="#lbAJ">SEE ALSO</A><DD>
|
|
<DT id="52"><A HREF="#lbAK">REFERENCES</A><DD>
|
|
<DT id="53"><A HREF="#lbAL">AUTHORS</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:12 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|