rngd.8.in

.\" Copyright (C) 2017 - Neil Horman <nhorman@tuxdriver.com>
.\"
.TH RNGD 8 "March 2001" "@PACKAGE@ @VERSION@"

.SH NAME
rngd \- Check and feed random data from hardware device to kernel random device

.SH SYNOPSIS
.B rngd
[\fB\-b\fR, \fB\-\-background\fR]
[\fB\-f\fR, \fB\-\-foreground\fR]
[\fB\-d\fR, \fB\-\-debug\fR]
[\fB\-l\fR, \fB\-\-list\fR]
[\fB\-x\fR, \fB\-\-exclude\fR]
[\fB\-n\fR, \fB\-\-include\fR]
[\fB\-O\fR, \fB\-\-option\fR]
[\fB\-i\fR, \fB\-\-ignorefail\fR]
[\fB\-o\fR, \fB\-\-random-device=\fIfile\fR]
[\fB\-p\fR, \fB\-\-pid-file=\fIfile\fR]
[\fB\-r\fR, \fB\-\-rng-device=\fIfile\fR]
[\fB\-s\fR, \fB\-\-random-step=\fInnn\fR]
[\fB\-t\fR, \fB\-\-test\fR]
[\fB\-W\fR, \fB\-\-fill-watermark=\fInnn\fR]
[\fB\-R\fR, \fB\-\-force_reseed=\fInnn\fR]
[\fB\-q\fR, \fB\-\-quiet\fR]
[\fB\-?\fR, \fB\-\-help\fR]
[\fB\-V\fR, \fB\-\-version\fR]
.RI

.SH DESCRIPTION
This daemon feeds data from a random number generator to the kernel's
random number entropy pool, after first checking the data to ensure that
it is properly random.
.PP
The \fB\-f\fR or \fB\-\-foreground\fR options can be used to tell
\fBrngd\fR to avoid forking on startup.  This is typically used for
debugging.  The \fB\-b\fR or \fB\-\-background\fR options, which fork and put
\fBrngd\fR into the background automatically, are the default.
.PP
The \fB\-r\fR or \fB\-\-rng-device\fR options can be used to select an
alternate source of input, besides the default /dev/hwrng.
The \fB\-o\fR or \fB\-\-random-device\fR options can be used to select
an alternate entropy output device, besides the default /dev/random.
Note that this device must support the Linux kernel /dev/random 
ioctl API.
.PP

.SH OPTIONS
.TP
\fB\-b\fR, \fB\-\-background\fR
Become a daemon (default)
.TP
\fB\-f\fR, \fB\-\-foreground\fR
Do not fork and become a daemon
.TP
\fB\-d\fR, \fB\-\-debug\fR
Enable debug messages
.TP
\fB\-l\fR, \fB\-\-list\fR
List the indexes and names of available entropy sources. Exit code when listing
sources is 0 if at least 1 entropy source was found and initialized, 1
otherwise.
.TP
\fB\-x\fR, \fB\-\-exclude\fR
Disable entropy sources based on index or (shortname) reported from --list option
.TP
\fB\-n\fR, \fB\-\-include\fR
Enable entropy sources based on index or (shortname) reported from --list option
.TP
\fB\-O\fR, \fB\-\-option\fR
Provide specific config options to individual entropy sources, in the format
--option [index|shortname]:key:value.  See Entropy Sources section below for indices and
source specific options.  Note that specifying \fB-O [<index>|<shortname>]\fR will print the
available options for that index to the console
.TP
\fB\-p\fI file\fR, \fB\-\-pid-file=\fIfile\fR
File used for recording daemon PID, and multiple exclusion
(default: /var/run/rngd.pid)
.TP
\fB\-i\fR, \fB\-\-ignorefail\fR
Ignore repeated fips failures
.TP
\fB\-o\fI file\fR, \fB\-\-random-device=\fIfile\fR
Kernel device used for random number output
(default: /dev/random)
.TP
\fB\-r\fI file\fR, \fB\-\-rng-device=\fIfile\fR
Kernel device used for random number input
(default: /dev/hwrng)
.TP
\fB\-s\fI nnn\fR, \fB\-\-random-step=\fInnn\fR
Number of bytes written to random-device at a time (default: 64)
.TP
\fB\-t, \fB\-\-test\fR
Enter test mode.  In this mode (which implies -f), all generated entropy is
discarded and rngd reports the amount of entropy generated every second
.TP
\fB\-e\fI nnn\fR, \fB\-\-entropy-count=\fInnn\fR
Number of bits to consider random when adding entropy. 1<=e<=8
(default: 8)
.TP
\fB\-W\fI n\fR, \fB\-\-fill\-watermark=\fInnn\fR
Once we start doing it, feed entropy to \fIrandom-device\fR until at least
\fIfill-watermark\fR bits of entropy are available in its entropy pool.
By default, this value is set to 75% of the entropy pool size or 2048 bits
if the entropy pool size couldn't be determined.
Setting this too high will cause \fIrngd\fR to dominate the contents of the
entropy pool.  Low values will hurt system performance during entropy 
starves.  Do not set \fIfill-watermark\fR above the size of the
entropy pool (usually 4096 bits).  A value of 0 to this option will cause no
watermark to be set.
.TP
\fB\-R\fI n\fR, \fB\-\-force_reseed=\fInnn\fR
For newer kernels which support non-blocking entropy pools, it is still
beneficial to periodically add fresh entropy as a reseeding event.
--force_reseed defines the number of seconds between which fresh entropy is
added to the kernel entropy pool.  Defaults to 5 minutes.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
Suppress all messages
.TP
\fB\-?\fR, \fB\-\-help\fR
Give a short summary of all program options.
.TP
\fB\-V\fR, \fB\-\-version\fR
Print program version

