haveged(8)


NAME

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

SYNOPSIS

   haveged [options]

DESCRIPTION

   haveged  generates  an unpredictable stream of random numbers harvested
   from the indirect effects of hardware events on hidden processor  state
   (caches,  branch  predictors, memory translation tables, etc) using the
   HAVEGE (HArdware Volatile Entropy Gathering and  Expansion)  algorithm.
   The  algorithm operates in user space, no special privilege is required
   for file system access to the output stream.

   Linux  pools  randomness  for  distribution  by  the  /dev/random   and
   /dev/urandom  device interfaces. The standard mechanisms of filling the
   /dev/random pool may not be sufficient to meet demand on  systems  with
   high needs or limited user interaction. In those circumstances, haveged
   may be run as a privileged daemon to fill the /dev/random pool whenever
   the supply of random bits in /dev/random falls below the low water mark
   of the device.

   haveged tunes itself to its environment and provides the same  built-in
   test suite for the output stream as used on certified hardware security
   devices. See NOTES below for further information.

OPTIONS

   -b nnn, --buffer=nnn
          Set collection buffer size to  nnn  KW.  Default  is  128KW  (or
          512KB).

   -d nnn, --data=nnn
          Set  data  cache  size to nnn KB. Default is 16 or as determined
          dynamically.

   -f file, --file=file
          Set output file path for non-daemon use.  Default  is  "sample",
          use "-" for stdout.

   -F , --Foreground
          Run daemon in foreground. Do not fork and detach.

   -i nnn, --inst=nnn
          Set  instruction  cache  size  to  nnn  KB.  Default is 16 or as
          determined dynamically.

   -n nnn, --number=nnn
          Set number of bytes written to the output file. The value may be
          specified  using  one  of  the suffixes k, m, g, or t. The upper
          bound of this value is "16t" (2^44 Bytes = 16TB).  A value of  0
          indicates  unbounded  output  and  forces output to stdout. This
          argument is required if the daemon interface is not present.  If
          the  daemon  interface is present, this setting takes precedence
          over any --run value.

   -o <spec>, --onlinetest=<spec>
          Specify online tests to run. The  <spec>  consists  of  optional
          "t"ot   and   "c"ontinuous  groups,  each  group  indicates  the
          procedures  to  be  run,  using  "a<n>"  to  indicate  a  AIS-31
          procedure  A  variant, and "b" to indicate AIS procedure B.  The
          specifications are order independent (procedure  B  always  runs
          first  in  each group) and case insensitive. The a<n> variations
          exist to mitigate  the  a  slow  autocorrelation  test  (test5).
          Normally  all  procedure  A tests, except the first are iterated
          257 times.  An  a<n>  option  indicates  test5  should  only  be
          executed  every  modulo  <n>  times  during  the procedure's 257
          repetitions. The effect is so noticeable that A8  is  the  usual
          choice.

          The  "tot"  tests  run  only  at  initialization  - there are no
          negative performance consequences except for a  slight  increase
          in  the  time required to initialize.  The "tot" tests guarantee
          haveged  has  initialized  properly.  The  use  of   both   test
          procedures  in  the "tot" test is highly recommended because the
          two test emphasize different aspects of RNG quality.

          In continuous testing, the test sequence is  cycled  repeatedly.
          For  example,  the  string  "tbca8b"  (suitable for an AIS NTG.1
          device) would run procedure B for the  "tot"  test,  then  cycle
          between  procedure  A8  and  procedure  B  continuously  for all
          further output. Continuous  testing  does  not  come  for  free,
          impacting  both  throughput  and resource consumption. Continual
          testing also opens up the  possibility  of  a  test  failure.  A
          strict retry procedure recovers from spurious failure in all but
          the most extreme circumstances. When the retry fails,  operation
          will  terminate unless a "w" has been appended to the test token
          to make the test advisory only. In our example above, the string
          "tbca8wbw"  would  make  all continuous tests advisory. For more
          detailed information on AIS retries see NOTES below.

          Complete control over the test  configuration  is  provided  for
          flexibility. The defaults (ta8bcb" if run as a daemon and "ta8b"
          otherwise) are suitable for most circumstances.

   -p file, --pidfile=file
          Set  file  path  for   the   daemon   pid   file.   Default   is
          "/var/run/haveged.pid",

   -r n, --run=n
          Set run level for daemon interface:

          n  =  0 Run as daemon - must be root. Fills /dev/random when the
          supply of random bits
           falls below the low water mark of the device.

          n = 1 Display configuration info and terminate.

          n > 1 Write <n> kb of output. Deprecated (use --number instead),
          only provided for backward compatibility.

          If  --number  is  specified,  values other than 0,1 are ignored.
          Default is 0.

   -v n, --verbose=n
          Set diagnostic bitmap as sum of following options:

          1=Show build/tuning summary on termination, summary  for  online
          test retries.

          2=Show online test retry details

          4=Show timing for collections

          8=Show collection loop layout

          16=Show collection loop code offsets

          32=Show all online test completion detail

          Default is 0. Use -1 for all diagnostics.

   -w nnn, --write=nnn
          Set  write_wakeup_threshold  of  daemon  interface  to nnn bits.
          Applies only to run level 0.

   -?, --help
          This summary of program options.

