| Current Path : /usr/opt/openssl11/share/doc/openssl/html/man3/ |
FreeBSD hs32.drive.ne.jp 9.1-RELEASE FreeBSD 9.1-RELEASE #1: Wed Jan 14 12:18:08 JST 2015 root@hs32.drive.ne.jp:/sys/amd64/compile/hs32 amd64 |
| Current File : //usr/opt/openssl11/share/doc/openssl/html/man3/BN_GENCB_call.html |
<?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@hsxx.drive.ne.jp" />
</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_ex, BN_is_prime_ex, 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_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
const BIGNUM *rem, BN_GENCB *cb);</pre>
<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>
<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:</p>
<pre>
#if OPENSSL_API_COMPAT < 0x00908000L
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 *a, int checks,
void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);</pre>
<pre>
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);
#endif</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p><code>BN_generate_prime_ex()</code> generates a pseudo-random prime number of
at least bit length <strong>bits</strong>. The returned number is probably prime
with a negligible error. 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.</p>
<p><code>BN_is_prime_ex()</code> and <code>BN_is_prime_fasttest_ex()</code> test if the number <strong>p</strong> is
prime. The following tests are performed until one of them shows that
<strong>p</strong> is composite; if <strong>p</strong> passes all these tests, it is considered
prime.</p>
<p><code>BN_is_prime_fasttest_ex()</code>, when called with <strong>do_trial_division == 1</strong>,
first attempts trial division by a number of small primes;
if no divisors are found by this test and <strong>cb</strong> is not <strong>NULL</strong>,
<strong>BN_GENCB_call(cb, 1, -1)</strong> is called.
If <strong>do_trial_division == 0</strong>, this test is skipped.</p>
<p>Both <code>BN_is_prime_ex()</code> and <code>BN_is_prime_fasttest_ex()</code> perform a Miller-Rabin
probabilistic primality test with <strong>nchecks</strong> iterations. If
<strong>nchecks == BN_prime_checks</strong>, a number of iterations is used that
yields a false positive rate of at most 2^-64 for random input.
The error rate depends on the size of the prime and goes down for bigger primes.
The rate is 2^-80 starting at 308 bits, 2^-112 at 852 bits, 2^-128 at 1080 bits,
2^-192 at 3747 bits and 2^-256 at 6394 bits.</p>
<p>When the source of the prime is not random or not trusted, the number
of checks needs to be much higher to reach the same level of assurance:
It should equal half of the targeted security level in bits (rounded up to the
next integer if necessary).
For instance, to reach the 128 bit security level, <strong>nchecks</strong> should be set to
64.</p>
<p>If <strong>cb</strong> is not <strong>NULL</strong>, <strong>BN_GENCB_call(cb, 1, j)</strong> is called
after the j-th iteration (j = 0, 1, ...). <strong>ctx</strong> is a
preallocated <strong>BN_CTX</strong> (to save the overhead of allocating and
freeing the structure in a loop), or <strong>NULL</strong>.</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> and
<code>BN_is_prime_fasttest()</code> 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>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.</p>
<p>Licensed under the OpenSSL license (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>