oracular (9) arc4rand.9freebsd.gz

NAME

     arc4rand, arc4random, random, read_random, read_random_uio, srandom — supply pseudo-random numbers

SYNOPSIS

     #include <sys/libkern.h>

     void
     srandom(u_long seed);

     u_long
     random(void);

     void
     arc4rand(void *ptr, u_int length, int reseed);

     uint32_t
     arc4random(void);

     #include <sys/random.h>

     int
     read_random(void *buffer, int count);

     int
     read_random_uio(struct uio *uio, bool nonblock);

DESCRIPTION

     The random() function will by default produce a sequence of numbers that can be duplicated by calling
     srandom() with some constant as the seed.  The srandom() function may be called with any arbitrary seed
     value to get slightly more unpredictable numbers.  It is important to remember that the random() function
     is entirely predictable, and is therefore not of use where knowledge of the sequence of numbers may be of
     benefit to an attacker.

     The arc4rand() function will return very good quality random numbers, better suited for security-related
     purposes.  The random numbers from arc4rand() are seeded from the entropy device if it is available.
     Automatic reseeds happen after a certain timeinterval and after a certain number of bytes have been
     delivered.  A forced reseed can be forced by passing a non-zero value in the reseed argument.

     The read_random() function is used to return entropy directly from the entropy device if it has been
     loaded.  If the entropy device is not loaded, then the buffer is ignored and zero is returned.  The buffer
     is filled with no more than count bytes.  It is strongly advised that read_random() is not used; instead
     use arc4rand() unless it is necessary to know that no entropy has been returned.

     The read_random_uio() function behaves identically to read(2) on /dev/random.  The uio argument points to a
     buffer where random data should be stored.  This function only returns data if the random device is seeded.
     It blocks if unseeded, except when the nonblock argument is true.

     All the bits returned by random(), arc4rand(), read_random(), and read_random_uio() are usable.  For
     example, ‘random()&01’ will produce a random binary value.

     The arc4random() is a convenience function which calls arc4rand() to return a 32 bit pseudo-random integer.

RETURN VALUES

     The random() function uses a non-linear additive feedback random number generator employing a default table
     of size 31 containing long integers to return successive pseudo-random numbers in the range from 0 to
     (2**31)−1.  The period of this random number generator is very large, approximately 16*((2**31)−1).

     The arc4rand() function uses the RC4 algorithm to generate successive pseudo-random bytes.  The
     arc4random() function uses arc4rand() to generate pseudo-random numbers in the range from 0 to (2**32)−1.

     The read_random() function returns the number of bytes placed in buffer.

     read_random_uio() returns zero when successful, otherwise an error code is returned.

ERRORS

     read_random_uio() may fail if:

     [EFAULT]           uio points to an invalid memory region.

     [EWOULDBLOCK]      The random device is unseeded and nonblock is true.

AUTHORS

     Dan Moschuk wrote arc4random().
     Mark R V Murray wrote read_random().