Provided by: haveged_1.9.14-1ubuntu1_amd64 bug

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).

       -c cmd, --command=cmd
              Switch to command mode and send a command to an already running haveged process  or
              daemon.   Currently  the  only  known  commands  are  close  to  close  the current
              communication socket of the running haveged  process  as  well  as  root=<new_root>
              where  <new_root>  is  a  place  holder for the path of the real new root directory
              which should provide a haveged installation. The haveged  process  or  daemon  will
              perform a chroot(2) system call followed by a execv(3) to become rebased within the
              new root directory.

       -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>