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 1c50c692b942a20a3e9e9024af4e4f4184925c20..06ee99d28ed6e499bbab42445077dd7f2085cb04 100644 (file)
--- a/doc/man3/BN_rand.pod
+++ b/doc/man3/BN_rand.pod
@@ -11,16 +11,20 @@ BN_pseudo_rand_range
 
  #include <openssl/bn.h>
 
 
  #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_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_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_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
  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
 
 
 =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.
 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.
 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
 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.
 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
 
 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
 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 aeec94dd8bea9ac8b1f343f3c07818ea59b08eaf..832790fb95945cba01eb676fb5b0ff7290e28074 100644 (file)
--- 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(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
 
 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
 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)>.
 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)>.