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