From 37ca204b96b036f949b8bc8389c1f8e806e1cbec Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Wed, 29 May 2019 16:03:57 +0100 Subject: [PATCH] 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 (Merged from https://github.com/openssl/openssl/pull/9039) --- doc/man3/RAND_DRBG_get0_master.pod | 34 +++++++++++++++++++++++------- doc/man3/RAND_DRBG_new.pod | 25 +++++++++++++++++----- 2 files changed, 46 insertions(+), 13 deletions(-) diff --git a/doc/man3/RAND_DRBG_get0_master.pod b/doc/man3/RAND_DRBG_get0_master.pod index 62f6fdbdd0..77d0ab70a5 100644 --- 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 + 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 and DRBG are thread-local instances, which are used +The I and I DRBG are thread-local instances, which are used by RAND_bytes() and RAND_priv_bytes(), respectively. -The DRBG is a global instance, which is not intended to be used +The I 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 DRBG instance. +OPENSSL_CTX_get0_master_drbg() returns a pointer to the I DRBG instance +for the given OPENSSL_CTX B. -RAND_DRBG_get0_public() returns a pointer to the DRBG instance. +OPENSSL_CTX_get0_public_drbg() returns a pointer to the I DRBG instance +for the given OPENSSL_CTX B. -RAND_DRBG_get0_private() returns a pointer to the DRBG instance. +OPENSSL_CTX_get0_private_drbg() returns a pointer to the I DRBG instance +for the given OPENSSL_CTX B. +In all the above cases the B 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 DRBG instance. -The and DRBG instance can be accessed safely, because +It is not thread-safe to access the I DRBG instance. +The I and I 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 =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 8b73840697..3ff98ae052 100644 --- 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 + 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, allocated from the heap resp. -the secure heap -(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()). +the secure heap, for the given OPENSSL_CTX +(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()). The 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 with the given B and B. @@ -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 -- 2.25.1