NOTES

   haveged tunes the HAVEGE algorithm for maximum  effectiveness  using  a
   hierarchy  of  defaults,  command  line  options,  virtual  file system
   information,  and  cpuid  information  where  available.   Under   most
   circumstances, user input is not required for excellent results.

   Run-time  testing  provides assurance of correct haveged operation. The
   run-time test suite is modeled upon the  AIS-31  specification  of  the
   German  Common  Criteria  body,  BIS.  This  specification is typically
   applied  to  hardware  devices,  requiring  formal  certification   and
   mandated  start-up  and continuous operational testing. Because haveged
   runs on many different hardware platforms, certification  cannot  be  a
   goal,  but  the  AIS-31 test suite provides the means to assess haveged
   output with the same operational tests applied  to  certified  hardware
   devices.

   AIS  test  procedure  A  performs  6  tests  to check for statistically
   inconspicuous behavior. AIS test procedure B performs more  theoretical
   tests  such  as checking multi-step transition probabilities and making
   an empirical entropy estimate.  Procedure A is the much  more  resource
   and  compute  intensive  of  the  two  but is still recommended for the
   haveged start-up tests. Procedure B is well suited to use of haveged as
   a  daemon  because  the  test  entropy  estimate  confirms  the entropy
   estimate haveged uses when adding entropy to the /dev/random device.

   No test is perfect.  There  is  a  10e-4  probability  that  a  perfect
   generator  will  fail  either of the test procedures. AIS-31 mandates a
   strict retry policy to filter out false alarms and haveged always  logs
   test  procedure  failures.  Retries  are  expected  but rarely observed
   except when large data sets are generated with continuous testing.  See
   the libhavege(3) notes for more detailed information.

FILES

   If running as a daemon, access to the following files is required

          /dev/random

          /proc/sys/kernel/osrelease

          /proc/sys/kernel/random/poolsize

          /proc/sys/kernel/random/write_wakeup_threshold

DIAGNOSTICS

   Haveged  returns  0  for  success and non-zero for failure. The failure
   return code is 1 "general failure" unless execution  is  terminated  by
   signal  <n>,  in  which  case  the  return  code will be 128 + <n>. The
   following diagnostics are issued to stderr upon non-zero termination:

   Cannot fork into the background
          Call to daemon(3) failed.

   Cannot open file <s> for writing.
          Could not open sample file <s> for writing.

   Cannot write data in file:
          Could not write data to the sample file.

   Couldn't get pool size.
          Unable to read /proc/sys/kernel/random/poolsize

   Couldn't initialize HAVEGE rng
          Invalid data or instruction cache size.

   Couldn't open PID file <s> for writing
          Unable to write daemon PID

   Couldn't open random device
          Could not open /dev/random for read-write.

   Couldn't query entropy-level from kernel: error
          Call to ioctl(2) failed.

   Couldn't open PID file <path> for writing
          Error writing /var/run/haveged.pid

   Fail:set_watermark()
          Unable                to                write                 to
          /proc/sys/kernel/random/write_wakeup_threshold

   RNDADDENTROPY failed!
          Call to ioctl(2) to add entropy failed

   RNG failed
          The  random  number  generator failed self-test or encountered a
          fatal error.

   Select error
          Call to select(2) failed.

   Stopping due to signal <n>
          Signal <n> caught.

   Unable to setup online tests
          Memory unavailable for online test resources.

