From 04256277cb9dddedd77965f19107c6c3935e8b96 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Fri, 7 Jul 2017 16:47:39 -0400 Subject: [PATCH] Update various RAND podpages Reviewed-by: Tim Hudson (Merged from https://github.com/openssl/openssl/pull/3883) --- doc/man3/RAND_add.pod | 16 +++---- doc/man3/RAND_cleanup.pod | 9 ++-- doc/man3/RAND_egd.pod | 76 ++++++++++--------------------- doc/man3/RAND_load_file.pod | 4 +- 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, 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 -or L. - RAND_seed() is equivalent to RAND_add() with B set to B. +On systems that provide C 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 or L. + 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, L, -L, L +L =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. +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. =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 + 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. -It queries 255 bytes and uses L 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. -It queries B bytes and uses L 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. If B is given, B bytes are queried and written into -B. If B is NULL, B bytes are queried and used to seed the -OpenSSL built-in PRNG using L. - -=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 to install). It is run as B -I, where I 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, +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 or L. + +RAND_egd_bytes() requests B bytes of randomness from an EGD at the +specified socket B, and passes the data it receives into RAND_add(). +RAND_egd() is equivalent to RAND_egd_bytes() with B set to 255. + +RAND_query_egd_bytes() requests B bytes of randomness from an EGD at +the specified socket B. +If B is B, it is equivalent to RAND_egd_bytes(). +If B is not B, 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, L, -L +L, L =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, L, L +L, L =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 + 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 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 API calls. +generation. -Initially, the default RAND_METHOD is the OpenSSL internal implementation, as -returned by RAND_OpenSSL(). +Initially, the default B 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 the method for PRNG use. B: 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 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 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. =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 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, L =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 -- 2.25.1