path: root/lib/libcrypto/man/BN_generate_prime.3

.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.