aboutsummaryrefslogtreecommitdiff
path: root/secure/lib/libcrypto/man/man3/BN_generate_prime.3
diff options
context:
space:
mode:
Diffstat (limited to 'secure/lib/libcrypto/man/man3/BN_generate_prime.3')
-rw-r--r--secure/lib/libcrypto/man/man3/BN_generate_prime.3148
1 files changed, 93 insertions, 55 deletions
diff --git a/secure/lib/libcrypto/man/man3/BN_generate_prime.3 b/secure/lib/libcrypto/man/man3/BN_generate_prime.3
index 7aa800377a6a..f588873a8ef0 100644
--- a/secure/lib/libcrypto/man/man3/BN_generate_prime.3
+++ b/secure/lib/libcrypto/man/man3/BN_generate_prime.3
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
@@ -68,8 +68,6 @@
. \}
.\}
.rr rF
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
@@ -132,26 +130,30 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
-.IX Title "BN_GENERATE_PRIME 3"
-.TH BN_GENERATE_PRIME 3 "2022-05-03" "1.1.1o" "OpenSSL"
+.IX Title "BN_GENERATE_PRIME 3ossl"
+.TH BN_GENERATE_PRIME 3ossl "2023-09-19" "3.0.11" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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_check_prime,
+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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
\&
-\& int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);
-\&
-\& int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
-\& int do_trial_division, BN_GENCB *cb);
+\& int BN_check_prime(const BIGNUM *p, BN_CTX *ctx, BN_GENCB *cb);
\&
\& int BN_GENCB_call(BN_GENCB *cb, int a, int b);
\&
@@ -168,29 +170,47 @@ BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call, BN
\& void *BN_GENCB_get_arg(BN_GENCB *cb);
.Ve
.PP
-Deprecated:
+The following functions have been deprecated since OpenSSL 0.9.8, and can be
+hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
+see \fBopenssl_user_macros\fR\|(7):
.PP
-.Vb 4
-\& #if OPENSSL_API_COMPAT < 0x00908000L
+.Vb 3
\& BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
\& BIGNUM *rem, void (*callback)(int, int, void *),
\& void *cb_arg);
\&
-\& int BN_is_prime(const BIGNUM *a, int checks,
+\& int BN_is_prime(const BIGNUM *p, int nchecks,
\& void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);
\&
-\& int BN_is_prime_fasttest(const BIGNUM *a, int checks,
+\& int BN_is_prime_fasttest(const BIGNUM *p, int nchecks,
\& void (*callback)(int, int, void *), BN_CTX *ctx,
\& void *cb_arg, int do_trial_division);
-\& #endif
+.Ve
+.PP
+The following functions have been deprecated since OpenSSL 3.0, and can be
+hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value,
+see \fBopenssl_user_macros\fR\|(7):
+.PP
+.Vb 1
+\& int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);
+\&
+\& int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
+\& int do_trial_division, BN_GENCB *cb);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
-\&\fBBN_generate_prime_ex()\fR generates a pseudo-random prime number of
-at least bit length \fBbits\fR. The returned number is probably prime
-with a negligible error. If \fBadd\fR is \fB\s-1NULL\s0\fR the returned prime
-number will have exact bit length \fBbits\fR with the top most two
-bits set.
+\&\fBBN_generate_prime_ex2()\fR generates a pseudo-random prime number of
+at least bit length \fBbits\fR using the \s-1BN_CTX\s0 provided in \fBctx\fR. The value of
+\&\fBctx\fR must not be \s-1NULL.\s0
+.PP
+The returned number is probably prime with a negligible error.
+The maximum error rate is 2^\-128.
+It's 2^\-287 for a 512 bit prime, 2^\-435 for a 1024 bit prime,
+2^\-648 for a 2048 bit prime, and lower than 2^\-882 for primes larger
+than 2048 bit.
+.PP
+If \fBadd\fR is \fB\s-1NULL\s0\fR the returned prime number will have exact bit
+length \fBbits\fR with the top most two bits set.
.PP
If \fBret\fR is not \fB\s-1NULL\s0\fR, it will be used to store the number.
.PP
@@ -222,38 +242,51 @@ It is recommended that \fBadd\fR is a multiple of 4.
The random generator must be seeded prior to calling \fBBN_generate_prime_ex()\fR.
If the automatic seeding or reseeding of the OpenSSL \s-1CSPRNG\s0 fails due to
external circumstances (see \s-1\fBRAND\s0\fR\|(7)), the operation will fail.
+The random number generator configured for the \s-1OSSL_LIB_CTX\s0 associated with
+\&\fBctx\fR will be used.
+.PP
+\&\fBBN_generate_prime_ex()\fR is the same as \fBBN_generate_prime_ex2()\fR except that no
+\&\fBctx\fR parameter is passed.
+In this case the random number generator associated with the default \s-1OSSL_LIB_CTX\s0
+will be used.
+.PP
+\&\fBBN_check_prime()\fR, \fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR
+and \fBBN_is_prime_fasttest()\fR test if the number \fBp\fR is prime.
+The functions tests until one of the tests shows that \fBp\fR is composite,
+or all the tests passed.
+If \fBp\fR passes all these tests, it is considered a probable prime.
+.PP
+The test performed on \fBp\fR are trial division by a number of small primes
+and rounds of the of the Miller-Rabin probabilistic primality test.
+.PP
+The functions do at least 64 rounds of the Miller-Rabin test giving a maximum
+false positive rate of 2^\-128.
+If the size of \fBp\fR is more than 2048 bits, they do at least 128 rounds
+giving a maximum false positive rate of 2^\-256.
+.PP
+If \fBnchecks\fR is larger than the minimum above (64 or 128), \fBnchecks\fR
+rounds of the Miller-Rabin test will be done.
.PP
-\&\fBBN_is_prime_ex()\fR and \fBBN_is_prime_fasttest_ex()\fR test if the number \fBp\fR is
-prime. The following tests are performed until one of them shows that
-\&\fBp\fR is composite; if \fBp\fR passes all these tests, it is considered
-prime.
-.PP
-\&\fBBN_is_prime_fasttest_ex()\fR, when called with \fBdo_trial_division == 1\fR,
-first attempts trial division by a number of small primes;
-if no divisors are found by this test and \fBcb\fR is not \fB\s-1NULL\s0\fR,
-\&\fBBN_GENCB_call(cb, 1, \-1)\fR is called.
-If \fBdo_trial_division == 0\fR, this test is skipped.
-.PP
-Both \fBBN_is_prime_ex()\fR and \fBBN_is_prime_fasttest_ex()\fR perform a Miller-Rabin
-probabilistic primality test with \fBnchecks\fR iterations. If
-\&\fBnchecks == BN_prime_checks\fR, a number of iterations is used that
-yields a false positive rate of at most 2^\-64 for random input.
-The error rate depends on the size of the prime and goes down for bigger primes.
-The rate is 2^\-80 starting at 308 bits, 2^\-112 at 852 bits, 2^\-128 at 1080 bits,
-2^\-192 at 3747 bits and 2^\-256 at 6394 bits.
-.PP
-When the source of the prime is not random or not trusted, the number
-of checks needs to be much higher to reach the same level of assurance:
-It should equal half of the targeted security level in bits (rounded up to the
-next integer if necessary).
-For instance, to reach the 128 bit security level, \fBnchecks\fR should be set to
-64.
-.PP
-If \fBcb\fR is not \fB\s-1NULL\s0\fR, \fBBN_GENCB_call(cb, 1, j)\fR is called
-after the j\-th iteration (j = 0, 1, ...). \fBctx\fR is a
-preallocated \fB\s-1BN_CTX\s0\fR (to save the overhead of allocating and
+If \fBdo_trial_division\fR set to \fB0\fR, the trial division will be skipped.
+\&\fBBN_is_prime_ex()\fR and \fBBN_is_prime()\fR always skip the trial division.
+.PP
+\&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR
+and \fBBN_is_prime_fasttest()\fR are deprecated.
+.PP
+\&\fBBN_is_prime_fasttest()\fR and \fBBN_is_prime()\fR behave just like
+\&\fBBN_is_prime_fasttest_ex()\fR and \fBBN_is_prime_ex()\fR respectively, but with the old
+style call back.
+.PP
+\&\fBctx\fR is a preallocated \fB\s-1BN_CTX\s0\fR (to save the overhead of allocating and
freeing the structure in a loop), or \fB\s-1NULL\s0\fR.
.PP
+If the trial division is done, and no divisors are found and \fBcb\fR
+is not \fB\s-1NULL\s0\fR, \fBBN_GENCB_call(cb, 1, \-1)\fR is called.
+.PP
+After each round of the Miller-Rabin probabilistic primality test,
+if \fBcb\fR is not \fB\s-1NULL\s0\fR, \fBBN_GENCB_call(cb, 1, j)\fR is called
+with \fBj\fR the iteration (j = 0, 1, ...).
+.PP
\&\fBBN_GENCB_call()\fR calls the callback function held in the \fB\s-1BN_GENCB\s0\fR structure
and passes the ints \fBa\fR and \fBb\fR as arguments. There are two types of
\&\fB\s-1BN_GENCB\s0\fR structure that are supported: \*(L"new\*(R" style and \*(L"old\*(R" style. New
@@ -287,9 +320,9 @@ can similarly be compared to \fBBN_is_prime_ex()\fR and
.IX Header "RETURN VALUES"
\&\fBBN_generate_prime_ex()\fR return 1 on success or 0 on error.
.PP
-\&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR and
-\&\fBBN_is_prime_fasttest()\fR return 0 if the number is composite, 1 if it is
-prime with an error probability of less than 0.25^\fBnchecks\fR, and
+\&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR,
+\&\fBBN_is_prime_fasttest()\fR and BN_check_prime return 0 if the number is composite,
+1 if it is prime with an error probability of less than 0.25^\fBnchecks\fR, and
\&\-1 on error.
.PP
\&\fBBN_generate_prime()\fR returns the prime number on success, \fB\s-1NULL\s0\fR otherwise.
@@ -329,13 +362,18 @@ Instead applications should create a \s-1BN_GENCB\s0 structure using BN_GENCB_ne
\&\s-1\fBRAND\s0\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
+The \fBBN_is_prime_ex()\fR and \fBBN_is_prime_fasttest_ex()\fR functions were
+deprecated in OpenSSL 3.0.
+.PP
The \fBBN_GENCB_new()\fR, \fBBN_GENCB_free()\fR,
and \fBBN_GENCB_get_arg()\fR functions were added in OpenSSL 1.1.0.
+.PP
+\&\fBBN_check_prime()\fR was added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
-Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
-Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
+Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.
generated by cgit v1.2.3 (git 2.25.1) at 2024-04-23 08:02:32 +0000