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 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
46       -d nnn, --data=nnn
47              Set  data  cache  size to nnn KB. Default is 16 or as determined
48              dynamically.
49
50       -f file, --file=file
51              Set output file path for non-daemon use.  Default  is  "sample",
52              use "-" for stdout.
53
54       -F , --Foreground
55              Run daemon in foreground. Do not fork and detach.
56
57       -i nnn, --inst=nnn
58              Set instruction cache size to nnn KB. Default is 16 or as deter‐
59              mined dynamically.
60
61       -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
70       -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
83              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
90              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
104              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
108
109       -p file, --pidfile=file
110              Set   file   path   for   the   daemon   pid  file.  Default  is
111              "/var/run/haveged.pid",
112
113       -r n, --run=n
114              Set run level for daemon interface:
115
116              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
120              n = 1 Display configuration info and terminate.
121
122              n > 1 Write <n> kb of output. Deprecated (use --number instead),
123              only provided for backward compatibility.
124
125              If --number is specified, values other  than  0,1  are  ignored.
126              Default is 0.
127
128       -v n, --verbose=n
129              Set diagnostic bitmap as sum of following options:
130
131              1=Show  build/tuning  summary on termination, summary for online
132              test retries.
133
134              2=Show online test retry details
135
136              4=Show timing for collections
137
138              8=Show collection loop layout
139
140              16=Show collection loop code offsets
141
142              32=Show all online test completion detail
143
144              Default is 0. Use -1 for all diagnostics.
145
146       -w nnn, --write=nnn
147              Set write_wakeup_threshold of  daemon  interface  to  nnn  bits.
148              Applies only to run level 0.
149
150       -?, --help
151              This summary of program options.
152
153

NOTES

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
160       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
169       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
178       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
185

FILES

187       If running as a daemon, access to the following files is required
188
189              /dev/random
190
191              /proc/sys/kernel/osrelease
192
193              /proc/sys/kernel/random/poolsize
194
195              /proc/sys/kernel/random/write_wakeup_threshold
196
197

DIAGNOSTICS

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

EXAMPLES

254       Write 1.5MB of random data to the file /tmp/random
255              haveged -n 1.5M -f /tmp/random
256
257       Generate a /tmp/keyfile for disk encryption with LUKS
258              haveged -n 2048 -f /tmp/keyfile
259
260       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
264       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
268       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
272       Evaluate speed of haveged to generate 1GB of random data
273              haveged -n 1g -f - | dd of=/dev/null
274
275       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
280       Test the randomness of the generated data with dieharder test suite
281              haveged -n 0 | dieharder -g 200 -a
282
283       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
288       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
292       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
296       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
304       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
309

SEE ALSO

311       libhavege(3),
312              cryptsetup(8), aespipe(1), pv(1), openssl(1), uuencode(1)
313
314

REFERENCES

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
320       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
324       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
329       Additional   information   can   also   be  found  at  http://www.issi
330       hosts.com/haveged/
331
332

AUTHORS

334       Gary Wuertz <gary@issiweb.com> and Jirka Hladky <hladky jiri  AT  gmail
335       DOT com>
336
337
338
339version 1.9                    February 10, 2014                    haveged(8)
Impressum