Document RAND library.

#endif

	/*

	 * (Based on doc/ssleay.txt, section rand.doc:)

	 * (Based on the rand(3) manpage)

	 *

	 * The input is chopped up into units of 16 bytes (or less for

	 * the last block).  Each of these blocks is run through the MD5

	 * message digest as follow:  The data passed to the MD5 digest

	 * the last block).  Each of these blocks is run through the hash

	 * function as follow:  The data passed to the hash function

	 * is the current 'md', the same number of bytes from the 'state'

	 * (the location determined by in incremented looping index) as

	 * the current 'block', the new key data 'block', and 'count'

	 * (which is incremented after each use).

	 * The result of this is kept in 'md' and also xored into the

	 * 'state' at the same locations that were used as input into the MD5.

	 * 'state' at the same locations that were used as input into the

         * hash function.

	 */

	CRYPTO_w_lock(CRYPTO_LOCK_RAND);

	i=stat(file,&sb);

	/* If the state fails, put some crap in anyway */

	RAND_add(&sb,sizeof(sb),0);

	ret+=sizeof(sb);

	if (i < 0) return(0);

	if (bytes <= 0) return(ret);

=pod

=head1 NAME

RAND_add, RAND_seed, RAND_screen - Add entropy to the PRNG

=head1 SYNOPSIS

 #include <openssl/rand.h>

 void RAND_seed(const void *buf, int num);

 void RAND_add(const void *buf, int num, int entropy);

 void RAND_screen(void);

=head1 DESCRIPTION

RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. Thus,

if the data at B<buf> are unpredictable to an adversary, this

increases the uncertainty about the state and makes the PRNG output

less predictable. Suitable input comes from user interaction (random

key presses, mouse movements) and certain hardware events. The

B<entropy> argument is (the lower bound of) an estimate of how much

randomness is contained in B<buf>. Details about sources of randomness

and how to estimate their entropy can be found in the literature,

e.g. RFC 1750.

RAND_add() may be called with sensitive data such as user entered

passwords. The seed values cannot be recovered from the PRNG output.

OpenSSL makes sure that the PRNG state is unique for each thread. On

systems that provide C</dev/random>, the randomness device is used

to seed the PRNG transparently. However, on all other systems, the

application is responsible for seeding the PRNG by calling RAND_add()

or RAND_load_file(3).

RAND_seed() is equivalent to RAND_add() when B<num == entropy>.

The RAND_screen() function is available for the convenience of Windows

programmers. It adds the current contents of the screen to the PRNG.

For applications that can catch Windows events, seeding the PRNG with

the parameters of B<WM_MOUSEMOVE> events is a significantly better

source of randomness. It should be noted that both methods cannot be

used on servers that run without user interaction.

=head1 RETURN VALUES

These functions do not return values.

=head1 SEE ALSO

rand(3), RAND_load_file(3), RAND_cleanup(3)

=head1 HISTORY

RAND_seed() and RAND_screen() are available in all versions of SSLeay

and OpenSSL. RAND_add() was added in OpenSSL 0.9.5.

=cut

=pod

=head1 NAME

RAND_bytes, RAND_pseudo_bytes - Generate random data

=head1 SYNOPSIS

 #include <openssl/rand.h>

 int RAND_bytes(unsigned char *buf, int num);

 int RAND_pseudo_bytes(unsigned char *buf, int num);

=head1 DESCRIPTION

RAND_bytes() puts B<num> random bytes into B<buf>. An error occurs if

the PRNG has not been seeded with enough randomness.

RAND_pseudo_bytes() puts B<num> pseudo-random bytes into B<buf>. These

bytes are guaranteed to be unique, but not unpredictable. They can be

used for non-cryptographic purposes and for certain purposes in

cryptographic protocols, but not for key generation etc.

=head1 RETURN VALUES

RAND_bytes() returns 1 on success, 0 otherwise. The error code can be

obtained by ERR_get_error(3). RAND_pseudo_bytes() returns 1 if the

bytes generated are cryptographically strong, 0 otherwise. Both

functions return -1 if they are not supported by the current RAND

method.

=head1 SEE ALSO

rand(3), err(3), RAND_add(3)

=head1 HISTORY

RAND_bytes() is available in all versions of SSLeay and OpenSSL.  It

has a return value since OpenSSL 0.9.5. RAND_pseudo_bytes() was added

in OpenSSL 0.9.5.

=cut

=pod

=head1 NAME

RAND_cleanup - erase the PRNG state

=head1 SYNOPSIS

 #include <openssl/rand.h>

 void RAND_cleanup(void);

=head1 DESCRIPTION

RAND_cleanup() erases the memory used by the PRNG.

=head1 RETURN VALUE

RAND_cleanup() returns no value.

=head1 SEE ALSO

rand(3)

=head1 HISTORY

RAND_cleanup() is available in all versions of SSLeay and OpenSSL.

=cut