diff options
Diffstat (limited to 'secure/lib/libcrypto/man/BN_generate_prime.3')
| -rw-r--r-- | secure/lib/libcrypto/man/BN_generate_prime.3 | 120 |
1 files changed, 85 insertions, 35 deletions
diff --git a/secure/lib/libcrypto/man/BN_generate_prime.3 b/secure/lib/libcrypto/man/BN_generate_prime.3 index 843860e1b36fb..bc73c105e8dc6 100644 --- a/secure/lib/libcrypto/man/BN_generate_prime.3 +++ b/secure/lib/libcrypto/man/BN_generate_prime.3 @@ -128,64 +128,76 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "BN_generate_prime 3" -.TH BN_generate_prime 3 "2018-08-14" "1.0.2p" "OpenSSL" +.IX Title "BN_GENERATE_PRIME 3" +.TH BN_GENERATE_PRIME 3 "2018-09-11" "1.1.1" "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_set_old, BN_GENCB_set, BN_generate_prime, BN_is_prime, -BN_is_prime_fasttest \- generate primes and test for primality +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 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/bn.h> \& -\& int BN_generate_prime_ex(BIGNUM *ret,int bits,int safe, const BIGNUM *add, -\& const BIGNUM *rem, BN_GENCB *cb); +\& 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_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_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, +\& int do_trial_division, BN_GENCB *cb); \& \& int BN_GENCB_call(BN_GENCB *cb, int a, int b); \& -\& #define BN_GENCB_set_old(gencb, callback, cb_arg) ... +\& BN_GENCB *BN_GENCB_new(void); \& -\& #define BN_GENCB_set(gencb, callback, cb_arg) ... +\& void BN_GENCB_free(BN_GENCB *cb); +\& +\& void BN_GENCB_set_old(BN_GENCB *gencb, +\& void (*callback)(int, int, void *), void *cb_arg); +\& +\& void BN_GENCB_set(BN_GENCB *gencb, +\& int (*callback)(int, int, BN_GENCB *), void *cb_arg); +\& +\& void *BN_GENCB_get_arg(BN_GENCB *cb); .Ve .PP Deprecated: .PP -.Vb 2 +.Vb 4 +\& #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); +\& BIGNUM *rem, void (*callback)(int, int, void *), +\& void *cb_arg); \& -\& int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int, -\& void *), BN_CTX *ctx, void *cb_arg); +\& int BN_is_prime(const BIGNUM *a, int checks, +\& void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); \& \& 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); +\& void (*callback)(int, int, void *), BN_CTX *ctx, +\& void *cb_arg, int do_trial_division); +\& #endif .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIBN_generate_prime_ex()\fR generates a pseudo-random prime number of -bit length \fBbits\fR. +at least bit length \fBbits\fR. If \fBret\fR is not \fB\s-1NULL\s0\fR, it will be used to store the number. .PP If \fBcb\fR is not \fB\s-1NULL\s0\fR, it is used as follows: -.IP "\(bu" 4 +.IP "\(bu" 2 \&\fBBN_GENCB_call(cb, 0, i)\fR is called after generating the i\-th potential prime number. -.IP "\(bu" 4 +.IP "\(bu" 2 While the number is being tested for primality, \&\fBBN_GENCB_call(cb, 1, j)\fR is called as described below. -.IP "\(bu" 4 +.IP "\(bu" 2 When a prime has been found, \fBBN_GENCB_call(cb, 2, i)\fR is called. +.IP "\(bu" 2 +The callers of \fIBN_generate_prime_ex()\fR may call \fBBN_GENCB_call(cb, i, j)\fR with +other values as described in their respective man pages; see \*(L"\s-1SEE ALSO\*(R"\s0. .PP The prime may have to fulfill additional requirements for use in Diffie-Hellman key exchange: @@ -231,29 +243,35 @@ after the j\-th iteration (j = 0, 1, ...). \fBctx\fR is a pre-allocated \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 -BN_GENCB_call calls the callback function held in the \fB\s-1BN_GENCB\s0\fR structure +\&\fIBN_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 programs should prefer the \*(L"new\*(R" style, whilst the \*(L"old\*(R" style is provided for backwards compatibility purposes. .PP +A \fB\s-1BN_GENCB\s0\fR structure should be created through a call to \fIBN_GENCB_new()\fR, +and freed through a call to \fIBN_GENCB_free()\fR. +.PP For \*(L"new\*(R" style callbacks a \s-1BN_GENCB\s0 structure should be initialised with a -call to BN_GENCB_set, where \fBgencb\fR is a \fB\s-1BN_GENCB\s0 *\fR, \fBcallback\fR is of +call to \fIBN_GENCB_set()\fR, where \fBgencb\fR is a \fB\s-1BN_GENCB\s0 *\fR, \fBcallback\fR is of type \fBint (*callback)(int, int, \s-1BN_GENCB\s0 *)\fR and \fBcb_arg\fR is a \fBvoid *\fR. \&\*(L"Old\*(R" style callbacks are the same except they are initialised with a call -to BN_GENCB_set_old and \fBcallback\fR is of type +to \fIBN_GENCB_set_old()\fR and \fBcallback\fR is of type \&\fBvoid (*callback)(int, int, void *)\fR. .PP A callback is invoked through a call to \fBBN_GENCB_call\fR. This will check the type of the callback and will invoke \fBcallback(a, b, gencb)\fR for new style callbacks or \fBcallback(a, b, cb_arg)\fR for old style. .PP -BN_generate_prime (deprecated) works in the same way as -BN_generate_prime_ex but expects an old style callback function +It is possible to obtain the argument associated with a \s-1BN_GENCB\s0 structure +(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg. +.PP +\&\fIBN_generate_prime()\fR (deprecated) works in the same way as +\&\fIBN_generate_prime_ex()\fR but expects an old-style callback function directly in the \fBcallback\fR parameter, and an argument to pass to it in -the \fBcb_arg\fR. Similarly BN_is_prime and BN_is_prime_fasttest are -deprecated and can be compared to BN_is_prime_ex and -BN_is_prime_fasttest_ex respectively. +the \fBcb_arg\fR. \fIBN_is_prime()\fR and \fIBN_is_prime_fasttest()\fR +can similarly be compared to \fIBN_is_prime_ex()\fR and +\&\fIBN_is_prime_fasttest_ex()\fR, respectively. .SH "RETURN VALUES" .IX Header "RETURN VALUES" \&\fIBN_generate_prime_ex()\fR return 1 on success or 0 on error. @@ -265,15 +283,47 @@ prime with an error probability of less than 0.25^\fBnchecks\fR, and .PP \&\fIBN_generate_prime()\fR returns the prime number on success, \fB\s-1NULL\s0\fR otherwise. .PP +BN_GENCB_new returns a pointer to a \s-1BN_GENCB\s0 structure on success, or \fB\s-1NULL\s0\fR +otherwise. +.PP +BN_GENCB_get_arg returns the argument previously associated with a \s-1BN_GENCB\s0 +structure. +.PP Callback functions should return 1 on success or 0 on error. .PP The error codes can be obtained by \fIERR_get_error\fR\|(3). +.SH "REMOVED FUNCTIONALITY" +.IX Header "REMOVED FUNCTIONALITY" +As of OpenSSL 1.1.0 it is no longer possible to create a \s-1BN_GENCB\s0 structure +directly, as in: +.PP +.Vb 1 +\& BN_GENCB callback; +.Ve +.PP +Instead applications should create a \s-1BN_GENCB\s0 structure using BN_GENCB_new: +.PP +.Vb 6 +\& BN_GENCB *callback; +\& callback = BN_GENCB_new(); +\& if (!callback) +\& /* error */ +\& ... +\& BN_GENCB_free(callback); +.Ve .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3), \fIrand\fR\|(3) +\&\fIDH_generate_parameters\fR\|(3), \fIDSA_generate_parameters\fR\|(3), +\&\fIRSA_generate_key\fR\|(3), \fIERR_get_error\fR\|(3), \fIRAND_bytes\fR\|(3) .SH "HISTORY" .IX Header "HISTORY" -The \fBcb_arg\fR arguments to \fIBN_generate_prime()\fR and to \fIBN_is_prime()\fR -were added in SSLeay 0.9.0. The \fBret\fR argument to \fIBN_generate_prime()\fR -was added in SSLeay 0.9.1. -\&\fIBN_is_prime_fasttest()\fR was added in OpenSSL 0.9.5. +\&\fIBN_GENCB_new()\fR, \fIBN_GENCB_free()\fR, +and \fIBN_GENCB_get_arg()\fR were added in OpenSSL 1.1.0 +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (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>. |