EXAMPLES

   Write 1.5MB of random data to the file /tmp/random
          haveged -n 1.5M -f /tmp/random

   Generate a /tmp/keyfile for disk encryption with LUKS
          haveged -n 2048 -f /tmp/keyfile

   Overwrite partition /dev/sda1 with random data. Be careful, all data on
   the partition will be lost!
          haveged -n 0 | dd of=/dev/sda1

   Generate random ASCII passwords of the length 16 characters
          (haveged -n 1000 -f - 2>/dev/null | tr -cd '[:graph:]' | fold -w
          16 && echo ) | head

   Write endless stream of random bytes to the pipe. Utility  pv  measures
   the speed by which data are written to the pipe.
          haveged -n 0 | pv > /dev/null

   Evaluate speed of haveged to generate 1GB of random data
          haveged -n 1g -f - | dd of=/dev/null

   Create  a  random key file containing 65 random keys for the encryption
   program aespipe.
          haveged -n 3705 -f - 2>/dev/null | uuencode -m - | head -n 66  |
          tail -n 65

   Test the randomness of the generated data with dieharder test suite
          haveged -n 0 | dieharder -g 200 -a

   Generate 16k of data, testing with procedure A and B with detailed test
   results. No c result seen because a single buffer fill did not  contain
   enough data to complete the test.
          haveged -n 16k -o tba8ca8 -v 33

   Generate  16k  of  data  as  above  with  larger buffer. The c test now
   completes - enough data now generated to complete the test.
          haveged -n 16k -o tba8ca8 -v 33 -b 512

   Generate 16m of data as above, observe many  c  test  completions  with
   default buffer size.
          haveged -n 16m -o tba8ca8 -v 33

   Generate   large   amounts   of  data  -  in  this  case  16TB.  Enable
   initialization test but made continuous tests advisory only to avoid  a
   possible  situation  that  program will terminate because of procedureB
   failing two times in a row. The probability of procedureB to  fail  two
   times  in  a row can be estimated as <TB to generate>/3000 which yields
   0.5% for 16TB.
          haveged -n 16T -o tba8cbw -f - | pv > /dev/null

   Generate large amounts of data (16TB). Disable continuous tests for the
   maximum throughput but run the online tests at the startup to make sure
   that generator for properly initialized:
          haveged -n 16T -o tba8c -f - | pv > /dev/null

SEE ALSO

   libhavege(3),
          cryptsetup(8), aespipe(1), pv(1), openssl(1), uuencode(1)

REFERENCES

   HArdware  Volatile  Entropy   Gathering   and   Expansion:   generating
   unpredictable  random  numbers at user level by A. Seznec, N. Sendrier,
   INRIA Research Report, RR-4592, October 2002

   A proposal for: Functionality classes for random number  generators  by
   W.  Killmann and W. Schindler, version 2.0, Bundesamt fur Sicherheit in
   der Informationstechnik (BSI), September, 2011

   A Statistical Test Suite for the Validation of Random NUmber Generators
   and  Pseudorandom  Number  Generators  for  Cryptographic Applications,
   special publication  SP800-22,  National  Institute  of  Standards  and
   Technology, revised April, 2010

   Additional      information      can      also      be     found     at
   http://www.issihosts.com/haveged/

AUTHORS

   Gary Wuertz <gary@issiweb.com> and Jirka Hladky <hladky jiri  AT  gmail
   DOT com>





Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.





Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.


Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.





Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.


Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.





Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.


Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.