QuasarApp/openssl
4
0
Fork 0
mirror of https://github.com/QuasarApp/openssl.git synced 2025-05-10 16:39:40 +00:00
Code Issues Projects Releases Wiki Activity

Add documentation for new functions taking an OPENSSL_CTX parameter

Browse Source 
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)
This commit is contained in:
Matt Caswell 2019-05-29 16:03:57 +01:00
parent a2f27fd750
commit 37ca204b96
2 changed files with 46 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
doc/man3/RAND_DRBG_get0_master.pod
View File

@ -2,6 +2,9 @@
=head1 NAME =head1 NAME
OPENSSL_CTX_get0_master_drbg,
OPENSSL_CTX_get0_public_drbg,
OPENSSL_CTX_get0_private_drbg,
RAND_DRBG_get0_master, RAND_DRBG_get0_master,
RAND_DRBG_get0_public, RAND_DRBG_get0_public,
RAND_DRBG_get0_private RAND_DRBG_get0_private
@ -11,6 +14,9 @@ RAND_DRBG_get0_private
#include <openssl/rand_drbg.h> #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_master(void);
RAND_DRBG *RAND_DRBG_get0_public(void); RAND_DRBG *RAND_DRBG_get0_public(void);
RAND_DRBG *RAND_DRBG_get0_private(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 The default RAND API implementation (RAND_OpenSSL()) utilizes three
shared DRBG instances which are accessed via the RAND API: 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. 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. directly, but is used internally to reseed the other two instances.
These functions here provide access to the shared DRBG instances. These functions here provide access to the shared DRBG instances.
=head1 RETURN VALUES =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 =head1 NOTES
It is not thread-safe to access the <master> DRBG instance. It is not thread-safe to access the I<master> DRBG instance.
The <public> and <private> DRBG instance can be accessed safely, because 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 they are thread-local. Note however, that changes to these two instances
apply only to the current thread. apply only to the current thread.
@ -65,7 +80,10 @@ L<RAND_DRBG(7)>
=head1 HISTORY =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 =head1 COPYRIGHT

25
doc/man3/RAND_DRBG_new.pod
View File

@ -2,7 +2,9 @@
=head1 NAME =head1 NAME
RAND_DRBG_new_ex,
RAND_DRBG_new, RAND_DRBG_new,
RAND_DRBG_secure_new_ex,
RAND_DRBG_secure_new, RAND_DRBG_secure_new,
RAND_DRBG_set, RAND_DRBG_set,
RAND_DRBG_set_defaults, RAND_DRBG_set_defaults,
@ -15,11 +17,20 @@ RAND_DRBG_free
#include <openssl/rand_drbg.h> #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, RAND_DRBG *RAND_DRBG_new(int type,
unsigned int flags, unsigned int flags,
RAND_DRBG *parent); 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, RAND_DRBG *RAND_DRBG_secure_new(int type,
unsigned int flags, unsigned int flags,
RAND_DRBG *parent); RAND_DRBG *parent);
@ -39,10 +50,13 @@ RAND_DRBG_free
=head1 DESCRIPTION =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. create a new DRBG instance of the given B<type>, allocated from the heap resp.
the secure heap the secure heap, for the given OPENSSL_CTX <ctx>
(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()). (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>. RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>.
@ -108,8 +122,9 @@ uninstantiated state.
=head1 RETURN VALUES =head1 RETURN VALUES
RAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a DRBG RAND_DRBG_new_ex(), RAND_DRBG_new(), RAND_DRBG_secure_new_ex() and
instance allocated on the heap, resp. secure heap. RAND_DRBG_secure_new() return a pointer to a DRBG instance allocated on the
heap, resp. secure heap.
RAND_DRBG_set(), RAND_DRBG_set(),
RAND_DRBG_instantiate(), and RAND_DRBG_instantiate(), and