secure/lib/libcrypto/man/man3/BN_generate_prime.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "BN_GENERATE_PRIME 3"
 136 .TH BN_GENERATE_PRIME 3 "2019-09-10" "1.1.1d" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 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
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/bn.h>
 147 \&
 148 \& int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
 149 \&                          const BIGNUM *rem, BN_GENCB *cb);
 150 \&
 151 \& int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);
 152 \&
 153 \& int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
 154 \&                             int do_trial_division, BN_GENCB *cb);
 155 \&
 156 \& int BN_GENCB_call(BN_GENCB *cb, int a, int b);
 157 \&
 158 \& BN_GENCB *BN_GENCB_new(void);
 159 \&
 160 \& void BN_GENCB_free(BN_GENCB *cb);
 161 \&
 162 \& void BN_GENCB_set_old(BN_GENCB *gencb,
 163 \&                       void (*callback)(int, int, void *), void *cb_arg);
 164 \&
 165 \& void BN_GENCB_set(BN_GENCB *gencb,
 166 \&                   int (*callback)(int, int, BN_GENCB *), void *cb_arg);
 167 \&
 168 \& void *BN_GENCB_get_arg(BN_GENCB *cb);
 169 .Ve
 170 .PP
 171 Deprecated:
 172 .PP
 173 .Vb 4
 174 \& #if OPENSSL_API_COMPAT < 0x00908000L
 175 \& BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
 176 \&                           BIGNUM *rem, void (*callback)(int, int, void *),
 177 \&                           void *cb_arg);
 178 \&
 179 \& int BN_is_prime(const BIGNUM *a, int checks,
 180 \&                 void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);
 181 \&
 182 \& int BN_is_prime_fasttest(const BIGNUM *a, int checks,
 183 \&                          void (*callback)(int, int, void *), BN_CTX *ctx,
 184 \&                          void *cb_arg, int do_trial_division);
 185 \& #endif
 186 .Ve
 187 .SH "DESCRIPTION"
 188 .IX Header "DESCRIPTION"
 189 \&\fBBN_generate_prime_ex()\fR generates a pseudo-random prime number of
 190 at least bit length \fBbits\fR. The returned number is probably prime
 191 with a negligible error.
 192 .PP
 193 If \fBret\fR is not \fB\s-1NULL\s0\fR, it will be used to store the number.
 194 .PP
 195 If \fBcb\fR is not \fB\s-1NULL\s0\fR, it is used as follows:
 196 .IP "\(bu" 2
 197 \&\fBBN_GENCB_call(cb, 0, i)\fR is called after generating the i\-th
 198 potential prime number.
 199 .IP "\(bu" 2
 200 While the number is being tested for primality,
 201 \&\fBBN_GENCB_call(cb, 1, j)\fR is called as described below.
 202 .IP "\(bu" 2
 203 When a prime has been found, \fBBN_GENCB_call(cb, 2, i)\fR is called.
 204 .IP "\(bu" 2
 205 The callers of \fBBN_generate_prime_ex()\fR may call \fBBN_GENCB_call(cb, i, j)\fR with
 206 other values as described in their respective man pages; see \*(L"\s-1SEE ALSO\*(R"\s0.
 207 .PP
 208 The prime may have to fulfill additional requirements for use in
 209 Diffie-Hellman key exchange:
 210 .PP
 211 If \fBadd\fR is not \fB\s-1NULL\s0\fR, the prime will fulfill the condition p % \fBadd\fR
 212 == \fBrem\fR (p % \fBadd\fR == 1 if \fBrem\fR == \fB\s-1NULL\s0\fR) in order to suit a given
 213 generator.
 214 .PP
 215 If \fBsafe\fR is true, it will be a safe prime (i.e. a prime p so
 216 that (p\-1)/2 is also prime).
 217 .PP
 218 The random generator must be seeded prior to calling \fBBN_generate_prime_ex()\fR.
 219 If the automatic seeding or reseeding of the OpenSSL \s-1CSPRNG\s0 fails due to
 220 external circumstances (see \s-1\fBRAND\s0\fR\|(7)), the operation will fail.
 221 .PP
 222 \&\fBBN_is_prime_ex()\fR and \fBBN_is_prime_fasttest_ex()\fR test if the number \fBp\fR is
 223 prime.  The following tests are performed until one of them shows that
 224 \&\fBp\fR is composite; if \fBp\fR passes all these tests, it is considered
 225 prime.
 226 .PP
 227 \&\fBBN_is_prime_fasttest_ex()\fR, when called with \fBdo_trial_division == 1\fR,
 228 first attempts trial division by a number of small primes;
 229 if no divisors are found by this test and \fBcb\fR is not \fB\s-1NULL\s0\fR,
 230 \&\fBBN_GENCB_call(cb, 1, \-1)\fR is called.
 231 If \fBdo_trial_division == 0\fR, this test is skipped.
 232 .PP
 233 Both \fBBN_is_prime_ex()\fR and \fBBN_is_prime_fasttest_ex()\fR perform a Miller-Rabin
 234 probabilistic primality test with \fBnchecks\fR iterations. If
 235 \&\fBnchecks == BN_prime_checks\fR, a number of iterations is used that
 236 yields a false positive rate of at most 2^\-64 for random input.
 237 The error rate depends on the size of the prime and goes down for bigger primes.
 238 The rate is 2^\-80 starting at 308 bits, 2^\-112 at 852 bits, 2^\-128 at 1080 bits,
 239 2^\-192 at 3747 bits and 2^\-256 at 6394 bits.
 240 .PP
 241 When the source of the prime is not random or not trusted, the number
 242 of checks needs to be much higher to reach the same level of assurance:
 243 It should equal half of the targeted security level in bits (rounded up to the
 244 next integer if necessary).
 245 For instance, to reach the 128 bit security level, \fBnchecks\fR should be set to
 246 64.
 247 .PP
 248 If \fBcb\fR is not \fB\s-1NULL\s0\fR, \fBBN_GENCB_call(cb, 1, j)\fR is called
 249 after the j\-th iteration (j = 0, 1, ...). \fBctx\fR is a
 250 pre-allocated \fB\s-1BN_CTX\s0\fR (to save the overhead of allocating and
 251 freeing the structure in a loop), or \fB\s-1NULL\s0\fR.
 252 .PP
 253 \&\fBBN_GENCB_call()\fR calls the callback function held in the \fB\s-1BN_GENCB\s0\fR structure
 254 and passes the ints \fBa\fR and \fBb\fR as arguments. There are two types of
 255 \&\fB\s-1BN_GENCB\s0\fR structure that are supported: \*(L"new\*(R" style and \*(L"old\*(R" style. New
 256 programs should prefer the \*(L"new\*(R" style, whilst the \*(L"old\*(R" style is provided
 257 for backwards compatibility purposes.
 258 .PP
 259 A \fB\s-1BN_GENCB\s0\fR structure should be created through a call to \fBBN_GENCB_new()\fR,
 260 and freed through a call to \fBBN_GENCB_free()\fR.
 261 .PP
 262 For \*(L"new\*(R" style callbacks a \s-1BN_GENCB\s0 structure should be initialised with a
 263 call to \fBBN_GENCB_set()\fR, where \fBgencb\fR is a \fB\s-1BN_GENCB\s0 *\fR, \fBcallback\fR is of
 264 type \fBint (*callback)(int, int, \s-1BN_GENCB\s0 *)\fR and \fBcb_arg\fR is a \fBvoid *\fR.
 265 \&\*(L"Old\*(R" style callbacks are the same except they are initialised with a call
 266 to \fBBN_GENCB_set_old()\fR and \fBcallback\fR is of type
 267 \&\fBvoid (*callback)(int, int, void *)\fR.
 268 .PP
 269 A callback is invoked through a call to \fBBN_GENCB_call\fR. This will check
 270 the type of the callback and will invoke \fBcallback(a, b, gencb)\fR for new
 271 style callbacks or \fBcallback(a, b, cb_arg)\fR for old style.
 272 .PP
 273 It is possible to obtain the argument associated with a \s-1BN_GENCB\s0 structure
 274 (set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.
 275 .PP
 276 \&\fBBN_generate_prime()\fR (deprecated) works in the same way as
 277 \&\fBBN_generate_prime_ex()\fR but expects an old-style callback function
 278 directly in the \fBcallback\fR parameter, and an argument to pass to it in
 279 the \fBcb_arg\fR. \fBBN_is_prime()\fR and \fBBN_is_prime_fasttest()\fR
 280 can similarly be compared to \fBBN_is_prime_ex()\fR and
 281 \&\fBBN_is_prime_fasttest_ex()\fR, respectively.
 282 .SH "RETURN VALUES"
 283 .IX Header "RETURN VALUES"
 284 \&\fBBN_generate_prime_ex()\fR return 1 on success or 0 on error.
 285 .PP
 286 \&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR and
 287 \&\fBBN_is_prime_fasttest()\fR return 0 if the number is composite, 1 if it is
 288 prime with an error probability of less than 0.25^\fBnchecks\fR, and
 289 \&\-1 on error.
 290 .PP
 291 \&\fBBN_generate_prime()\fR returns the prime number on success, \fB\s-1NULL\s0\fR otherwise.
 292 .PP
 293 BN_GENCB_new returns a pointer to a \s-1BN_GENCB\s0 structure on success, or \fB\s-1NULL\s0\fR
 294 otherwise.
 295 .PP
 296 BN_GENCB_get_arg returns the argument previously associated with a \s-1BN_GENCB\s0
 297 structure.
 298 .PP
 299 Callback functions should return 1 on success or 0 on error.
 300 .PP
 301 The error codes can be obtained by \fBERR_get_error\fR\|(3).
 302 .SH "REMOVED FUNCTIONALITY"
 303 .IX Header "REMOVED FUNCTIONALITY"
 304 As of OpenSSL 1.1.0 it is no longer possible to create a \s-1BN_GENCB\s0 structure
 305 directly, as in:
 306 .PP
 307 .Vb 1
 308 \& BN_GENCB callback;
 309 .Ve
 310 .PP
 311 Instead applications should create a \s-1BN_GENCB\s0 structure using BN_GENCB_new:
 312 .PP
 313 .Vb 6
 314 \& BN_GENCB *callback;
 315 \& callback = BN_GENCB_new();
 316 \& if (!callback)
 317 \&     /* error */
 318 \& ...
 319 \& BN_GENCB_free(callback);
 320 .Ve
 321 .SH "SEE ALSO"
 322 .IX Header "SEE ALSO"
 323 \&\fBDH_generate_parameters\fR\|(3), \fBDSA_generate_parameters\fR\|(3),
 324 \&\fBRSA_generate_key\fR\|(3), \fBERR_get_error\fR\|(3), \fBRAND_bytes\fR\|(3),
 325 \&\s-1\fBRAND\s0\fR\|(7)
 326 .SH "HISTORY"
 327 .IX Header "HISTORY"
 328 The \fBBN_GENCB_new()\fR, \fBBN_GENCB_free()\fR,
 329 and \fBBN_GENCB_get_arg()\fR functions were added in OpenSSL 1.1.0.
 330 .SH "COPYRIGHT"
 331 .IX Header "COPYRIGHT"
 332 Copyright 2000\-2019 The OpenSSL Project Authors. All Rights Reserved.
 333 .PP
 334 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 335 this file except in compliance with the License.  You can obtain a copy
 336 in the file \s-1LICENSE\s0 in the source distribution or at
 337 <https://www.openssl.org/source/license.html>.