BN_generate_prime 3 2003-07-24 0.9.9-dev OpenSSL

NAME

BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality

LIBRARY

libcrypto, -lcrypto

SYNOPSIS


 #include 


 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, 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);

DESCRIPTION

_B_N___g_e_n_e_r_a_t_e___p_r_i_m_e_(_) generates a pseudo-random prime number of nnuumm bits. If rreett is not NNUULLLL, it will be used to store the number.

If ccaallllbbaacckk is not NNUULLLL, it is called as follows:

· ccaallllbbaacckk((00,, ii,, ccbb__aarrgg)) is called after generating the i-th
potential prime number.
· While the number is being tested for primality, ccaallllbbaacckk((11,, jj,, <> ccbb__aarrgg)) is called as described below.
· When a prime has been found, ccaallllbbaacckk((22,, ii,, ccbb__aarrgg)) is called.

The prime may have to fulfill additional requirements for use in Diffie-Hellman key exchange:

If aadddd is not NNUULLLL, the prime will fulfill the condition p % aadddd == rreemm (p % aadddd == 1 if rreemm == NNUULLLL) in order to suit a given generator.

If ssaaffee is true, it will be a safe prime (i.e. a prime p so that (p-1)/2 is also prime).

The PRNG must be seeded prior to calling _B_N___g_e_n_e_r_a_t_e___p_r_i_m_e_(_). The prime number generation has a negligible error probability.

_B_N___i_s___p_r_i_m_e_(_) and _B_N___i_s___p_r_i_m_e___f_a_s_t_t_e_s_t_(_) test if the number aa is prime. The following tests are performed until one of them shows that aa is composite; if aa passes all these tests, it is considered prime.

_B_N___i_s___p_r_i_m_e___f_a_s_t_t_e_s_t_(_), when called with ddoo__ttrriiaall__ddiivviissiioonn ==== 11, first attempts trial division by a number of small primes; if no divisors are found by this test and ccaallllbbaacckk is not NNUULLLL, ccaallllbbaacckk((11,, --11,, ccbb__aarrgg)) is called. If ddoo__ttrriiaall__ddiivviissiioonn ==== 00, this test is skipped.

Both _B_N___i_s___p_r_i_m_e_(_) and _B_N___i_s___p_r_i_m_e___f_a_s_t_t_e_s_t_(_) perform a Miller-Rabin probabilistic primality test with cchheecckkss iterations. If cchheecckkss ==== BBNN__pprriimmee__cchheecckkss, a number of iterations is used that yields a false positive rate of at most 2^-80 for random input.

If ccaallllbbaacckk is not NNUULLLL, ccaallllbbaacckk((11,, jj,, ccbb__aarrgg)) is called after the j-th iteration (j = 0, 1, ...). ccttxx is a pre-allocated BBNN__CCTTXX (to save the overhead of allocating and freeing the structure in a loop), or NNUULLLL.

RETURN VALUES

_B_N___g_e_n_e_r_a_t_e___p_r_i_m_e_(_) returns the prime number on success, NNUULLLL otherwise.

_B_N___i_s___p_r_i_m_e_(_) returns 0 if the number is composite, 1 if it is prime with an error probability of less than 0.25^cchheecckkss, and -1 on error.

The error codes can be obtained by _E_R_R___g_e_t___e_r_r_o_r(3).

SEE ALSO

_o_p_e_n_s_s_l___b_n(3), _E_R_R___g_e_t___e_r_r_o_r(3), _o_p_e_n_s_s_l___r_a_n_d(3)

HISTORY

The ccbb__aarrgg arguments to _B_N___g_e_n_e_r_a_t_e___p_r_i_m_e_(_) and to _B_N___i_s___p_r_i_m_e_(_) were added in SSLeay 0.9.0. The rreett argument to _B_N___g_e_n_e_r_a_t_e___p_r_i_m_e_(_) was added in SSLeay 0.9.1. _B_N___i_s___p_r_i_m_e___f_a_s_t_t_e_s_t_(_) was added in OpenSSL 0.9.5.