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 known commands
40 are close to close the current communication socket of the run‐
41 ning haveged process as well as root=<new_root> where <new_root>
42 is a place holder for the path of the real new root directory
43 which should provide a haveged installation. The haveged process
44 or daemon will perform a chroot(2) system call followed by a
45 execv(3) to become rebased within the new root directory.
46 -d nnn, --data=nnn
48 Set data cache size to nnn KB. Default is 16 or as determined
49 dynamically.
50 -f file, --file=file
52 Set output file path for non-daemon use. Default is "sample",
53 use "-" for stdout.
54 -F , --Foreground
56 Run daemon in foreground. Do not fork and detach.
57 -i nnn, --inst=nnn
59 Set instruction cache size to nnn KB. Default is 16 or as deter‐
60 mined dynamically.
61 -n nnn, --number=nnn
63 Set number of bytes written to the output file. The value may be
64 specified using one of the suffixes k, m, g, or t. The upper
65 bound of this value is "16t" (2^44 Bytes = 16TB). A value of 0
66 indicates unbounded output and forces output to stdout. This
67 argument is required if the daemon interface is not present. If
68 the daemon interface is present, this setting takes precedence
69 over any --run value.
70 -o <spec>, --onlinetest=<spec>
72 Specify online tests to run. The <spec> consists of optional
73 "t"ot and "c"ontinuous groups, each group indicates the proce‐
74 dures to be run, using "a<n>" to indicate a AIS-31 procedure A
75 variant, and "b" to indicate AIS procedure B. The specifica‐
76 tions are order independent (procedure B always runs first in
77 each group) and case insensitive. The a<n> variations exist to
78 mitigate the a slow autocorrelation test (test5). Normally all
79 procedure A tests, except the first are iterated 257 times. An
80 a<n> option indicates test5 should only be executed every modulo
81 <n> times during the procedure's 257 repetitions. The effect is
82 so noticeable that A8 is the usual choice.
83 The "tot" tests run only at initialization - there are no nega‐
85 tive performance consequences except for a slight increase in
86 the time required to initialize. The "tot" tests guarantee
87 haveged has initialized properly. The use of both test proce‐
88 dures in the "tot" test is highly recommended because the two
89 test emphasize different aspects of RNG quality.
90 In continuous testing, the test sequence is cycled repeatedly.
92 For example, the string "tbca8b" (suitable for an AIS NTG.1
93 device) would run procedure B for the "tot" test, then cycle
94 between procedure A8 and procedure B continuously for all fur‐
95 ther output. Continuous testing does not come for free, impact‐
96 ing both throughput and resource consumption. Continual testing
97 also opens up the possibility of a test failure. A strict retry
98 procedure recovers from spurious failure in all but the most
99 extreme circumstances. When the retry fails, operation will ter‐
100 minate unless a "w" has been appended to the test token to make
101 the test advisory only. In our example above, the string
102 "tbca8wbw" would make all continuous tests advisory. For more
103 detailed information on AIS retries see NOTES below.
104 Complete control over the test configuration is provided for
106 flexibility. The defaults (ta8bcb" if run as a daemon and "ta8b"
107 otherwise) are suitable for most circumstances.
108 -p file, --pidfile=file
111 Set file path for the daemon pid file. Default is
112 "/var/run/haveged.pid",
113 -r n, --run=n
115 Set run level for daemon interface:
116 n = 0 Run as daemon - must be root. Fills /dev/random when the
118 supply of random bits
119 falls below the low water mark of the device.
120 n = 1 Display configuration info and terminate.
122 n > 1 Write <n> kb of output. Deprecated (use --number instead),
124 only provided for backward compatibility.
125 If --number is specified, values other than 0,1 are ignored.
127 Default is 0.
128 -v n, --verbose=n
130 Set diagnostic bitmap as sum of following options:
131 1=Show build/tuning summary on termination, summary for online
133 test retries.
134 2=Show online test retry details
136 4=Show timing for collections
138 8=Show collection loop layout
140 16=Show collection loop code offsets
142 32=Show all online test completion detail
144 Default is 0. Use -1 for all diagnostics.
146 -w nnn, --write=nnn
148 Set write_wakeup_threshold of daemon interface to nnn bits.
149 Applies only to run level 0.
150 -?, --help
152 This summary of program options.
153
156 haveged tunes the HAVEGE algorithm for maximum effectiveness using a
157 hierarchy of defaults, command line options, virtual file system infor‐
158 mation, and cpuid information where available. Under most circum‐
159 stances, user input is not required for excellent results.
160 Run-time testing provides assurance of correct haveged operation. The
162 run-time test suite is modeled upon the AIS-31 specification of the
163 German Common Criteria body, BIS. This specification is typically
164 applied to hardware devices, requiring formal certification and man‐
165 dated start-up and continuous operational testing. Because haveged runs
166 on many different hardware platforms, certification cannot be a goal,
167 but the AIS-31 test suite provides the means to assess haveged output
168 with the same operational tests applied to certified hardware devices.
169 AIS test procedure A performs 6 tests to check for statistically incon‐
171 spicuous behavior. AIS test procedure B performs more theoretical tests
172 such as checking multi-step transition probabilities and making an
173 empirical entropy estimate. Procedure A is the much more resource and
174 compute intensive of the two but is still recommended for the haveged
175 start-up tests. Procedure B is well suited to use of haveged as a dae‐
176 mon because the test entropy estimate confirms the entropy estimate
177 haveged uses when adding entropy to the /dev/random device.
178 No test is perfect. There is a 10e-4 probability that a perfect genera‐
180 tor will fail either of the test procedures. AIS-31 mandates a strict
181 retry policy to filter out false alarms and haveged always logs test
182 procedure failures. Retries are expected but rarely observed except
183 when large data sets are generated with continuous testing. See the
184 libhavege(3) notes for more detailed information.
185
188 If running as a daemon, access to the following files is required
189 /dev/random
191 /proc/sys/kernel/osrelease
193 /proc/sys/kernel/random/poolsize
195 /proc/sys/kernel/random/write_wakeup_threshold
197
200 Haveged returns 0 for success and non-zero for failure. The failure
201 return code is 1 "general failure" unless execution is terminated by
202 signal <n>, in which case the return code will be 128 + <n>. The fol‐
203 lowing diagnostics are issued to stderr upon non-zero termination:
204 Cannot fork into the background
206 Call to daemon(3) failed.
207 Cannot open file <s> for writing.
209 Could not open sample file <s> for writing.
210 Cannot write data in file:
212 Could not write data to the sample file.
213 Couldn't get pool size.
215 Unable to read /proc/sys/kernel/random/poolsize
216 Couldn't initialize HAVEGE rng
218 Invalid data or instruction cache size.
219 Couldn't open PID file <s> for writing
221 Unable to write daemon PID
222 Couldn't open random device
224 Could not open /dev/random for read-write.
225 Couldn't query entropy-level from kernel: error
227 Call to ioctl(2) failed.
228 Couldn't open PID file <path> for writing
230 Error writing /var/run/haveged.pid
231 Fail:set_watermark()
233 Unable to write to /proc/sys/kernel/random/write_wakeup_thresh‐
234 old
235 RNDADDENTROPY failed!
237 Call to ioctl(2) to add entropy failed
238 RNG failed
240 The random number generator failed self-test or encountered a
241 fatal error.
242 Select error
244 Call to select(2) failed.
245 Stopping due to signal <n>
247 Signal <n> caught.
248 Unable to setup online tests
250 Memory unavailable for online test resources.
251
255 Write 1.5MB of random data to the file /tmp/random
256 haveged -n 1.5M -f /tmp/random
257 Generate a /tmp/keyfile for disk encryption with LUKS
259 haveged -n 2048 -f /tmp/keyfile
260 Overwrite partition /dev/sda1 with random data. Be careful, all data on
262 the partition will be lost!
263 haveged -n 0 | dd of=/dev/sda1
264 Generate random ASCII passwords of the length 16 characters
266 (haveged -n 1000 -f - 2>/dev/null | tr -cd '[:graph:]' | fold -w
267 16 && echo ) | head
268 Write endless stream of random bytes to the pipe. Utility pv measures
270 the speed by which data are written to the pipe.
271 haveged -n 0 | pv > /dev/null
272 Evaluate speed of haveged to generate 1GB of random data
274 haveged -n 1g -f - | dd of=/dev/null
275 Create a random key file containing 65 random keys for the encryption
277 program aespipe.
278 haveged -n 3705 -f - 2>/dev/null | uuencode -m - | head -n 66 |
279 tail -n 65
280 Test the randomness of the generated data with dieharder test suite
282 haveged -n 0 | dieharder -g 200 -a
283 Generate 16k of data, testing with procedure A and B with detailed test
285 results. No c result seen because a single buffer fill did not contain
286 enough data to complete the test.
287 haveged -n 16k -o tba8ca8 -v 33
288 Generate 16k of data as above with larger buffer. The c test now com‐
290 pletes - enough data now generated to complete the test.
291 haveged -n 16k -o tba8ca8 -v 33 -b 512
292 Generate 16m of data as above, observe many c test completions with
294 default buffer size.
295 haveged -n 16m -o tba8ca8 -v 33
296 Generate large amounts of data - in this case 16TB. Enable initializa‐
298 tion test but made continuous tests advisory only to avoid a possible
299 situation that program will terminate because of procedureB failing two
300 times in a row. The probability of procedureB to fail two times in a
301 row can be estimated as <TB to generate>/3000 which yields 0.5% for
302 16TB.
303 haveged -n 16T -o tba8cbw -f - | pv > /dev/null
304 Generate large amounts of data (16TB). Disable continuous tests for the
306 maximum throughput but run the online tests at the startup to make sure
307 that generator for properly initialized:
308 haveged -n 16T -o tba8c -f - | pv > /dev/null
309
312 libhavege(3),
313 cryptsetup(8), aespipe(1), pv(1), openssl(1), uuencode(1)
314
317 HArdware Volatile Entropy Gathering and Expansion: generating unpre‐
318 dictable random numbers at user level by A. Seznec, N. Sendrier, INRIA
319 Research Report, RR-4592, October 2002
320 A proposal for: Functionality classes for random number generators by
322 W. Killmann and W. Schindler, version 2.0, Bundesamt fur Sicherheit in
323 der Informationstechnik (BSI), September, 2011
324 A Statistical Test Suite for the Validation of Random NUmber Generators
326 and Pseudorandom Number Generators for Cryptographic Applications, spe‐
327 cial publication SP800-22, National Institute of Standards and Technol‐
328 ogy, revised April, 2010
329 Additional information can also be found at http://www.issi‐
331 hosts.com/haveged/
332
335 Gary Wuertz <gary@issiweb.com> and Jirka Hladky <hladky jiri AT gmail
336 DOT com>
337version 1.9 February 10, 2014 haveged(8)