diff options
author | Rich Salz <rsalz@openssl.org> | 2017-07-07 16:47:39 -0400 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2017-07-07 23:53:54 -0400 |
commit | 04256277cb9dddedd77965f19107c6c3935e8b96 (patch) | |
tree | 3b0635241592576b172c7b6b1a69de5141108e20 | |
parent | 222417eb71a91f28381f5b3f93d7db690e8d92bf (diff) |
Update various RAND podpages
Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3883)
-rw-r--r-- | doc/man3/RAND_add.pod | 16 | ||||
-rw-r--r-- | doc/man3/RAND_cleanup.pod | 9 | ||||
-rw-r--r-- | doc/man3/RAND_egd.pod | 76 | ||||
-rw-r--r-- | doc/man3/RAND_load_file.pod | 4 | ||||
-rw-r--r-- | doc/man3/RAND_set_rand_method.pod | 45 |
5 files changed, 54 insertions, 96 deletions
diff --git a/doc/man3/RAND_add.pod b/doc/man3/RAND_add.pod index c62d1407e7..f5514f092e 100644 --- a/doc/man3/RAND_add.pod +++ b/doc/man3/RAND_add.pod @@ -35,15 +35,13 @@ can be found in the literature; for example IETF RFC 4086. 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/urandom>, 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(), -L<RAND_egd(3)> -or L<RAND_load_file(3)>. - RAND_seed() is equivalent to RAND_add() with B<randomness> set to B<num>. +On systems that provide C</dev/urandom> or similar source of randomess, +it will be used +to seed the PRNG transparently. On older systems, however, it might +be necessary to use RAND_add(), L<RAND_egd(3)> or L<RAND_load_file(3)>. + RAND_event() and RAND_screen() are deprecated and should not be called. =head1 RETURN VALUES @@ -65,11 +63,11 @@ RAND_event() and RAND_screen() are deprecated since OpenSSL =head1 SEE ALSO L<RAND_bytes(3)>, L<RAND_egd(3)>, -L<RAND_load_file(3)>, L<RAND_cleanup(3)> +L<RAND_load_file(3)> =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/RAND_cleanup.pod b/doc/man3/RAND_cleanup.pod index 31c90e71ed..90395d22a0 100644 --- a/doc/man3/RAND_cleanup.pod +++ b/doc/man3/RAND_cleanup.pod @@ -14,9 +14,10 @@ RAND_cleanup - erase the PRNG state =head1 DESCRIPTION -Prior to OpenSSL 1.1.0 RAND_cleanup() erases the memory used by the PRNG. This -function is deprecated and as of version 1.1.0 does nothing. No explicit -initialisation or de-initialisation is necessary. See L<OPENSSL_init_crypto(3)>. +Prior to OpenSSL 1.1.0, RAND_cleanup() released all resources used by +the PRNG. As of version 1.1.0, it does nothing and should not be called, +since since no explicit initialisation or de-initialisation is necessary. See +L<OPENSSL_init_crypto(3)>. =head1 RETURN VALUE @@ -32,7 +33,7 @@ RAND_cleanup() was deprecated in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/RAND_egd.pod b/doc/man3/RAND_egd.pod index 956362dff2..e2c7b3f0e1 100644 --- a/doc/man3/RAND_egd.pod +++ b/doc/man3/RAND_egd.pod @@ -8,76 +8,48 @@ RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon #include <openssl/rand.h> + int RAND_egd_bytes(const char *path, int num); int RAND_egd(const char *path); - int RAND_egd_bytes(const char *path, int bytes); - int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes); + int RAND_query_egd_bytes(const char *path, unsigned char *buf, int num); =head1 DESCRIPTION -RAND_egd() queries the Entropy Gathering Daemon (EGD) on socket B<path>. -It queries 255 bytes and uses L<RAND_add(3)> to seed the -OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for -RAND_egd_bytes(path, 255); - -RAND_egd_bytes() queries EGD on socket B<path>. -It queries B<bytes> bytes and uses L<RAND_add(3)> to seed the -OpenSSL built-in PRNG. -This function is more flexible than RAND_egd(). -When only one secret key must -be generated, it is not necessary to request the full amount 255 bytes from -the EGD socket. This can be advantageous, since the amount of randomness -that can be retrieved from EGD over time is limited. - -RAND_query_egd_bytes() performs the actual query of the EGD daemon on socket -B<path>. If B<buf> is given, B<bytes> bytes are queried and written into -B<buf>. If B<buf> is NULL, B<bytes> bytes are queried and used to seed the -OpenSSL built-in PRNG using L<RAND_add(3)>. - -=head1 NOTES - -On systems without /dev/*random devices providing randomness from the kernel, -EGD provides -a socket interface through which randomness can be gathered in chunks up to -255 bytes. Several chunks can be queried during one connection. - -EGD is available from http://www.lothar.com/tech/crypto/ (C<perl -Makefile.PL; make; make install> to install). It is run as B<egd> -I<path>, where I<path> is an absolute path designating a socket. When -RAND_egd() is called with that path as an argument, it tries to read -random bytes that EGD has collected. RAND_egd() retrieves randomness from the -daemon using the daemon's "non-blocking read" command which shall -be answered immediately by the daemon without waiting for additional -randomness to be collected. The write and read socket operations in the -communication are blocking. - -Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is -available from -http://prngd.sourceforge.net/ . -PRNGD does employ an internal PRNG itself and can therefore never run -out of randomness. - -OpenSSL automatically queries EGD when randomness is requested via RAND_bytes() -or the status is checked via RAND_status() for the first time, if the socket -is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool. +On older platforms without a good source of randomness such as C</dev/urandom>, +it is possible to query an Entropy Gathering Daemon (EGD) over a local +socket to obtain randomness and seed the OpenSSL RNG. +The protocol used is defined by the EGDs available at +L<http://egd.sourceforge.net/> or L<http://prngd.sourceforge.net>. + +RAND_egd_bytes() requests B<num> bytes of randomness from an EGD at the +specified socket B<path>, and passes the data it receives into RAND_add(). +RAND_egd() is equivalent to RAND_egd_bytes() with B<num> set to 255. + +RAND_query_egd_bytes() requests B<num> bytes of randomness from an EGD at +the specified socket B<path>. +If B<buf> is B<NULL>, it is equivalent to RAND_egd_bytes(). +If B<buf> is not B<NULL>, then the data is copied to the buffer and +RAND_add() is not called. + +OpenSSL can be configured at build time to try to use the EGD for seeding +automatically. =head1 RETURN VALUE RAND_egd() and RAND_egd_bytes() return the number of bytes read from the -daemon on success, and -1 if the connection failed or the daemon did not +daemon on success, or -1 if the connection failed or the daemon did not return enough data to fully seed the PRNG. RAND_query_egd_bytes() returns the number of bytes read from the daemon on -success, and -1 if the connection failed. The PRNG state is not considered. +success, or -1 if the connection failed. =head1 SEE ALSO -L<RAND_bytes(3)>, L<RAND_add(3)>, -L<RAND_cleanup(3)> +L<RAND_bytes(3)>, L<RAND_add(3)> =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/RAND_load_file.pod b/doc/man3/RAND_load_file.pod index 8b5867ff89..0a0c4bca6b 100644 --- a/doc/man3/RAND_load_file.pod +++ b/doc/man3/RAND_load_file.pod @@ -64,7 +64,7 @@ error. =head1 SEE ALSO -L<RAND_bytes(3)>, L<RAND_add(3)>, L<RAND_cleanup(3)> +L<RAND_bytes(3)>, L<RAND_add(3)> =head1 HISTORY @@ -75,7 +75,7 @@ poorly enforced before OpenSSL version 1.1.1. =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/RAND_set_rand_method.pod b/doc/man3/RAND_set_rand_method.pod index 12075d252a..70c1b23cd7 100644 --- a/doc/man3/RAND_set_rand_method.pod +++ b/doc/man3/RAND_set_rand_method.pod @@ -8,35 +8,32 @@ RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method #include <openssl/rand.h> + RAND_METHOD *RAND_OpenSSL(void); + void RAND_set_rand_method(const RAND_METHOD *meth); const RAND_METHOD *RAND_get_rand_method(void); - RAND_METHOD *RAND_OpenSSL(void); - =head1 DESCRIPTION A B<RAND_METHOD> specifies the functions that OpenSSL uses for random number -generation. By modifying the method, alternative implementations such as -hardware RNGs may be used. IMPORTANT: See the NOTES section for important -information about how these RAND API functions are affected by the use of -B<ENGINE> API calls. +generation. -Initially, the default RAND_METHOD is the OpenSSL internal implementation, as -returned by RAND_OpenSSL(). +Initially, the default B<RAND_METHOD> is the OpenSSL internal implementation, +as returned by RAND_OpenSSL(). +This implementation ensures that the PRNG state is unique for each thread. -RAND_set_default_method() makes B<meth> the method for PRNG use. B<NB>: This is -true only whilst no ENGINE has been set as a default for RAND, so this function -is no longer recommended. +If an B<ENGINE> is loaded that provides the RAND API, however, it will +be used instead of the method returned by RAND_OpenSSL(). -RAND_get_default_method() returns a pointer to the current RAND_METHOD. -However, the meaningfulness of this result is dependent on whether the ENGINE -API is being used, so this function is no longer recommended. +RAND_set_rand_method() makes B<meth> the method for PRNG use. If an +ENGINE was providing the method, it will be released first. + +RAND_get_rand_method() returns a pointer to the current B<RAND_METHOD>. =head1 THE RAND_METHOD STRUCTURE - typedef struct rand_meth_st - { + typedef struct rand_meth_st { void (*seed)(const void *buf, int num); int (*bytes)(unsigned char *buf, int num); void (*cleanup)(void); @@ -45,33 +42,23 @@ API is being used, so this function is no longer recommended. int (*status)(void); } RAND_METHOD; -The components point to method implementations used by (or called by), in order, +The fields point to functions that are used by, in order, RAND_seed(), RAND_bytes(), internal RAND cleanup, RAND_add(), RAND_pseudo_rand() and RAND_status(). -Each component may be NULL if the function is not implemented. +Each pointer may be NULL if the function is not implemented. =head1 RETURN VALUES RAND_set_rand_method() returns no value. RAND_get_rand_method() and RAND_OpenSSL() return pointers to the respective methods. -=head1 NOTES - -RAND_METHOD implementations are grouped together with other -algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a -default ENGINE is specified for RAND functionality using an ENGINE API function, -that will override any RAND defaults set using the RAND API (ie. -RAND_set_rand_method()). For this reason, the ENGINE API is the recommended way -to control default implementations for use in RAND and other cryptographic -algorithms. - =head1 SEE ALSO L<RAND_bytes(3)>, L<ENGINE_by_id(3)> =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy |