OPENSSL_s390xcap.pod: list msa9 facility bit (155)

[openssl.git] / doc / man3 / BN_rand.pod

diff --git a/doc/man3/BN_rand.pod b/doc/man3/BN_rand.pod
index 18f70908362bb7598acca37fc4c00582af1b965e..fc41322f8e8ffa5db32053c582d21449d6dd1e00 100644 (file)
--- a/doc/man3/BN_rand.pod
+++ b/doc/man3/BN_rand.pod
@@ -2,30 +2,37 @@
 
 =head1 NAME
 
-BN_rand, BN_priv_rand, BN_pseudo_rand,
-BN_rand_range, BN_priv_rand_range, BN_pseudo_rand_range
+BN_rand_ex, BN_rand, BN_priv_rand_ex, BN_priv_rand, BN_pseudo_rand,
+BN_rand_range_ex, BN_rand_range, BN_priv_rand_range_ex, BN_priv_rand_range,
+BN_pseudo_rand_range
 - generate pseudo-random number
 
 =head1 SYNOPSIS
 
  #include <openssl/bn.h>
 
+ int BN_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, 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(BIGNUM *rnd, int bits, int top, int bottom);
 
  int BN_pseudo_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(BIGNUM *rnd, BIGNUM *range);
 
+ int BN_priv_rand_range_ex(BIGNUM *rnd, BIGNUM *range, BN_CTX *ctx);
  int BN_priv_rand_range(BIGNUM *rnd, BIGNUM *range);
 
  int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);
 
 =head1 DESCRIPTION
 
-BN_rand() generates a cryptographically strong pseudo-random number of
-B<bits> in length and stores it in B<rnd>.
+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>
+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>
 parameters, an error is returned.
@@ -40,11 +47,20 @@ If B<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>.
 
-BN_rand_range() generates a cryptographically strong pseudo-random
-number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range>.
+BN_rand() is the same as BN_rand_ex() except that the default library context
+is always used.
 
-BN_priv_rand() and BN_priv_rand_range() have the same semantics as
-BN_rand() and BN_rand_range() respectively.  They are intended to be
+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>
+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
+library context is always used.
+
+BN_priv_rand_ex(), BN_priv_rand(), BN_priv_rand_rand_ex() and
+BN_priv_rand_range() have the same semantics as BN_rand_ex(), BN_rand(),
+BN_rand_range_ex() and BN_rand_range() respectively.  They are intended to be
 used for generating values that should remain private, and mirror the
 same difference between L<RAND_bytes(3)> and L<RAND_priv_bytes(3)>.
 
@@ -59,6 +75,15 @@ seeded with enough randomness to ensure an unpredictable byte sequence.
 The functions return 1 on success, 0 on error.
 The error codes can be obtained by L<ERR_get_error(3)>.
 
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>,
+L<RAND_add(3)>,
+L<RAND_bytes(3)>,
+L<RAND_priv_bytes(3)>,
+L<RAND(7)>,
+L<RAND_DRBG(7)>
+
 =head1 HISTORY
 
 =over 2
@@ -73,22 +98,19 @@ a future release.
 
 =item *
 
-BN_priv_rand() and BN_priv_rand_range() were added in OpenSSL 1.1.1.
+The
+BN_priv_rand() and BN_priv_rand_range() functions were added in OpenSSL 1.1.1.
 
-=back
+=item *
 
-=head1 SEE ALSO
+The BN_rand_ex(), BN_priv_rand_ex(), BN_rand_range_ex() and
+BN_priv_rand_range_ex() functions were added in OpenSSL 3.0.
 
-L<ERR_get_error(3)>,
-L<RAND_add(3)>,
-L<RAND_bytes(3)>,
-L<RAND_priv_bytes(3)>,
-L<RAND(7)>,
-L<RAND_DRBG(7)>
+=back
 
 =head1 COPYRIGHT
 
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy