GH367: Fix dsa keygen for too-short seed

[openssl.git] / doc / crypto / rand.pod

diff --git a/doc/crypto/rand.pod b/doc/crypto/rand.pod
index 96901f109e64e3cdbd461684c02ff063663ce378..25172d954d25d1ba1ef1e5f20b7f5693ce6ffb92 100644 (file)
--- a/doc/crypto/rand.pod
+++ b/doc/crypto/rand.pod
@@ -8,13 +8,14 @@ rand - pseudo-random number generator
 
  #include <openssl/rand.h>
 
+ int  RAND_set_rand_engine(ENGINE *engine);
+
  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);
- void RAND_screen(void);
 
  int  RAND_load_file(const char *file, long max_bytes);
  int  RAND_write_file(const char *file);
@@ -22,14 +23,31 @@ rand - pseudo-random number generator
 
  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
@@ -37,11 +55,11 @@ need randomness.
 
 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)|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
+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.
 
-L<RAND_bytes(3)|RAND_bytes(3)> describes how to obtain random data from the
+L<RAND_bytes(3)> describes how to obtain random data from the
 PRNG. 
 
 =head1 INTERNALS
@@ -144,14 +162,14 @@ 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(3)|RAND_add(3)>).
+L<RAND_add(3)>).
 
 =head1 SEE ALSO
 
-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)> 
+L<BN_rand(3)>, L<RAND_add(3)>,
+L<RAND_load_file(3)>, L<RAND_egd(3)>,
+L<RAND_bytes(3)>,
+L<RAND_set_rand_method(3)>,
+L<RAND_cleanup(3)> 
 
 =cut