Update documentation of BN_generate_prime_ex

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

diff --git a/doc/man3/BN_generate_prime.pod b/doc/man3/BN_generate_prime.pod
index 08158c193981dadd94b897c9a3fff12b035ef796..6a3376b1fdeb8f79551d1ec696ed925e2c90aefe 100644 (file)
--- a/doc/man3/BN_generate_prime.pod
+++ b/doc/man3/BN_generate_prime.pod
@@ -2,15 +2,19 @@
 
 =head1 NAME
 
-BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call,
-BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg,
-BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test
-for primality
+BN_generate_prime_ex2, BN_generate_prime_ex, BN_is_prime_ex,
+BN_is_prime_fasttest_ex, BN_GENCB_call, BN_GENCB_new, BN_GENCB_free,
+BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, BN_generate_prime,
+BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality
 
 =head1 SYNOPSIS
 
  #include <openssl/bn.h>
 
+ int BN_generate_prime_ex2(BIGNUM *ret, int bits, int safe,
+                           const BIGNUM *add, const BIGNUM *rem, BN_GENCB *cb,
+                           BN_CTX *ctx);
+
  int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
                           const BIGNUM *rem, BN_GENCB *cb);
 
@@ -33,9 +37,10 @@ for primality
 
  void *BN_GENCB_get_arg(BN_GENCB *cb);
 
-Deprecated:
+Deprecated since OpenSSL 0.9.8, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #if OPENSSL_API_COMPAT < 0x00908000L
  BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
                            BIGNUM *rem, void (*callback)(int, int, void *),
                            void *cb_arg);
@@ -46,12 +51,16 @@ Deprecated:
  int BN_is_prime_fasttest(const BIGNUM *a, int checks,
                           void (*callback)(int, int, void *), BN_CTX *ctx,
                           void *cb_arg, int do_trial_division);
- #endif
 
 =head1 DESCRIPTION
 
-BN_generate_prime_ex() generates a pseudo-random prime number of
-at least bit length B<bits>.
+BN_generate_prime_ex2() generates a pseudo-random prime number of
+at least bit length B<bits> using the BN_CTX provided in B<ctx>. The value of
+B<ctx> must not be NULL.
+The returned number is probably prime with a negligible error.
+If B<add> is B<NULL> the returned prime number will have exact bit
+length B<bits> with the top most two bits set.
+
 If B<ret> is not B<NULL>, it will be used to store the number.
 
 If B<cb> is not B<NULL>, it is used as follows:
@@ -87,10 +96,20 @@ If B<add> is not B<NULL>, the prime will fulfill the condition p % B<add>
 generator.
 
 If B<safe> is true, it will be a safe prime (i.e. a prime p so
-that (p-1)/2 is also prime).
+that (p-1)/2 is also prime). If B<safe> is true, and B<rem> == B<NULL>
+the condition will be p % B<add> == 3.
+It is recommended that B<add> is a multiple of 4.
+
+The random generator must be seeded prior to calling BN_generate_prime_ex().
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
+The random number generator configured for the OPENSSL_CTX associated with
+B<ctx> will be used.
 
-The PRNG must be seeded prior to calling BN_generate_prime_ex().
-The prime number generation has a negligible error probability.
+BN_generate_prime_ex() is the same as BN_generate_prime_ex2() except that no
+B<ctx> parameter is passed.
+In this case the random number generator associated with the default OPENSSL_CTX
+will be used.
 
 BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is
 prime.  The following tests are performed until one of them shows that
@@ -143,7 +162,7 @@ A callback is invoked through a call to B<BN_GENCB_call>. This will check
 the type of the callback and will invoke B<callback(a, b, gencb)> for new
 style callbacks or B<callback(a, b, cb_arg)> for old style.
 
-It is possible to obtained the argument associated with a BN_GENCB structure
+It is possible to obtain the argument associated with a BN_GENCB structure
 (set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.
 
 BN_generate_prime() (deprecated) works in the same way as
@@ -193,18 +212,19 @@ Instead applications should create a BN_GENCB structure using BN_GENCB_new:
 =head1 SEE ALSO
 
 L<DH_generate_parameters(3)>, L<DSA_generate_parameters(3)>,
-L<RSA_generate_key(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>
+L<RSA_generate_key(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>,
+L<RAND(7)>
 
 =head1 HISTORY
 
-BN_GENCB_new(), BN_GENCB_free(),
-and BN_GENCB_get_arg() were added in OpenSSL 1.1.0
+The BN_GENCB_new(), BN_GENCB_free(),
+and BN_GENCB_get_arg() functions were added in OpenSSL 1.1.0.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+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
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.