frandom: A fast random number generator as a kernel module for Linux.

This README file contains technical data about loading and using the module.
Regarding how this module works and other non-technical issues, please visit
the project's site at http://frandom.sourceforge.net.

For installation info: See the INSTALL file.

<----------------------------------------------------------------------------->

frandom vs. erandom
===================
Both frandom and erandom generate random data very fast, with the algorithm
that is used in the alledged RC4 cipher.

As pseudorandom random generators, these devices need an initial seed, from
which all "random" data is derived. It's important that this seed is different
every time a new random stream is started, or the same random sequence will
appear over and over again.

erandom and frandom differ in the seed used. frandom calls the kernel's random
generator for 256 bytes of random data, while erandom uses an internal random
generator to generate its own 256 bytes of seed. This internal random generator
is exactly like the one used to generate random data for each /dev/{f,e}random
stream. It is seeded when the module is initialized, using the kernel's random
generator.

/dev/erandom should be used when the random device file is opened often, and
the seeding directly from the kernel needs to be avoided. By using /dev/erandom
the kernel's random entropy is left untouched, so random data is generated
without interfering with other applications that may need kernel entropy.

/dev/frandom uses 256 bytes of kernel random data every time a device file is
opened, so if it's opened very frequently, kernel entropy may run out,
resulting in slower operation and possible degradation in other application's
security.

The self-seeding used in /dev/erandom promises less randomality than
/dev/frandom, and both generators are probably "less random" than the kernel's
native random generators. Having said that, it's reasonable to assume that no
empiric statistical analysis will ever be able prove these two generators as
less random than any other.

Seeding the global generator
============================

/dev/erandom and the sysctl interface are based upon a modulewise-global random
generator. This generator is seeded from the kernel's get_random_bytes(),
which is similar to /dev/urandom.

This seeding occurs once, when data is needed from this generator. A side
effect of this is, that if data is requested before the boot startup script
has seeded the /dev/{u}random, then the seeding of erandom will be based upon
a relatively non-random seed. Even though the practical impact of this is zero,
heavy paranoids may claim that the same erandom sequence can occur more than
(with a probability of a meteor hitting earth while you're chewing bubble gum).

A kernel message is given (KERN_INFO level) when the global generator is
seeded, saying "frandom: Seeded global generator now". By looking for this
message in /var/log/messages, one can determine if the seeding occured before
or after the /dev/{u}random generator was seeded.

Major and Minor
===============

By default, frandom takes hold of major 235 and minor 11. This is why
/dev/frandom should be created as

mknod /dev/frandom c 235 11

/dev/erandom occupies minor 12, and we create /dev/erandom as

mknod /dev/erandom c 235 12

(see the INSTALL file about this).

Should the major 235 be occupied by another device, the module will fail to
load ("Device or resource busy") with a descriptive error message in the
kernel log (usually /var/log/messages).
If this is the case, it's possible to assign another major/minor set for
frandom. For example, if we want major 250 and minor 1, we set a couple of
module parameters:

insmod frandom frandom_major=250 frandom_minor=1
mknod /dev/frandom c 250 1

Chunk size
==========

On 2.6-like kernels, everything said in this clause is irrelevant, and there
is no reason whatsoever to relate to this subject.

When a read() call is made, frandom creates the entire chunk of random data
without allowing rescheduling to another process. This does *not* mean that
interrupts are inhibited, but that other processes are kept sleeping.

If the read() call demands a huge buffer (say, 1 MB) this may take enough
time to make other processes to lag behind. If real-time response is needed,
and the processor is not so fast, it may be undesired behaviour.

Solution: Limit the maximal allowed chunk. read() calls which require more
data will get only this much (applications using read() should always expect
to get less than they asked for).

So if we want to limit the maximal chunk to 16kB, we go:

insmod frandom frandom_chunklimit=16384

Note that when using this limitation, the "dd" utility may behave unlike most
of us expect: After setting frandom_chunklimit as above,

dd if=/dev/frandom of=junk bs=1M count=1

will create a file of size 16kB only, instead of what some would expect -- 1MB.
No warning will be issued.

The kernel parameter's default is 0, which means no limit. The minimal value
is 256 (bytes).

Internal buffer size
====================

The kernel parameter frandom_bufsize is the number of bytes in the internal
buffer. This buffer is where the random data is initially written to, and
copied from (with copy_to_user() ) as data is generated.

It defaults to its minimum, 256. Setting it to a higher value has a zero
impact performance, and is a waste of kernel memory.
