rng-tools, unofficial Debian fork
=================================

NOTICE:
This is an unofficial version of rng-tools with a lot of added functionality
and bugs, for which I assume total blame.  Don't bother rng-tools upstream
with problems you find in this version of rng-tools.

rng-tools unofficial-mt is a living reminder to myself to not modify upstream
code without sending the changes upstream at every step.  Suddenly, you have a
mass of changes too big to send upstream, and yet you find yourself without the
energy to break them into smallish patches to submit upstream (i.e. to
"unfork").  -- Henrique de Moraes Holschuh <hmh@hmh.eng.br>

Most users should install the Debian package rng-tools5 instead.

rng-tools originally was developed as part of the gkernel project:
‣ https://sourceforge.net/p/gkernel/
rng-tools5 now lives at: https://github.com/nhorman/rng-tools


rngd is a daemon that runs conditioning tests (from FIPS 140-2, edition of
2002-10-10) on a source of random data, and if that data passes the FIPS test,
feeds it back as trusted entropy to the in-kernel entropy pool.  Thus, it
increases the amount of true random data the kernel has available.

If the kernel runs out of entropy, reading from /dev/random will block, and all
network activity that needs random numbers (such as TCP/IP) will halt until the
kernel manages to get a bit more of entropy.

See the rngd(8) manpage for more information.

FIPS 140-1 is available at
http://csrc.nist.gov/cryptval/140-1.htm

FIPS 140-2 is available at
http://csrc.nist.gov/cryptval/140-2.htm
for the curious.

It was designed to be the user-space companion to the i810_rng and hw_random
drivers of the linux kernel, but it will work with anything that outputs random
bytes to a device or named pipe/fifo.

/dev/hwrng is a character device, major 10, minor 183 for the usual Linux
hardware RNG drivers, and that's what rng-tools expect to read from by default.

If the RNG is not generating random output (as verified by FIPS 140-2, that
is), rngd will log errors, and will NOT touch the kernel entropy pool, so no
lasting harm will be done (other than wasting CPU time).  If too many errors
happen, rngd will exit.

If you want to feed rngd from a big file containing TRNG data, you must take
steps to never use twice the same random data as input for rngd.

rngtest allows one to test the hw_random device directly, and should be run
only with rngd stopped.


The rngd init scripts do not start it if /dev/hwrng is autodetected
-------------------------------------------------------------------

In recent Linux kernel versions (at least going back to 5.10 in
Debian bullseye, if not much further to 4.x or more), the Linux
kernel’s hwrng framework automatically polls the active generator
(chosen by HRNGSELECT from /etc/default/rng-tools-debian) out of
those registred with the hwrng framework; therefore, there’s no
need to also run rngd (the entropy pool shrank to a mere 32 bytes
anyway). Autoprobing now checks /dev/hwrng last, and if it was
found, the init scripts just silently do not start rngd. If the
/etc/default/rng-tools-debian file sets HRNGDEVICE=/dev/hwrng then
autoprobing is not used and rngd still starts as usual.

To obtain options for hwrng, load all modules, then cat
/sys/devices/virtual/misc/hw_random/rng_available and check if
there’s no (or the sysfs node does not even exist), one or more
than one line in that node. The ./rng_current node is used, via
HRNGSELECT, to select the active device. The active device is both
the one auto-polled and the one behind /dev/hwrng, so if you have
multiple devices, you’ll have to find a device node DIFFERENT FROM
/dev/hwrng that is connected to the other generator(s) and run rngd
on that node / these nodes (in which case, one each) or a different
driver (in rngd).

Note that the reduced-to-32-bytes-RNG-state random subsystem adds
entropy to the pool at most once a minute once seeded, so writing
more than about 32 bytes a minute is not usually useful, unless -H
(--rng-entropy=) is smallish. -W/--fill-watermark= is also useless
with those kernels and -t/--feed-interval= plus -s/--random-step=
basically fullily determine what rngd feeds to the kernel pool.


FAQ
---

* Q: "I don't have a /dev/hwrng, and I am NOT using udev or devfs.
     How do I get one?"
  A: mknod /dev/hwrng c 10 183

* Q: "I don't have a /dev/hwrng, and I AM using devfs or udev.  How do I
     get one?"
  A: You should have a /dev/misc/hw_random device, IF the kernel driver has
     loaded properly.  The initscript should notice this and use this alternate
     location.

