diff options
author | Ulf Möller <ulf@openssl.org> | 2000-01-21 17:50:27 +0000 |
---|---|---|
committer | Ulf Möller <ulf@openssl.org> | 2000-01-21 17:50:27 +0000 |
commit | 60b5245360a70f4b10a6c77aa0bf5ee04b2e7262 (patch) | |
tree | 2de908febe44ee615faf54ddd405e163d72c3f63 /doc/crypto/RAND_add.pod | |
parent | 5d82c5b3f425b13d9e75db8b21db92a8cf22159b (diff) |
Document RAND library.
Diffstat (limited to 'doc/crypto/RAND_add.pod')
-rw-r--r-- | doc/crypto/RAND_add.pod | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/doc/crypto/RAND_add.pod b/doc/crypto/RAND_add.pod new file mode 100644 index 0000000000..fe53919801 --- /dev/null +++ b/doc/crypto/RAND_add.pod @@ -0,0 +1,60 @@ +=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 |