.SH
ENTROPY SOURCES
.TP
.B
Hardware RNG (hwrng) [Index 0]
The Hardware RNG is a generic entropy source that draws entropy from a hardware
rng attached by default to /dev/hwrng

.TP
.B
TPM (tpm) [Index 1]
Entropy drawn from on board TPM device.  Note this entropy source is deprecated
and will be removed soon, as newer tpm devices export entropy via /dev/hwrng,
which is collected by the hwrng source above

.TP
.B
RDRAND/RDSEED (rdrand) [Index 2]
Entropy drawn from the RDRAND and RDSEED instructions (x86 only)
.TP
Options

\fBuse_aes - \fR select if rdrand is used to seed a cprng to produce entropy, or
if all entropy is drawn directly from rdrand instruction (default 0)

.TP
.B
DARN (darn) [Index 3]
Entropy drawn from the DARN instruction (ppc64 only)
.TP
Options

\fBuse_aes - \fR select if the power darn instruction is used to directly fill
the entropy poll, or if it is used as a periodic seed to an aes based cprng
(default 1)

.TP
.B
NIST Entropy Beacon (nist) [Index 4]
Entropy gathered from the NIST network entropy beacon.  Note that this entropy
source is disabled by default as it should never be used for cryptographic
purposes, or any use case in which random data should be known only by a single
entity.

.TP
.B
JITTER (jitter) [Index 5]
Entropy gathered by measuring timing variance of operations on the local cpu
.TP
Options
\fBthread_count - \fR Set the number of threads that the jitter entropy source will spawn

\fBbuffer_size - \fR Set the size of the buffer cache that each thread maintains 

\fBrefill_thresh - \fR Set the low watermark for the cache that triggers its corresponding thread to start refill operations 

\fBretry_count - \fR If all entropy buffers are empty, retry this many times before giving up.  Note that jitterentropy can take several seconds to refill a buffer, and so retries after a delay may be preferable to repeatedly spining on an empty buffer (default 1)

\fBretry_delay - \fR between each retry for retry_count above, sleep for this many seconds. May also be the special value -1, representing adaptive sleep, where each retry delay will be half the recorded execution time of the last entropy gathering round (default -1)

.TP
.B
PKCS11 (pkcs11) [Index 6]
Entropy gathered via the opensc openssl engine, which can extract entropy from
various smart card readers
.TP
Options
\fBengine_path - \fR Set the patch for the pkcs11 engine DSO to load

\fBchunk_size - \fR Some pkcs11 engines have restrictions on how much data can
be requested at a time, this option allows for the request to be subdivided into
smaller chunks to be satisfied

.TP
.B
RTLSDR (rtlsdr) [Index 7]
Entropy gathered via the rtl software defined radio library, which can gather
entropy using various usb software defined radios listening to random radio
static
.TP
Options
\fBdevid - \fR When multiple devices are available the integer index of the
device to use

\fBfreq_min - \fR The minimum frequence range to scan in

\fBfreq_max - \fR The maximum frequency range to scan in

\fBsample_min - \fR The minimum sample rate of the radio

\fBsample_max - \fR The maximum sample rate of the radio

.SH AUTHORS
Philipp Rumpf
.br
Jeff Garzik \- jgarzik@pobox.com
.br
Matt Sottek
.br
Brad Hill
.br
Neil Horman - nhorman@tuxdriver.com