251 lines
12 KiB
HTML
Executable File
251 lines
12 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>BN_generate_prime</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#removed_functionality">REMOVED FUNCTIONALITY</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#history">HISTORY</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>BN_generate_prime_ex2, BN_generate_prime_ex, BN_is_prime_ex, BN_check_prime,
|
|
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</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/bn.h></pre>
|
|
<pre>
|
|
int BN_generate_prime_ex2(BIGNUM *ret, int bits, int safe,
|
|
const BIGNUM *add, const BIGNUM *rem, BN_GENCB *cb,
|
|
BN_CTX *ctx);</pre>
|
|
<pre>
|
|
int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
|
|
const BIGNUM *rem, BN_GENCB *cb);</pre>
|
|
<pre>
|
|
int BN_check_prime(const BIGNUM *p, BN_CTX *ctx, BN_GENCB *cb);</pre>
|
|
<pre>
|
|
int BN_GENCB_call(BN_GENCB *cb, int a, int b);</pre>
|
|
<pre>
|
|
BN_GENCB *BN_GENCB_new(void);</pre>
|
|
<pre>
|
|
void BN_GENCB_free(BN_GENCB *cb);</pre>
|
|
<pre>
|
|
void BN_GENCB_set_old(BN_GENCB *gencb,
|
|
void (*callback)(int, int, void *), void *cb_arg);</pre>
|
|
<pre>
|
|
void BN_GENCB_set(BN_GENCB *gencb,
|
|
int (*callback)(int, int, BN_GENCB *), void *cb_arg);</pre>
|
|
<pre>
|
|
void *BN_GENCB_get_arg(BN_GENCB *cb);</pre>
|
|
<p>Deprecated since OpenSSL 0.9.8, can be hidden entirely by defining
|
|
<strong>OPENSSL_API_COMPAT</strong> with a suitable version value, see
|
|
<em>openssl_user_macros(7)</em>:</p>
|
|
<pre>
|
|
BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
|
|
BIGNUM *rem, void (*callback)(int, int, void *),
|
|
void *cb_arg);</pre>
|
|
<pre>
|
|
int BN_is_prime(const BIGNUM *p, int nchecks,
|
|
void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);</pre>
|
|
<pre>
|
|
int BN_is_prime_fasttest(const BIGNUM *p, int nchecks,
|
|
void (*callback)(int, int, void *), BN_CTX *ctx,
|
|
void *cb_arg, int do_trial_division);</pre>
|
|
<p>Deprecated since OpenSSL 3.0:</p>
|
|
<pre>
|
|
int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);</pre>
|
|
<pre>
|
|
int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
|
|
int do_trial_division, BN_GENCB *cb);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>BN_generate_prime_ex2() generates a pseudo-random prime number of
|
|
at least bit length <strong>bits</strong> using the BN_CTX provided in <strong>ctx</strong>. The value of
|
|
<strong>ctx</strong> must not be NULL.</p>
|
|
<p>The returned number is probably prime with a negligible error.
|
|
The maximum error rate is 2^-128.
|
|
It's 2^-287 for a 512 bit prime, 2^-435 for a 1024 bit prime,
|
|
2^-648 for a 2048 bit prime, and lower than 2^-882 for primes larger
|
|
than 2048 bit.</p>
|
|
<p>If <strong>add</strong> is <strong>NULL</strong> the returned prime number will have exact bit
|
|
length <strong>bits</strong> with the top most two bits set.</p>
|
|
<p>If <strong>ret</strong> is not <strong>NULL</strong>, it will be used to store the number.</p>
|
|
<p>If <strong>cb</strong> is not <strong>NULL</strong>, it is used as follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p><strong>BN_GENCB_call(cb, 0, i)</strong> is called after generating the i-th
|
|
potential prime number.</p>
|
|
</li>
|
|
<li>
|
|
<p>While the number is being tested for primality,
|
|
<strong>BN_GENCB_call(cb, 1, j)</strong> is called as described below.</p>
|
|
</li>
|
|
<li>
|
|
<p>When a prime has been found, <strong>BN_GENCB_call(cb, 2, i)</strong> is called.</p>
|
|
</li>
|
|
<li>
|
|
<p>The callers of <code>BN_generate_prime_ex()</code> may call <strong>BN_GENCB_call(cb, i, j)</strong> with
|
|
other values as described in their respective man pages; see <a href="#see_also">SEE ALSO</a>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The prime may have to fulfill additional requirements for use in
|
|
Diffie-Hellman key exchange:</p>
|
|
<p>If <strong>add</strong> is not <strong>NULL</strong>, the prime will fulfill the condition p % <strong>add</strong>
|
|
== <strong>rem</strong> (p % <strong>add</strong> == 1 if <strong>rem</strong> == <strong>NULL</strong>) in order to suit a given
|
|
generator.</p>
|
|
<p>If <strong>safe</strong> is true, it will be a safe prime (i.e. a prime p so
|
|
that (p-1)/2 is also prime). If <strong>safe</strong> is true, and <strong>rem</strong> == <strong>NULL</strong>
|
|
the condition will be p % <strong>add</strong> == 3.
|
|
It is recommended that <strong>add</strong> is a multiple of 4.</p>
|
|
<p>The random generator must be seeded prior to calling <code>BN_generate_prime_ex()</code>.
|
|
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
|
|
external circumstances (see <em>RAND(7)</em>), the operation will fail.
|
|
The random number generator configured for the OPENSSL_CTX associated with
|
|
<strong>ctx</strong> will be used.</p>
|
|
<p><code>BN_generate_prime_ex()</code> is the same as BN_generate_prime_ex2() except that no
|
|
<strong>ctx</strong> parameter is passed.
|
|
In this case the random number generator associated with the default OPENSSL_CTX
|
|
will be used.</p>
|
|
<p><code>BN_check_prime()</code>, <code>BN_is_prime_ex()</code>, <code>BN_is_prime_fasttest_ex()</code>, <code>BN_is_prime()</code>
|
|
and <code>BN_is_prime_fasttest()</code> test if the number <strong>p</strong> is prime.
|
|
The functions tests until one of the tests shows that <strong>p</strong> is composite,
|
|
or all the tests passed.
|
|
If <strong>p</strong> passes all these tests, it is considered a probable prime.</p>
|
|
<p>The test performed on <strong>p</strong> are trial division by a number of small primes
|
|
and rounds of the of the Miller-Rabin probabilistic primality test.</p>
|
|
<p>The functions do at least 64 rounds of the Miller-Rabin test giving a maximum
|
|
false positive rate of 2^-128.
|
|
If the size of <strong>p</strong> is more than 2048 bits, they do at least 128 rounds
|
|
giving a maximum false positive rate of 2^-256.</p>
|
|
<p>If <strong>nchecks</strong> is larger than the minimum above (64 or 128), <strong>nchecks</strong>
|
|
rounds of the Miller-Rabin test will be done.</p>
|
|
<p>If <strong>do_trial_division</strong> set to <strong>0</strong>, the trial division will be skipped.
|
|
<code>BN_is_prime_ex()</code> and <code>BN_is_prime()</code> always skip the trial division.</p>
|
|
<p><code>BN_is_prime_ex()</code>, <code>BN_is_prime_fasttest_ex()</code>, <code>BN_is_prime()</code>
|
|
and <code>BN_is_prime_fasttest()</code> are deprecated.</p>
|
|
<p><code>BN_is_prime_fasttest()</code> and <code>BN_is_prime()</code> behave just like
|
|
<code>BN_is_prime_fasttest_ex()</code> and <code>BN_is_prime_ex()</code> respectively, but with the old
|
|
style call back.</p>
|
|
<p><strong>ctx</strong> is a pre-allocated <strong>BN_CTX</strong> (to save the overhead of allocating and
|
|
freeing the structure in a loop), or <strong>NULL</strong>.</p>
|
|
<p>If the trial division is done, and no divisors are found and <strong>cb</strong>
|
|
is not <strong>NULL</strong>, <strong>BN_GENCB_call(cb, 1, -1)</strong> is called.</p>
|
|
<p>After each round of the Miller-Rabin probabilistic primality test,
|
|
if <strong>cb</strong> is not <strong>NULL</strong>, <strong>BN_GENCB_call(cb, 1, j)</strong> is called
|
|
with <strong>j</strong> the iteration (j = 0, 1, ...).</p>
|
|
<p><code>BN_GENCB_call()</code> calls the callback function held in the <strong>BN_GENCB</strong> structure
|
|
and passes the ints <strong>a</strong> and <strong>b</strong> as arguments. There are two types of
|
|
<strong>BN_GENCB</strong> structure 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.</p>
|
|
<p>A <strong>BN_GENCB</strong> structure should be created through a call to <code>BN_GENCB_new()</code>,
|
|
and freed through a call to <code>BN_GENCB_free()</code>.</p>
|
|
<p>For "new" style callbacks a BN_GENCB structure should be initialised with a
|
|
call to <code>BN_GENCB_set()</code>, where <strong>gencb</strong> is a <strong>BN_GENCB *</strong>, <strong>callback</strong> is of
|
|
type <strong>int (*callback)(int, int, BN_GENCB *)</strong> and <strong>cb_arg</strong> is a <strong>void *</strong>.
|
|
"Old" style callbacks are the same except they are initialised with a call
|
|
to <code>BN_GENCB_set_old()</code> and <strong>callback</strong> is of type
|
|
<strong>void (*callback)(int, int, void *)</strong>.</p>
|
|
<p>A callback is invoked through a call to <strong>BN_GENCB_call</strong>. This will check
|
|
the type of the callback and will invoke <strong>callback(a, b, gencb)</strong> for new
|
|
style callbacks or <strong>callback(a, b, cb_arg)</strong> for old style.</p>
|
|
<p>It is possible to obtain the argument associated with a BN_GENCB structure
|
|
(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.</p>
|
|
<p><code>BN_generate_prime()</code> (deprecated) works in the same way as
|
|
<code>BN_generate_prime_ex()</code> but expects an old-style callback function
|
|
directly in the <strong>callback</strong> parameter, and an argument to pass to it in
|
|
the <strong>cb_arg</strong>. <code>BN_is_prime()</code> and <code>BN_is_prime_fasttest()</code>
|
|
can similarly be compared to <code>BN_is_prime_ex()</code> and
|
|
<code>BN_is_prime_fasttest_ex()</code>, respectively.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p><code>BN_generate_prime_ex()</code> return 1 on success or 0 on error.</p>
|
|
<p><code>BN_is_prime_ex()</code>, <code>BN_is_prime_fasttest_ex()</code>, <code>BN_is_prime()</code>,
|
|
<code>BN_is_prime_fasttest()</code> and BN_check_prime return 0 if the number is composite,
|
|
1 if it is prime with an error probability of less than 0.25^<strong>nchecks</strong>, and
|
|
-1 on error.</p>
|
|
<p><code>BN_generate_prime()</code> returns the prime number on success, <strong>NULL</strong> otherwise.</p>
|
|
<p>BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or <strong>NULL</strong>
|
|
otherwise.</p>
|
|
<p>BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB
|
|
structure.</p>
|
|
<p>Callback functions should return 1 on success or 0 on error.</p>
|
|
<p>The error codes can be obtained by <em>ERR_get_error(3)</em>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="removed_functionality">REMOVED FUNCTIONALITY</a></h1>
|
|
<p>As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure
|
|
directly, as in:</p>
|
|
<pre>
|
|
BN_GENCB callback;</pre>
|
|
<p>Instead applications should create a BN_GENCB structure using BN_GENCB_new:</p>
|
|
<pre>
|
|
BN_GENCB *callback;
|
|
callback = BN_GENCB_new();
|
|
if (!callback)
|
|
/* error */
|
|
...
|
|
BN_GENCB_free(callback);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>DH_generate_parameters(3)</em>, <em>DSA_generate_parameters(3)</em>,
|
|
<em>RSA_generate_key(3)</em>, <em>ERR_get_error(3)</em>, <em>RAND_bytes(3)</em>,
|
|
<em>RAND(7)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p>The <code>BN_GENCB_new()</code>, <code>BN_GENCB_free()</code>,
|
|
and <code>BN_GENCB_get_arg()</code> functions were added in OpenSSL 1.1.0.</p>
|
|
<p><code>BN_check_prime()</code> was added in OpenSSL 3.0.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|