Add documentation for new functions taking an OPENSSL_CTX parameter

Various functions have been added that take an OPENSSL_CTX parameter as
a result of moving the RAND code into the FIPS module. We document all of
those functions.

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9039)

diff --git a/doc/man3/RAND_DRBG_get0_master.pod b/doc/man3/RAND_DRBG_get0_master.pod
index 62f6fdbdd09f4a89e8a7d3b2293707405fba50ac..77d0ab70a5b76838b99615c8e2772214b9917903 100644 (file)
--- a/doc/man3/RAND_DRBG_get0_master.pod
+++ b/doc/man3/RAND_DRBG_get0_master.pod
@@ -2,6 +2,9 @@
 
 =head1 NAME
 
+OPENSSL_CTX_get0_master_drbg,
+OPENSSL_CTX_get0_public_drbg,
+OPENSSL_CTX_get0_private_drbg,
 RAND_DRBG_get0_master,
 RAND_DRBG_get0_public,
 RAND_DRBG_get0_private
@@ -11,6 +14,9 @@ RAND_DRBG_get0_private
 
  #include <openssl/rand_drbg.h>
 
+ RAND_DRBG *OPENSSL_CTX_get0_master_drbg(OPENSSL_CTX *ctx);
+ RAND_DRBG *OPENSSL_CTX_get0_public_drbg(OPENSSL_CTX *ctx);
+ RAND_DRBG *OPENSSL_CTX_get0_private_drbg(OPENSSL_CTX *ctx);
  RAND_DRBG *RAND_DRBG_get0_master(void);
  RAND_DRBG *RAND_DRBG_get0_public(void);
  RAND_DRBG *RAND_DRBG_get0_private(void);
@@ -21,26 +27,35 @@ RAND_DRBG_get0_private
 The default RAND API implementation (RAND_OpenSSL()) utilizes three
 shared DRBG instances which are accessed via the RAND API:
 
-The <public> and <private> DRBG are thread-local instances, which are used
+The I<public> and I<private> DRBG are thread-local instances, which are used
 by RAND_bytes() and RAND_priv_bytes(), respectively.
-The <master> DRBG is a global instance, which is not intended to be used
+The I<master> DRBG is a global instance, which is not intended to be used
 directly, but is used internally to reseed the other two instances.
 
 These functions here provide access to the shared DRBG instances.
 
 =head1 RETURN VALUES
 
-RAND_DRBG_get0_master() returns a pointer to the <master> DRBG instance.
+OPENSSL_CTX_get0_master_drbg() returns a pointer to the I<master> DRBG instance
+for the given OPENSSL_CTX B<ctx>.
 
-RAND_DRBG_get0_public() returns a pointer to the <public> DRBG instance.
+OPENSSL_CTX_get0_public_drbg() returns a pointer to the I<public> DRBG instance
+for the given OPENSSL_CTX B<ctx>.
 
-RAND_DRBG_get0_private() returns a pointer to the <private> DRBG instance.
+OPENSSL_CTX_get0_private_drbg() returns a pointer to the I<private> DRBG instance
+for the given OPENSSL_CTX B<ctx>.
 
+In all the above cases the B<ctx> parameter can
+be NULL in which case the default OPENSSL_CTX is used. RAND_DRBG_get0_master(),
+RAND_DRBG_get0_public() and RAND_DRBG_get0_private() are the same as
+OPENSSL_CTX_get0_master_drbg(), OPENSSL_CTX_get0_public_drbg() and
+OPENSSL_CTX_get0_private_drbg() respectively except that the default OPENSSL_CTX
+is always used.
 
 =head1 NOTES
 
-It is not thread-safe to access the <master> DRBG instance.
-The <public> and <private> DRBG instance can be accessed safely, because
+It is not thread-safe to access the I<master> DRBG instance.
+The I<public> and I<private> DRBG instance can be accessed safely, because
 they are thread-local. Note however, that changes to these two instances
 apply only to the current thread.
 
@@ -65,7 +80,10 @@ L<RAND_DRBG(7)>
 
 =head1 HISTORY
 
-The RAND_DRBG functions were added in OpenSSL 1.1.1.
+The OPENSSL_CTX_get0_master_drbg(), OPENSSL_CTX_get0_public_drbg() and
+OPENSSL_CTX_get0_private_drbg() functions were added in OpenSSL 3.0.
+
+All other RAND_DRBG functions were added in OpenSSL 1.1.1.
 
 =head1 COPYRIGHT
 

diff --git a/doc/man3/RAND_DRBG_new.pod b/doc/man3/RAND_DRBG_new.pod
index 8b7384069711611ca33b5b9164f55e357d735862..3ff98ae0526a62dd29b97b258e48275b647f5335 100644 (file)
--- a/doc/man3/RAND_DRBG_new.pod
+++ b/doc/man3/RAND_DRBG_new.pod
@@ -2,7 +2,9 @@
 
 =head1 NAME
 
+RAND_DRBG_new_ex,
 RAND_DRBG_new,
+RAND_DRBG_secure_new_ex,
 RAND_DRBG_secure_new,
 RAND_DRBG_set,
 RAND_DRBG_set_defaults,
@@ -15,11 +17,20 @@ RAND_DRBG_free
 
  #include <openssl/rand_drbg.h>
 
+ RAND_DRBG *RAND_DRBG_new_ex(OPENSSL_CTX *ctx,
+                             int type,
+                             unsigned int flags,
+                             RAND_DRBG *parent);
 
  RAND_DRBG *RAND_DRBG_new(int type,
                           unsigned int flags,
                           RAND_DRBG *parent);
 
+ RAND_DRBG *RAND_DRBG_secure_new_ex(OPENSSL_CTX *ctx,
+                                    int type,
+                                    unsigned int flags,
+                                    RAND_DRBG *parent);
+
  RAND_DRBG *RAND_DRBG_secure_new(int type,
                                  unsigned int flags,
                                  RAND_DRBG *parent);
@@ -39,10 +50,13 @@ RAND_DRBG_free
 
 =head1 DESCRIPTION
 
-RAND_DRBG_new() and RAND_DRBG_secure_new()
+RAND_DRBG_new_ex() and RAND_DRBG_secure_new_ex()
 create a new DRBG instance of the given B<type>, allocated from the heap resp.
-the secure heap
-(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()).
+the secure heap, for the given OPENSSL_CTX <ctx>
+(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()). The <ctx> parameter can
+be NULL in which case the default OPENSSL_CTX is used. RAND_DRBG_new() and
+RAND_DRBG_secure_new() are the same as RAND_DRBG_new_ex() and
+RAND_DRBG_secure_new_ex() except that the default OPENSSL_CTX is always used.
 
 RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>.
 
@@ -108,8 +122,9 @@ uninstantiated state.
 =head1 RETURN VALUES
 
 
-RAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a DRBG
-instance allocated on the heap, resp. secure heap.
+RAND_DRBG_new_ex(), RAND_DRBG_new(), RAND_DRBG_secure_new_ex() and
+RAND_DRBG_secure_new() return a pointer to a DRBG instance allocated on the
+heap, resp. secure heap.
 
 RAND_DRBG_set(),
 RAND_DRBG_instantiate(), and