Commit 37ca204b authored by Matt Caswell's avatar Matt Caswell
Browse files

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: default avatarRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9039)
parent a2f27fd7

doc/man3/RAND_DRBG_get0_master.pod

+26 −8
Original line number Diff line number Diff line
@@ -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

doc/man3/RAND_DRBG_new.pod

+20 −5
Original line number Diff line number Diff line
@@ -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