haveged(category31-clients.html) - phpMan

haveged(8)              SYSTEM ADMINISTRATION COMMANDS              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).
       -c cmd, --command=cmd
              Switch  to command mode and send a command to an already running
              haveged process or daemon.  Currently the only knows command  is
              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 deter-
              mined 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 proce-
              dures to be run, using "a<n>" to indicate a AIS-31  procedure  A
              variant,  and  "b"  to indicate AIS procedure B.  The specifica-
              tions 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  nega-
              tive  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 proce-
              dures 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  fur-
              ther  output. Continuous testing does not come for free, impact-
              ing 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 ter-
              minate 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 infor-
       mation,  and  cpuid  information  where  available.  Under most circum-
       stances, 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 man-
       dated 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 incon-
       spicuous 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  dae-
       mon  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 genera-
       tor  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 fol-
       lowing 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_thresh-
              old
       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 com-
       pletes - 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 initializa-
       tion 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  unpre-
       dictable  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, spe-
       cial publication SP800-22, National Institute of Standards and Technol-
       ogy, revised April, 2010
       Additional   information   can   also   be  found  at  http://www.issi-
       hosts.com/haveged/

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

version 1.9                    February 10, 2014                    haveged(8)