RAND_METHOD deprecation: documentation

Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13652)

4 files changed, 80 insertions, 9 deletions

diff --git a/doc/man3/RAND_get0_primary.pod b/doc/man3/RAND_get0_primary.pod
index 5d84b330ab..cf0fae95f7 100644
--- a/doc/man3/RAND_get0_primary.pod
+++ b/doc/man3/RAND_get0_primary.pod
@@ -15,7 +15,6 @@ RAND_get0_private
  EVP_RAND_CTX *RAND_get0_public(OSSL_LIB_CTX *ctx);
  EVP_RAND_CTX *RAND_get0_private(OSSL_LIB_CTX *ctx);
 
-
 =head1 DESCRIPTION
 
 The default RAND API implementation (RAND_OpenSSL()) utilizes three
diff --git a/doc/man3/RAND_set_DRBG_type.pod b/doc/man3/RAND_set_DRBG_type.pod
new file mode 100644
index 0000000000..f78c15ff45
--- /dev/null
+++ b/doc/man3/RAND_set_DRBG_type.pod
@@ -0,0 +1,64 @@
+=pod
+
+=head1 NAME
+
+RAND_set_DRBG_type,
+RAND_set_seed_source_type
+- specify the global random number generator types
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ int RAND_set_DRBG_type(OSSL_LIB_CTX *ctx, const char *drbg, const char *propq,
+                        const char *cipher, const char *digest);
+ int RAND_set_seed_source_type(OSSL_LIB_CTX *ctx, const char *seed,
+                               const char *propq);
+
+=head1 DESCRIPTION
+
+RAND_set_DRBG_type() specifies the random bit generator that will be
+used within the library context I<ctx>.  A generator of name I<drbg>
+with properties I<propq> will be fetched.  It will be instantiated with
+either I<cipher> or I<digest> as its underlying cryptographic algorithm.
+This specifies the type that will be used for the primary, public and
+private random instances.
+
+RAND_set_seed_source_type() specifies the seed source that will be used
+within the library context I<ctx>.  The seed source of name I<seed>
+with properties I<propq> will be fetched and used to seed the primary
+random big generator.
+
+=head1 RETURN VALUES
+
+These function return 1 on success and 0 on failure.
+
+=head1 NOTES
+
+These functions must be called before the random bit generators are first
+created in the library context.  They will return an error if the call
+is made too late.
+
+The default DRBG is "CTR-DRBG" using the "AES-256-CTR" cipher.
+
+The default seed source is "SEED-SRC".
+
+=head1 SEE ALSO
+
+L<EVP_RAND(3)>,
+L<RAND_get0_primary(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man3/RAND_set_rand_method.pod b/doc/man3/RAND_set_rand_method.pod
index a989c1c9b4..755e25dde1 100644
--- a/doc/man3/RAND_set_rand_method.pod
+++ b/doc/man3/RAND_set_rand_method.pod
@@ -8,6 +8,10 @@ RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method
 
  #include <openssl/rand.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  RAND_METHOD *RAND_OpenSSL(void);
 
  int RAND_set_rand_method(const RAND_METHOD *meth);
@@ -16,6 +20,10 @@ RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method
 
 =head1 DESCRIPTION
 
+All of the functions described on this page are deprecated.
+Applications should instead use L<RAND_set_DRBG_type(3)>,
+L<EVP_RAND(3)> and L<EVP_RAND(7)>.
+
 A B<RAND_METHOD> specifies the functions that OpenSSL uses for random number
 generation.
 
@@ -55,14 +63,16 @@ methods.
 
 =head1 SEE ALSO
 
+L<EVP_RAND(3)>,
+L<RAND_set_DRBG_type(3)>,
 L<RAND_bytes(3)>,
 L<ENGINE_by_id(3)>,
+L<EVP_RAND(7)>,
 L<RAND(7)>
 
 =head1 HISTORY
 
-The ability for an B<ENGINE> to replace the RAND API was deprecated in
-OpenSSL 3.0.
+All of these functions were deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man7/RAND.pod b/doc/man7/RAND.pod
index 7bad23a0ca..8ae55ccac8 100644
--- a/doc/man7/RAND.pod
+++ b/doc/man7/RAND.pod
@@ -46,8 +46,8 @@ possible about its internal state, and that a compromise of the "public"
 CSPRNG instance will not affect the secrecy of these private values.
 
 In the rare case where the default implementation does not satisfy your special
-requirements, the default RAND method can be replaced by your own RAND
-method using L<RAND_set_rand_method(3)>.
+requirements, the default RAND internals can be replaced by your own
+L<EVP_RAND(3)> objects.
 
 Changing the default random generator should be necessary
 only in exceptional cases and is not recommended, unless you have a profound
@@ -66,11 +66,9 @@ number generator (CSPRNG), which is described in [NIST SP 800-90A Rev. 1].
 
 L<RAND_bytes(3)>,
 L<RAND_priv_bytes(3)>,
-L<RAND_get_rand_method(3)>,
-L<RAND_set_rand_method(3)>,
-L<RAND_OpenSSL(3)>,
 L<EVP_RAND(3)>,
-L<RAND_get0_primary(3)>
+L<RAND_get0_primary(3)>,
+L<EVP_RAND(7)>
 
 =head1 COPYRIGHT