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