BNgenerateprime(3) OpenSSL BNgenerateprime(3)

NAME
       BNgenerateprime, BNisprime, BNisprimefasttest - generate primes
       and test for primality

SYNOPSIS
        #include 

        BIGNUM *BNgenerateprime(BIGNUM *ret, int num, int safe, BIGNUM *add,
            BIGNUM *rem, void (*callback)(int, int, void *), void *cbarg);

        int BNisprime(const BIGNUM *a, int checks, void (*callback)(int, int,
            void *), BNCTX *ctx, void *cbarg);

        int BNisprimefasttest(const BIGNUM *a, int checks,
            void (*callback)(int, int, void *), BNCTX *ctx, void *cbarg,
            int dotrialdivision);

DESCRIPTION
       BNgenerateprime() 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:

       +o   ccaallllbbaacckk((00,, ii,, ccbbaarrgg)) is called after generating the i-th
           potential prime number.

       +o   While the number is being tested for primality, ccaallllbbaacckk((11,, jj,,
           ccbbaarrgg)) is called as described below.

       +o   When a prime has been found, ccaallllbbaacckk((22,, ii,, ccbbaarrgg)) 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 BNgenerateprime().  The
       prime number generation has a negligible error probability.

       BNisprime() and BNisprimefasttest() 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.

       BNisprimefasttest(), when called with ddoottrriiaallddiivviissiioonn ==== 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,, ccbbaarrgg)) is
       called.  If ddoottrriiaallddiivviissiioonn ==== 00, this test is skipped.

       Both BNisprime() and BNisprimefasttest() perform a Miller-Rabin
       probabilistic primality test with cchheecckkss iterations. If cchheecckkss ====
       BBNNpprriimmeecchheecckkss, 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,, ccbbaarrgg)) is called after the
       j-th iteration (j = 0, 1, ...). ccttxx is a pre-allocated BBNNCCTTXX (to save
       the overhead of allocating and freeing the structure in a loop), or
       NNUULLLL.

RETURN VALUES
       BNgenerateprime() returns the prime number on success, NNUULLLL
       otherwise.

       BNisprime() 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 ERRgeterror(3).

SEE ALSO
       bn(3), ERRgeterror(3), rand(3)

HISTORY       The ccbbaarrgg arguments to BNgenerateprime() and to BNisprime() were
       added in SSLeay 0.9.0. The rreett argument to BNgenerateprime() was
       added in SSLeay 0.9.1.  BNisprimefasttest() was added in OpenSSL
       0.9.5.



0.9.7l                            2003-01-13              BNgenerateprime(3)