=head1 NAME
-rand - Psdeudo-random number generator
+rand - pseudo-random number generator
=head1 SYNOPSIS
#include <openssl/rand.h>
- int RAND_bytes(unsigned char *buf,int num);
- int RAND_pseudo_bytes(unsigned char *buf,int num);
+ int RAND_set_rand_engine(ENGINE *engine);
- void RAND_seed(const void *buf,int num);
- void RAND_add(const void *buf,int num,int entropy);
- void RAND_screen(void);
+ int RAND_bytes(unsigned char *buf, int num);
+ int RAND_pseudo_bytes(unsigned char *buf, int num);
+
+ void RAND_seed(const void *buf, int num);
+ void RAND_add(const void *buf, int num, int entropy);
+ int RAND_status(void);
- int RAND_load_file(const char *file,long max_bytes);
+ int RAND_load_file(const char *file, long max_bytes);
int RAND_write_file(const char *file);
- char *RAND_file_name(char *file,int num);
+ const char *RAND_file_name(char *file, size_t num);
+
+ int RAND_egd(const char *path);
- void RAND_set_rand_method(RAND_METHOD *meth);
- RAND_METHOD *RAND_get_rand_method(void);
+ void RAND_set_rand_method(const RAND_METHOD *meth);
+ const RAND_METHOD *RAND_get_rand_method(void);
RAND_METHOD *RAND_SSLeay(void);
void RAND_cleanup(void);
+ /* For Win32 only */
+ void RAND_screen(void);
+ int RAND_event(UINT, WPARAM, LPARAM);
+
=head1 DESCRIPTION
+Since the introduction of the ENGINE API, the recommended way of controlling
+default implementations is by using the ENGINE API functions. The default
+B<RAND_METHOD>, as set by RAND_set_rand_method() and returned by
+RAND_get_rand_method(), is only used if no ENGINE has been set as the default
+"rand" implementation. Hence, these two functions are no longer the recommended
+way to control defaults.
+
+If an alternative B<RAND_METHOD> implementation is being used (either set
+directly or as provided by an ENGINE module), then it is entirely responsible
+for the generation and management of a cryptographically secure PRNG stream. The
+mechanisms described below relate solely to the software PRNG implementation
+built in to OpenSSL and used by default.
+
These functions implement a cryptographically secure pseudo-random
number generator (PRNG). It is used by other library functions for
example to generate random keys, and applications can use it when they
A cryptographic PRNG must be seeded with unpredictable data such as
mouse movements or keys pressed at random by the user. This is
-described in L<RAND_add(3)>. Its state can be saved in a seed file
-(see L<RAND_load_file(3)>) to avoid having to go through the seeding
-process whenever the application is started.
+described in L<RAND_add(3)|RAND_add(3)>. Its state can be saved in a seed file
+(see L<RAND_load_file(3)|RAND_load_file(3)>) to avoid having to go through the
+seeding process whenever the application is started.
-L<RAND_bytes(3)> describes how to obtain random data from the PRNG.
+L<RAND_bytes(3)|RAND_bytes(3)> describes how to obtain random data from the
+PRNG.
=head1 INTERNALS
The algorithm is as follows.
There is global state made up of a 1023 byte buffer (the 'state'), a
-working hash function ('md') and a counter ('count').
+working hash value ('md'), and a counter ('count').
Whenever seed data is added, it is inserted into the 'state' as
follows.
-The input is chopped up into units of 16 bytes (or less for the last
-block). Each of these blocks is run through the hash function. 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' and the new key data 'block'.
-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 hash function. I
+The input is chopped up into units of 20 bytes (or less for
+the last block). Each of these blocks is run through the hash
+function as follows: 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
+hash function. I
believe this system addresses points 1 (hash function; currently
SHA-1), 3 (the 'state'), 4 (via the 'md'), 5 (by the use of a hash
function and xor).
When bytes are extracted from the RNG, the following process is used.
-For each group of 8 bytes (or less), we do the following,
-
-Input into the hash function, the top 8 bytes from 'md', the byte that
-are to be overwritten by the random bytes and bytes from the 'state'
-(incrementing looping index). From this hash function output (which
-is kept in 'md'), the top (upto) 8 bytes are returned to the caller
-and the bottom (upto) 8 bytes are xored into the 'state'.
-
-Finally, after we have finished 'generation' random bytes for the
-called, 'count' (which is incremented) and 'md' are fed into the hash
-function and the results are kept in 'md'. I believe the above
-addressed points 1 (use of SHA-1), 6 (by hashing into the 'state' the
-'old' data from the caller that is about to be overwritten) and 7 (by
-not using the 8 bytes given to the caller to update the 'state', but
-they are used to update 'md').
+For each group of 10 bytes (or less), we do the following:
+
+Input into the hash function the local 'md' (which is initialized from
+the global 'md' before any bytes are generated), the bytes that are to
+be overwritten by the random bytes, and bytes from the 'state'
+(incrementing looping index). From this digest output (which is kept
+in 'md'), the top (up to) 10 bytes are returned to the caller and the
+bottom 10 bytes are xored into the 'state'.
+
+Finally, after we have finished 'num' random bytes for the caller,
+'count' (which is incremented) and the local and global 'md' are fed
+into the hash function and the results are kept in the global 'md'.
+
+I believe the above addressed points 1 (use of SHA-1), 6 (by hashing
+into the 'state' the 'old' data from the caller that is about to be
+overwritten) and 7 (by not using the 10 bytes given to the caller to
+update the 'state', but they are used to update 'md').
So of the points raised, only 2 is not addressed (but see
-L<RAND_add()>).
+L<RAND_add(3)|RAND_add(3)>).
=head1 SEE ALSO
-BN_rand(3), RAND_add(3), RAND_load_file(3), RAND_bytes(3),
-RAND_set_rand_method(3), RAND_cleanup(3)
+L<BN_rand(3)|BN_rand(3)>, L<RAND_add(3)|RAND_add(3)>,
+L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_egd(3)|RAND_egd(3)>,
+L<RAND_bytes(3)|RAND_bytes(3)>,
+L<RAND_set_rand_method(3)|RAND_set_rand_method(3)>,
+L<RAND_cleanup(3)|RAND_cleanup(3)>
=cut
projects / openssl.git / blobdiff