1haveged(8) SYSTEM ADMINISTRATION COMMANDS haveged(8)
2
6 haveged - Generate random numbers and feed Linux's random device.
7
9 haveged [options]
10
12 haveged generates an unpredictable stream of random numbers harvested
13 from the indirect effects of hardware events on hidden processor state
14 (caches, branch predictors, memory translation tables, etc) using the
15 HAVEGE (HArdware Volatile Entropy Gathering and Expansion) algorithm.
16 The algorithm operates in user space, no special privilege is required
17 for file system access to the output stream.
18 Linux pools randomness for distribution by the /dev/random and
20 /dev/urandom device interfaces. The standard mechanisms of filling the
21 /dev/random pool may not be sufficient to meet demand on systems with
22 high needs or limited user interaction. In those circumstances, haveged
23 may be run as a privileged daemon to fill the /dev/random pool whenever
24 the supply of random bits in /dev/random falls below the low water mark
25 of the device.
26 haveged tunes itself to its environment and provides the same built-in
28 test suite for the output stream as used on certified hardware security
29 devices. See NOTES below for further information.
30
33 -b nnn, --buffer=nnn
34 Set collection buffer size to nnn KW. Default is 128KW (or
35 512KB).
36 -c cmd, --command=cmd
38 Switch to command mode and send a command to an already running
39 haveged process or daemon. Currently the only knows command is
40 root=<new_root> where <new_root> is a place holder for the path
41 of the real new root directory which should provide a haveged
42 installation. The haveged process or daemon will perform a
43 chroot(2) system call followed by a execv(3) to become rebased
44 within the new root directory.
45 -d nnn, --data=nnn
47 Set data cache size to nnn KB. Default is 16 or as determined
48 dynamically.
49 -f file, --file=file
51 Set output file path for non-daemon use. Default is "sample",
52 use "-" for stdout.
53 -F , --Foreground
55 Run daemon in foreground. Do not fork and detach.
56 -i nnn, --inst=nnn
58 Set instruction cache size to nnn KB. Default is 16 or as deter‐
59 mined dynamically.
60 -n nnn, --number=nnn
62 Set number of bytes written to the output file. The value may be
63 specified using one of the suffixes k, m, g, or t. The upper
64 bound of this value is "16t" (2^44 Bytes = 16TB). A value of 0
65 indicates unbounded output and forces output to stdout. This
66 argument is required if the daemon interface is not present. If
67 the daemon interface is present, this setting takes precedence
68 over any --run value.
69 -o <spec>, --onlinetest=<spec>
71 Specify online tests to run. The <spec> consists of optional
72 "t"ot and "c"ontinuous groups, each group indicates the proce‐
73 dures to be run, using "a<n>" to indicate a AIS-31 procedure A
74 variant, and "b" to indicate AIS procedure B. The specifica‐
75 tions are order independent (procedure B always runs first in
76 each group) and case insensitive. The a<n> variations exist to
77 mitigate the a slow autocorrelation test (test5). Normally all
78 procedure A tests, except the first are iterated 257 times. An
79 a<n> option indicates test5 should only be executed every modulo
80 <n> times during the procedure's 257 repetitions. The effect is
81 so noticeable that A8 is the usual choice.
82 The "tot" tests run only at initialization - there are no nega‐
84 tive performance consequences except for a slight increase in
85 the time required to initialize. The "tot" tests guarantee
86 haveged has initialized properly. The use of both test proce‐
87 dures in the "tot" test is highly recommended because the two
88 test emphasize different aspects of RNG quality.
89 In continuous testing, the test sequence is cycled repeatedly.
91 For example, the string "tbca8b" (suitable for an AIS NTG.1
92 device) would run procedure B for the "tot" test, then cycle
93 between procedure A8 and procedure B continuously for all fur‐
94 ther output. Continuous testing does not come for free, impact‐
95 ing both throughput and resource consumption. Continual testing
96 also opens up the possibility of a test failure. A strict retry
97 procedure recovers from spurious failure in all but the most
98 extreme circumstances. When the retry fails, operation will ter‐
99 minate unless a "w" has been appended to the test token to make
100 the test advisory only. In our example above, the string
101 "tbca8wbw" would make all continuous tests advisory. For more
102 detailed information on AIS retries see NOTES below.
103 Complete control over the test configuration is provided for
105 flexibility. The defaults (ta8bcb" if run as a daemon and "ta8b"
106 otherwise) are suitable for most circumstances.
107 -p file, --pidfile=file
110 Set file path for the daemon pid file. Default is
111 "/var/run/haveged.pid",
112 -r n, --run=n
114 Set run level for daemon interface:
115 n = 0 Run as daemon - must be root. Fills /dev/random when the
117 supply of random bits
118 falls below the low water mark of the device.
119 n = 1 Display configuration info and terminate.
121 n > 1 Write <n> kb of output. Deprecated (use --number instead),
123 only provided for backward compatibility.
124 If --number is specified, values other than 0,1 are ignored.
126 Default is 0.
127 -v n, --verbose=n
129 Set diagnostic bitmap as sum of following options:
130 1=Show build/tuning summary on termination, summary for online
132 test retries.
133 2=Show online test retry details
135 4=Show timing for collections
137 8=Show collection loop layout
139 16=Show collection loop code offsets
141 32=Show all online test completion detail
143 Default is 0. Use -1 for all diagnostics.
145 -w nnn, --write=nnn
147 Set write_wakeup_threshold of daemon interface to nnn bits.
148 Applies only to run level 0.
149 -?, --help
151 This summary of program options.
152
155 haveged tunes the HAVEGE algorithm for maximum effectiveness using a
156 hierarchy of defaults, command line options, virtual file system infor‐
157 mation, and cpuid information where available. Under most circum‐
158 stances, user input is not required for excellent results.
159 Run-time testing provides assurance of correct haveged operation. The
161 run-time test suite is modeled upon the AIS-31 specification of the
162 German Common Criteria body, BIS. This specification is typically
163 applied to hardware devices, requiring formal certification and man‐
164 dated start-up and continuous operational testing. Because haveged runs
165 on many different hardware platforms, certification cannot be a goal,
166 but the AIS-31 test suite provides the means to assess haveged output
167 with the same operational tests applied to certified hardware devices.
168 AIS test procedure A performs 6 tests to check for statistically incon‐
170 spicuous behavior. AIS test procedure B performs more theoretical tests
171 such as checking multi-step transition probabilities and making an
172 empirical entropy estimate. Procedure A is the much more resource and
173 compute intensive of the two but is still recommended for the haveged
174 start-up tests. Procedure B is well suited to use of haveged as a dae‐
175 mon because the test entropy estimate confirms the entropy estimate
176 haveged uses when adding entropy to the /dev/random device.
177 No test is perfect. There is a 10e-4 probability that a perfect genera‐
179 tor will fail either of the test procedures. AIS-31 mandates a strict
180 retry policy to filter out false alarms and haveged always logs test
181 procedure failures. Retries are expected but rarely observed except
182 when large data sets are generated with continuous testing. See the
183 libhavege(3) notes for more detailed information.
184
187 If running as a daemon, access to the following files is required
188 /dev/random
190 /proc/sys/kernel/osrelease
192 /proc/sys/kernel/random/poolsize
194 /proc/sys/kernel/random/write_wakeup_threshold
196
199 Haveged returns 0 for success and non-zero for failure. The failure
200 return code is 1 "general failure" unless execution is terminated by
201 signal <n>, in which case the return code will be 128 + <n>. The fol‐
202 lowing diagnostics are issued to stderr upon non-zero termination:
203 Cannot fork into the background
205 Call to daemon(3) failed.
206 Cannot open file <s> for writing.
208 Could not open sample file <s> for writing.
209 Cannot write data in file:
211 Could not write data to the sample file.
212 Couldn't get pool size.
214 Unable to read /proc/sys/kernel/random/poolsize
215 Couldn't initialize HAVEGE rng
217 Invalid data or instruction cache size.
218 Couldn't open PID file <s> for writing
220 Unable to write daemon PID
221 Couldn't open random device
223 Could not open /dev/random for read-write.
224 Couldn't query entropy-level from kernel: error
226 Call to ioctl(2) failed.
227 Couldn't open PID file <path> for writing
229 Error writing /var/run/haveged.pid
230 Fail:set_watermark()
232 Unable to write to /proc/sys/kernel/random/write_wakeup_thresh‐
233 old
234 RNDADDENTROPY failed!
236 Call to ioctl(2) to add entropy failed
237 RNG failed
239 The random number generator failed self-test or encountered a
240 fatal error.
241 Select error
243 Call to select(2) failed.
244 Stopping due to signal <n>
246 Signal <n> caught.
247 Unable to setup online tests
249 Memory unavailable for online test resources.
250
254 Write 1.5MB of random data to the file /tmp/random
255 haveged -n 1.5M -f /tmp/random
256 Generate a /tmp/keyfile for disk encryption with LUKS
258 haveged -n 2048 -f /tmp/keyfile
259 Overwrite partition /dev/sda1 with random data. Be careful, all data on
261 the partition will be lost!
262 haveged -n 0 | dd of=/dev/sda1
263 Generate random ASCII passwords of the length 16 characters
265 (haveged -n 1000 -f - 2>/dev/null | tr -cd '[:graph:]' | fold -w
266 16 && echo ) | head
267 Write endless stream of random bytes to the pipe. Utility pv measures
269 the speed by which data are written to the pipe.
270 haveged -n 0 | pv > /dev/null
271 Evaluate speed of haveged to generate 1GB of random data
273 haveged -n 1g -f - | dd of=/dev/null
274 Create a random key file containing 65 random keys for the encryption
276 program aespipe.
277 haveged -n 3705 -f - 2>/dev/null | uuencode -m - | head -n 66 |
278 tail -n 65
279 Test the randomness of the generated data with dieharder test suite
281 haveged -n 0 | dieharder -g 200 -a
282 Generate 16k of data, testing with procedure A and B with detailed test
284 results. No c result seen because a single buffer fill did not contain
285 enough data to complete the test.
286 haveged -n 16k -o tba8ca8 -v 33
287 Generate 16k of data as above with larger buffer. The c test now com‐
289 pletes - enough data now generated to complete the test.
290 haveged -n 16k -o tba8ca8 -v 33 -b 512
291 Generate 16m of data as above, observe many c test completions with
293 default buffer size.
294 haveged -n 16m -o tba8ca8 -v 33
295 Generate large amounts of data - in this case 16TB. Enable initializa‐
297 tion test but made continuous tests advisory only to avoid a possible
298 situation that program will terminate because of procedureB failing two
299 times in a row. The probability of procedureB to fail two times in a
300 row can be estimated as <TB to generate>/3000 which yields 0.5% for
301 16TB.
302 haveged -n 16T -o tba8cbw -f - | pv > /dev/null
303 Generate large amounts of data (16TB). Disable continuous tests for the
305 maximum throughput but run the online tests at the startup to make sure
306 that generator for properly initialized:
307 haveged -n 16T -o tba8c -f - | pv > /dev/null
308
311 libhavege(3),
312 cryptsetup(8), aespipe(1), pv(1), openssl(1), uuencode(1)
313
316 HArdware Volatile Entropy Gathering and Expansion: generating unpre‐
317 dictable random numbers at user level by A. Seznec, N. Sendrier, INRIA
318 Research Report, RR-4592, October 2002
319 A proposal for: Functionality classes for random number generators by
321 W. Killmann and W. Schindler, version 2.0, Bundesamt fur Sicherheit in
322 der Informationstechnik (BSI), September, 2011
323 A Statistical Test Suite for the Validation of Random NUmber Generators
325 and Pseudorandom Number Generators for Cryptographic Applications, spe‐
326 cial publication SP800-22, National Institute of Standards and Technol‐
327 ogy, revised April, 2010
328 Additional information can also be found at http://www.issi‐
330 hosts.com/haveged/
331
334 Gary Wuertz <gary@issiweb.com> and Jirka Hladky <hladky jiri AT gmail
335 DOT com>
336version 1.9 February 10, 2014 haveged(8)