From: Pauli <pauli@openssl.org>
Date: Fri, 28 May 2021 04:44:38 +0000 (+1000)
Subject: doc: document the strength arugments to the RNG functions
X-Git-Tag: openssl-3.0.0-beta1~315
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e587bccdf9152716e8ff74d8208a064cabf9f3e8;p=thirdparty%2Fopenssl.git

doc: document the strength arugments to the RNG functions

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15513)
---

diff --git a/doc/man3/BN_rand.pod b/doc/man3/BN_rand.pod
index 1c50c692b94..06ee99d28ed 100644
--- a/doc/man3/BN_rand.pod
+++ b/doc/man3/BN_rand.pod
@@ -11,16 +11,20 @@ BN_pseudo_rand_range
 
  #include <openssl/bn.h>
 
- int BN_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, BN_CTX *ctx);
+ int BN_rand_ex(BIGNUM *rnd, int bits, int top, int bottom,
+                unsigned int strength, BN_CTX *ctx);
  int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
 
- int BN_priv_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, BN_CTX *ctx);
+ int BN_priv_rand_ex(BIGNUM *rnd, int bits, int top, int bottom,
+                     unsigned int strength, BN_CTX *ctx);
  int BN_priv_rand(BIGNUM *rnd, int bits, int top, int bottom);
 
- int BN_rand_range_ex(BIGNUM *rnd, BIGNUM *range, BN_CTX *ctx);
+ int BN_rand_range_ex(BIGNUM *rnd, BIGNUM *range, unsigned int strength,
+                      BN_CTX *ctx);
  int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
 
- int BN_priv_rand_range_ex(BIGNUM *rnd, BIGNUM *range, BN_CTX *ctx);
+ int BN_priv_rand_range_ex(BIGNUM *rnd, BIGNUM *range, unsigned int strength,
+                           BN_CTX *ctx);
  int BN_priv_rand_range(BIGNUM *rnd, BIGNUM *range);
 
 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
@@ -32,30 +36,32 @@ openssl_user_macros(7):
 
 =head1 DESCRIPTION
 
-BN_rand_ex() generate a cryptographically strong pseudo-random
-number of B<bits> in length and stores it in B<rnd> using the random number
-generator for the library context associated with B<ctx>. The parameter B<ctx>
+BN_rand_ex() generates a cryptographically strong pseudo-random
+number of I<bits> in length and security strength at least I<strength> bits
+using the random number generator for the library context associated with
+I<ctx>. The function stores the generated data in I<rnd>. The parameter I<ctx>
 may be NULL in which case the default library context is used.
-If B<bits> is less than zero, or too small to
-accommodate the requirements specified by the B<top> and B<bottom>
+If I<bits> is less than zero, or too small to
+accommodate the requirements specified by the I<top> and I<bottom>
 parameters, an error is returned.
-The B<top> parameters specifies
+The I<top> parameters specifies
 requirements on the most significant bit of the generated number.
 If it is B<BN_RAND_TOP_ANY>, there is no constraint.
 If it is B<BN_RAND_TOP_ONE>, the top bit must be one.
 If it is B<BN_RAND_TOP_TWO>, the two most significant bits of
 the number will be set to 1, so that the product of two such random
-numbers will always have 2*B<bits> length.
-If B<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it
+numbers will always have 2*I<bits> length.
+If I<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it
 is B<BN_RAND_BOTTOM_ANY> it can be odd or even.
-If B<bits> is 1 then B<top> cannot also be B<BN_RAND_FLG_TOPTWO>.
+If I<bits> is 1 then I<top> cannot also be B<BN_RAND_FLG_TOPTWO>.
 
 BN_rand() is the same as BN_rand_ex() except that the default library context
 is always used.
 
 BN_rand_range_ex() generates a cryptographically strong pseudo-random
-number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range> using the random number
-generator for the library context associated with B<ctx>. The parameter B<ctx>
+number I<rnd>, of security stength at least I<strength> bits,
+in the range 0 E<lt>= I<rnd> E<lt> I<range> using the random number
+generator for the library context associated with I<ctx>. The parameter I<ctx>
 may be NULL in which case the default library context is used.
 
 BN_rand_range() is the same as BN_rand_range_ex() except that the default
diff --git a/doc/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod
index aeec94dd8be..832790fb959 100644
--- a/doc/man3/RAND_bytes.pod
+++ b/doc/man3/RAND_bytes.pod
@@ -12,8 +12,10 @@ RAND_pseudo_bytes - generate random data
  int RAND_bytes(unsigned char *buf, int num);
  int RAND_priv_bytes(unsigned char *buf, int num);
 
- int RAND_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, int num);
- int RAND_priv_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, int num);
+ int RAND_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, int num,
+                   unsigned int strength);
+ int RAND_priv_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, int num,
+                        unsigned int strength);
 
 Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining
 B<OPENSSL_API_COMPAT> with a suitable version value, see
@@ -34,7 +36,9 @@ affect the secrecy of these private values, as described in L<RAND(7)>
 and L<EVP_RAND(7)>.
 
 RAND_bytes_ex() and RAND_priv_bytes_ex() are the same as RAND_bytes() and
-RAND_priv_bytes() except that they both take an additional I<ctx> parameter.
+RAND_priv_bytes() except that they both take additional I<strength> and
+I<ctx> parameters. The bytes genreated will have a security strength of at
+least I<strength> bits.
 The DRBG used for the operation is the public or private DRBG associated with
 the specified I<ctx>. The parameter can be NULL, in which case
 the default library context is used (see L<OSSL_LIB_CTX(3)>.