* Q: "can't open RNG file /dev/hwrng: No such device.
      error reading from entropy source:: No such device
      rngtest: error reading input: No such device
      What does that mean?"
  A: The hw_random device is missing from the kernel (or disabled, maybe
     because it couldn't detect a TRNG), the hw_random module failed to
     install, or /dev/hwrng has the wrong major/minor numbers.

     You might need to set HRNGSELECT in /etc/default/rng-tools-debian
     and/or load some kernel modules first. Ideally, place kernel modules
     into /etc/initramfs-tools/modules so the RNG device will come up
     early enough during boot for rng-tools-debian to see it’s working.

* Q: "I have an Intel TRNG (my chipset is a i8xx, after all), but
     rngd logs a lot of errors to syslog.  What is happening?"
  A: Sorry, but you DON'T have a working TRNG.  Refer to the "testing rngd"
     section for more details.

* Q: "I can't get the Intel TRNG to work, but I have a TPM.  Can I use it?"
  A: Yes, first enable the tpm-rng module: (as root)
	modprobe tpm-rng && echo tpm-rng >>/etc/modules
	# or /etc/initramfs-tools/modules
     Then uncomment the corresponding line (RNGDOPTIONS) in
     /etc/default/rng-tools-debian and (re‑)start the service.

* Q: "I see no errors anywhere, but rngd doesn't appear to be working.  Why?"
  A: See the "testing rngd" section for details.

* Q: "How good are the FIPS tests?"
  A: Good enough to detect a failing TRNG, but not good enough to detect a
     TRNG that is not cryptographically strong for other reasons.
     I suppose this is the reason for these tests being removed from the
     newest FIPS editions.

* Q: "I start rngd manually, how can I prevent the automatic start?"
  A: Your usual disable mechanisms, for example:
     $ sudo /usr/sbin/update-rc.d -f rng-tools-debian remove


Testing rngd
------------

rngtest will be of great help for testing hw_random and /dev/[u]random.  Read
its manpage rngtest(1) for details.  You may want to use rngtest -b n or -t n
if your TRNG is slow.

With rngd stopped (and as root), do:
  rngtest -c 1 </dev/hwrng

If you get no output in a small while, hit ^C (or send a TERM signal using
kill) to interrupt rngtest.  If rngtest output states that it hasn't received
any bits from the TRNG, then either your TRNG is not working, it is not
supported, or the kernel driver is broken.  rngd will _not_ work.

If rngtest reports that one of the FIPS tests failed, try it again with more
blocks:
  rngtest -c 50 </dev/hwrng

If more than a few blocks fail, your TRNG isn't working right, and there is
nothing that rng-tools can do.  It is probably unsafe to use rngd.  In fact,
chances are you will see no FIPS errors at all with a good TRNG.

You can use rngtest to measure the available bandwidth and quality (as far
as FIPS tests can measure it) of /dev/random and /dev/urandom, too.

To test /dev/random, you must first make sure your machine is in a position to
survive losing all ability to generate real random numbers for a small while.
It is a good idea to unplug it from the network while the tests are running,
and to use something like rngtest -c 10 to get meaningful averages.

Running rngtest against /dev/random with rngd running should show a remarkable
improvement on /dev/random bandwidth over the measurements with rngd stopped.


The Intel Hardware RNG
----------------------

The Intel hardware TRNG is provided by the Intel FWH (82802AB or 82802AC)
_optional_ component of the 8xx chipsets.  This chip hosts the firmware (BIOS)
and the TRNG, and is directly connected to the LPC bus in the South Bridge.

It shows up as memory mapped by the South Bridge, and its presence is difficult
to detect.  Regardless, the kernel driver has difficulties detecting the FWH,
and is easily misled into believing there is an TRNG active, when in fact there
isn't even an Intel FWH in the mainboard.

Almost no one but Intel itself uses this component (its main use is to host the
system BIOS, which a cheaper Flash device without a RNG can also do just as
easily).  Intel Desktop Boards usually have a 82802AB FWH (if you are lucky and
Intel itself has not used something else on that particular manufacturing lot
of the board), and the TRNG in those is usually functional.  Intel Server
Boards usually do NOT have a 82802AB/AC FWH.

http://developer.intel.com/design/chipsets/rng/CRIwp.htm has interesting
documentation on how the RNG behaves.  An important point to know is that it
has a variable bit rate, and that its entropy (H) is better than 0.999.
An alternate URL for that document is
http://www.cryptography.com/resources/whitepapers/IntelRNG.pdf

Measurements on an Intel Desktop Board D875PBZ show that you can expect an
average of 24kbit/s of random data from the 2.4.24 kernel driver (documentation
suggests this should be on the order of 75kbit/s).  The kernel driver will eat
up a LOT of "system time", I hope this can be corrected in future versions of
the driver.

/dev/random output in the test system archived an average of 120kbit/s with
rngd active, probably due to the entropy accounting bugs in most 2.4 kernels.

The suggested rngd -H parameter for the Intel TRNG is 0.998.


The VIA Hardware RNG
--------------------

VIA has outdone everyone else with their TRNG.  It is implemented by the
"Padlock" engine in their "Nehemiah" CPU core, and it is *extremely fast*,
unlike Intel's.

An excellent site to keep an eye for enhanced support for VIA's
TRNG is: http://peertech.org/hardware/viarng/

A paper describing the Padlock engine is at:
http://www.cryptography.com/resources/whitepapers/VIA_rng.pdf

The suggested -H paremeter for the Padlock TRNG is 0.75 if the whitener is
disabled, or 0.98 if the withener is enabled.  You're strongly advised to run
the TRNG with the whitener enabled.

For safety reasons, rngd always use 0.75 for the VIA TRNG entropy by default.
It always enables the whitener, and it discards consecutive random bits from
the TRNG, because there is a measurable correlation among consecutive bits.
This means that rngd will be probably "slower" than other VIA TRNG drivers,
but it will be safer for cryptographic use.
