1haveged(8)              SYSTEM ADMINISTRATION COMMANDS              haveged(8)
2
3
4

NAME

6       haveged - Generate random numbers and feed Linux's random device.
7

SYNOPSIS

9       haveged [options]
10

DESCRIPTION

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
19       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
27       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
31

OPTIONS

33       -b nnn, --buffer=nnn
34              Set collection buffer size to  nnn  KW.  Default  is  128KW  (or
35              512KB).
36
37       -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
47       -d nnn, --data=nnn
48              Set data cache size to nnn KB. Default is 16  or  as  determined
49              dynamically.
50
51       -f file, --file=file
52              Set  output  file  path for non-daemon use. Default is "sample",
53              use "-" for stdout.
54
55       -F , --Foreground
56              Run daemon in foreground. Do not fork and detach.
57
58       -e , --once
59              Provide entropy to the kernel once and quit immediatelly.
60
61       -i nnn, --inst=nnn
62              Set instruction cache size to nnn KB. Default is 16 or as deter‐
63              mined dynamically.
64
65       -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
74       -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
87              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
94              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
108              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
112
113       -p file, --pidfile=file
114              Set  file  path  for   the   daemon   pid   file.   Default   is
115              "/var/run/haveged.pid",
116
117       -r n, --run=n
118              Set run level for daemon interface:
119
120              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
124              n = 1 Display configuration info and terminate.
125
126              n > 1 Write <n> kb of output. Deprecated (use --number instead),
127              only provided for backward compatibility.
128
129              If --number is specified, values other than 0,1 are ignored. De‐
130              fault is 0.
131
132       -v n, --verbose=n
133              Set diagnostic bitmap as sum of following options:
134
135              1=Show build/tuning summary on termination, summary  for  online
136              test retries.
137
138              2=Show online test retry details
139
140              4=Show timing for collections
141
142              8=Show collection loop layout
143
144              16=Show collection loop code offsets
145
146              32=Show all online test completion detail
147
148              64=Show info on RNDADDENTROPY operation
149
150              Default is 0. Use -1 for all diagnostics.
151
152       -w nnn, --write=nnn
153              Set  write_wakeup_threshold of daemon interface to nnn bits. Ap‐
154              plies only to run level 0.
155
156       -V, --version
157              Print version information and exit
158
159       -?, --help
160              This summary of program options.
161
162

NOTES

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
169       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
178       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
187       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
194

FILES

196       If running as a daemon, access to the following files is required
197
198              /dev/random
199
200              /proc/sys/kernel/osrelease
201
202              /proc/sys/kernel/random/poolsize
203
204              /proc/sys/kernel/random/write_wakeup_threshold
205
206

DIAGNOSTICS

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
213       Cannot fork into the background
214              Call to daemon(3) failed.
215
216       Cannot open file <s> for writing.
217              Could not open sample file <s> for writing.
218
219       Cannot write data in file:
220              Could not write data to the sample file.
221
222       Couldn't get pool size.
223              Unable to read /proc/sys/kernel/random/poolsize
224
225       Couldn't initialize HAVEGE rng
226              Invalid data or instruction cache size.
227
228       Couldn't open PID file <s> for writing
229              Unable to write daemon PID
230
231       Couldn't open random device
232              Could not open /dev/random for read-write.
233
234       Couldn't query entropy-level from kernel: error
235              Call to ioctl(2) failed.
236
237       Couldn't open PID file <path> for writing
238              Error writing /var/run/haveged.pid
239
240       Fail:set_watermark()
241              Unable  to write to /proc/sys/kernel/random/write_wakeup_thresh‐
242              old
243
244       RNDADDENTROPY failed!
245              Call to ioctl(2) to add entropy failed
246
247       RNG failed
248              The random number generator failed self-test  or  encountered  a
249              fatal error.
250
251       Select error
252              Call to select(2) failed.
253
254       Stopping due to signal <n>
255              Signal <n> caught.
256
257       Unable to setup online tests
258              Memory unavailable for online test resources.
259
260
261

EXAMPLES

263       Write 1.5MB of random data to the file /tmp/random
264              haveged -n 1.5M -f /tmp/random
265
266       Generate a /tmp/keyfile for disk encryption with LUKS
267              haveged -n 2048 -f /tmp/keyfile
268
269       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
273       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
277       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
281       Evaluate speed of haveged to generate 1GB of random data
282              haveged -n 1g -f - | dd of=/dev/null
283
284       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
289       Test the randomness of the generated data with dieharder test suite
290              haveged -n 0 | dieharder -g 200 -a
291
292       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
297       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
301       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
305       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
313       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
318       Create a password equivalent to a key strength of 256 bit
319              haveged -f - -n 32 2>/dev/null | base64 | tr -d =
320
321

SEE ALSO

323       libhavege(3),
324              cryptsetup(8), aespipe(1), pv(1), openssl(1), uuencode(1)
325
326

REFERENCES

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
332       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
336       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
341       Additional  information  can  also   be   found   at   http://www.issi
342       hosts.com/haveged/
343
344

AUTHORS

346       Gary  Wuertz  <gary@issiweb.com> and Jirka Hladky <hladky jiri AT gmail
347       DOT com>
348
349
350
351version 1.9                    February 10, 2014                    haveged(8)
Impressum