From 9cb1a51933a1847042ee88e16d560485f682bcad Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Mon, 23 Feb 2015 17:43:24 +0000 Subject: fourth batch of perlpod(1) to mdoc(7) conversion --- src/lib/libcrypto/man/BN_generate_prime.3 | 289 ++++++++++++++++++++++++++++++ 1 file changed, 289 insertions(+) create mode 100644 src/lib/libcrypto/man/BN_generate_prime.3 (limited to 'src/lib/libcrypto/man/BN_generate_prime.3') diff --git a/src/lib/libcrypto/man/BN_generate_prime.3 b/src/lib/libcrypto/man/BN_generate_prime.3 new file mode 100644 index 0000000000..e269571914 --- /dev/null +++ b/src/lib/libcrypto/man/BN_generate_prime.3 @@ -0,0 +1,289 @@ +.Dd $Mdocdate: February 23 2015 $ +.Dt BN_GENERATE_PRIME 3 +.Os +.Sh NAME +.Nm BN_generate_prime_ex , +.Nm BN_is_prime_ex , +.Nm BN_is_prime_fasttest_ex , +.Nm BN_GENCB_call , +.Nm BN_GENCB_set_old , +.Nm BN_GENCB_set , +.Nm BN_generate_prime , +.Nm BN_is_prime , +.Nm BN_is_prime_fasttest +.Nd generate primes and test for primality +.Sh SYNOPSIS +.In openssl/bn.h +.Ft int +.Fo BN_generate_prime_ex +.Fa "BIGNUM *ret" +.Fa "int bits" +.Fa "int safe" +.Fa "const BIGNUM *add" +.Fa "const BIGNUM *rem" +.Fa "BN_GENCB *cb" +.Fc +.Ft int +.Fo BN_is_prime_ex +.Fa "const BIGNUM *p" +.Fa "int nchecks" +.Fa "BN_CTX *ctx" +.Fa "BN_GENCB *cb" +.Fc +.Ft int +.Fo BN_is_prime_fasttest_ex +.Fa "const BIGNUM *p" +.Fa "int nchecks" +.Fa "BN_CTX *ctx" +.Fa "int do_trial_division" +.Fa "BN_GENCB *cb" +.Fc +.Ft int +.Fo BN_GENCB_call +.Fa "BN_GENCB *cb" +.Fa "int a" +.Fa "int b" +.Fc +.Fd #define BN_GENCB_set_old(gencb, callback, cb_arg) ... +.Fd #define BN_GENCB_set(gencb, callback, cb_arg) ... +.Pp +Deprecated: +.Pp +.Ft BIGNUM * +.Fo BN_generate_prime +.Fa "BIGNUM *ret" +.Fa "int num" +.Fa "int safe" +.Fa "BIGNUM *add" +.Fa "BIGNUM *rem" +.Fa "void (*callback)(int, int, void *)" +.Fa "void *cb_arg" +.Fc +.Ft int +.Fo BN_is_prime +.Fa "const BIGNUM *a" +.Fa "int checks" +.Fa "void (*callback)(int, int, void *)" +.Fa "BN_CTX *ctx" +.Fa "void *cb_arg" +.Fc +.Ft int +.Fo BN_is_prime_fasttest +.Fa "const BIGNUM *a" +.Fa "int checks" +.Fa "void (*callback)(int, int, void *)" +.Fa "BN_CTX *ctx" +.Fa "void *cb_arg" +.Fa "int do_trial_division" +.Fc +.Sh DESCRIPTION +.Fn BN_generate_prime_ex +generates a pseudo-random prime number of bit length +.Fa bits . +If +.Fa ret +is not +.Dv NULL , +it will be used to store the number. +.Pp +If +.Fa cb +is not +.Dv NULL , +it is used as follows: +.Bl -bullet +.It +.Fn BN_GENCB_call cb 0 i +is called after generating the i-th potential prime number. +.It +While the number is being tested for primality, +.Fn BN_GENCB_call cb 1 j +is called as described below. +.It +When a prime has been found, +.Fn BN_GENCB_call cb 2 i +is called. +.El +.Pp +The prime may have to fulfill additional requirements for use in +Diffie-Hellman key exchange: +.Pp +If +.Fa add +is not +.Dv NULL , +the prime will fulfill the condition p % +.Fa add +== +.Fa rem +(p % +.Fa add +== 1 if +.Fa rem +== +.Dv NULL ) +in order to suit a given generator. +.Pp +If +.Fa safe +is true, it will be a safe prime (i.e. a prime p so that (p-1)/2 +is also prime). +.Pp +The prime number generation has a negligible error probability. +.Pp +.Fn BN_is_prime_ex +and +.Fn BN_is_prime_fasttest_ex +test if the number +.Fa p +is prime. +The following tests are performed until one of them shows that +.Fa p +is composite; if +.Fa p +passes all these tests, it is considered prime. +.Pp +.Fn BN_is_prime_fasttest_ex , +when called with +.Fa do_trial_division +== 1, first attempts trial division by a number of small primes; +if no divisors are found by this test and +.Fa cb +is not +.Dv NULL , +.Sy BN_GENCB_call(cb, 1, -1) +is called. +If +.Fa do_trial_division +== 0, this test is skipped. +.Pp +Both +.Fn BN_is_prime_ex +and +.Fn BN_is_prime_fasttest_ex +perform a Miller-Rabin probabilistic primality test with +.Fa nchecks +iterations. +If +.Fa nchecks +== +.Dv BN_prime_checks , +a number of iterations is used that yields a false positive rate of at +most 2^-80 for random input. +.Pp +If +.Fa cb +is not +.Dv NULL , +.Fa BN_GENCB_call cb 1 j +is called after the j-th iteration (j = 0, 1, ...). +.Fa ctx +is a pre-allocated +.Vt BN_CTX +(to save the overhead of allocating and freeing the structure in a +loop), or +.Dv NULL . +.Pp +.Fn BN_GENCB_call +calls the callback function held in the +.Vt BN_GENCB +structure and passes the ints +.Fa a +and +.Fa b +as arguments. +There are two types of +.Vt BN_GENCB +structures that are supported: "new" style and "old" style. +New programs should prefer the "new" style, whilst the "old" style is +provided for backwards compatibility purposes. +.Pp +For "new" style callbacks a +.Vt BN_GENCB +structure should be initialised with a call to +.Fn BN_GENCB_set , +where +.Fa gencb +is a +.Vt BN_GENCB * , +.Fa callback +is of type +.Vt int (*callback)(int, int, BN_GENCB *) +and +.Fa cb_arg +is a +.Vt void * . +"Old" style callbacks are the same except they are initialised with a +call to +.Fn BN_GENCB_set_old +and +.Fa callback +is of type +.Vt void (*callback)(int, int, void *) . +.Pp +A callback is invoked through a call to +.Fn BN_GENCB_call . +This will check the type of the callback and will invoke +.Fn callback a b gencb +for new style callbacks or +.Fn callback a b cb_arg +for old style. +.Pp +.Fn BN_generate_prime +(deprecated) works in the same way as +.Fn BN_generate_prime_ex +but expects an old style callback function directly in the +.Fa callback +parameter, and an argument to pass to it in the +.Fa cb_arg . +Similarly +.Fn BN_is_prime +and +.Fn BN_is_prime_fasttest +are deprecated and can be compared to +.Fn BN_is_prime_ex +and +.Fn BN_is_prime_fasttest_ex +respectively. +.Sh RETURN VALUES +.Fn BN_generate_prime_ex +returns 1 on success or 0 on error. +.Pp +.Fn BN_is_prime_ex , +.Fn BN_is_prime_fasttest_ex , +.Fn BN_is_prime , +and +.Fn BN_is_prime_fasttest +return 0 if the number is composite, 1 if it is prime with an error +probability of less than +.Pf 0.25^ Fa nchecks , +and -1 on error. +.Pp +.Fn BN_generate_prime +returns the prime number on success, +.Dv NULL +otherwise. +.Pp +Callback functions should return 1 on success or 0 on error. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr bn 3 , +.Xr ERR_get_error 3 , +.Xr rand 3 +.Sh HISTORY +The +.Fa cb_arg +arguments to +.Fn BN_generate_prime +and to +.Fn BN_is_prime +were added in SSLeay 0.9.0. +The +.Fa ret +argument to +.Fn BN_generate_prime +was added in SSLeay 0.9.1. +.Fn BN_is_prime_fasttest +was added in OpenSSL 0.9.5. -- cgit v1.2.3-55-g6feb