secure/lib/libcrypto/man/BN_generate_prime.3

   1 .\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
   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-02-26" "1.1.1b" "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.
 191 If \fBret\fR is not \fB\s-1NULL\s0\fR, it will be used to store the number.
 192 .PP
 193 If \fBcb\fR is not \fB\s-1NULL\s0\fR, it is used as follows:
 194 .IP "\(bu" 2
 195 \&\fBBN_GENCB_call(cb, 0, i)\fR is called after generating the i\-th
 196 potential prime number.
 197 .IP "\(bu" 2
 198 While the number is being tested for primality,
 199 \&\fBBN_GENCB_call(cb, 1, j)\fR is called as described below.
 200 .IP "\(bu" 2
 201 When a prime has been found, \fBBN_GENCB_call(cb, 2, i)\fR is called.
 202 .IP "\(bu" 2
 203 The callers of \fBBN_generate_prime_ex()\fR may call \fBBN_GENCB_call(cb, i, j)\fR with
 204 other values as described in their respective man pages; see \*(L"\s-1SEE ALSO\*(R"\s0.
 205 .PP
 206 The prime may have to fulfill additional requirements for use in
 207 Diffie-Hellman key exchange:
 208 .PP
 209 If \fBadd\fR is not \fB\s-1NULL\s0\fR, the prime will fulfill the condition p % \fBadd\fR
 210 == \fBrem\fR (p % \fBadd\fR == 1 if \fBrem\fR == \fB\s-1NULL\s0\fR) in order to suit a given
 211 generator.
 212 .PP
 213 If \fBsafe\fR is true, it will be a safe prime (i.e. a prime p so
 214 that (p\-1)/2 is also prime).
 215 .PP
 216 The \s-1PRNG\s0 must be seeded prior to calling \fBBN_generate_prime_ex()\fR.
 217 The prime number generation has a negligible error probability.
 218 .PP
 219 \&\fBBN_is_prime_ex()\fR and \fBBN_is_prime_fasttest_ex()\fR test if the number \fBp\fR is
 220 prime.  The following tests are performed until one of them shows that
 221 \&\fBp\fR is composite; if \fBp\fR passes all these tests, it is considered
 222 prime.
 223 .PP
 224 \&\fBBN_is_prime_fasttest_ex()\fR, when called with \fBdo_trial_division == 1\fR,
 225 first attempts trial division by a number of small primes;
 226 if no divisors are found by this test and \fBcb\fR is not \fB\s-1NULL\s0\fR,
 227 \&\fBBN_GENCB_call(cb, 1, \-1)\fR is called.
 228 If \fBdo_trial_division == 0\fR, this test is skipped.
 229 .PP
 230 Both \fBBN_is_prime_ex()\fR and \fBBN_is_prime_fasttest_ex()\fR perform a Miller-Rabin
 231 probabilistic primality test with \fBnchecks\fR iterations. If
 232 \&\fBnchecks == BN_prime_checks\fR, a number of iterations is used that
 233 yields a false positive rate of at most 2^\-64 for random input.
 234 The error rate depends on the size of the prime and goes down for bigger primes.
 235 The rate is 2^\-80 starting at 308 bits, 2^\-112 at 852 bits, 2^\-128 at 1080 bits,
 236 2^\-192 at 3747 bits and 2^\-256 at 6394 bits.
 237 .PP
 238 When the source of the prime is not random or not trusted, the number
 239 of checks needs to be much higher to reach the same level of assurance:
 240 It should equal half of the targeted security level in bits (rounded up to the
 241 next integer if necessary).
 242 For instance, to reach the 128 bit security level, \fBnchecks\fR should be set to
 243 64.
 244 .PP
 245 If \fBcb\fR is not \fB\s-1NULL\s0\fR, \fBBN_GENCB_call(cb, 1, j)\fR is called
 246 after the j\-th iteration (j = 0, 1, ...). \fBctx\fR is a
 247 pre-allocated \fB\s-1BN_CTX\s0\fR (to save the overhead of allocating and
 248 freeing the structure in a loop), or \fB\s-1NULL\s0\fR.
 249 .PP
 250 \&\fBBN_GENCB_call()\fR calls the callback function held in the \fB\s-1BN_GENCB\s0\fR structure
 251 and passes the ints \fBa\fR and \fBb\fR as arguments. There are two types of
 252 \&\fB\s-1BN_GENCB\s0\fR structure that are supported: \*(L"new\*(R" style and \*(L"old\*(R" style. New
 253 programs should prefer the \*(L"new\*(R" style, whilst the \*(L"old\*(R" style is provided
 254 for backwards compatibility purposes.
 255 .PP
 256 A \fB\s-1BN_GENCB\s0\fR structure should be created through a call to \fBBN_GENCB_new()\fR,
 257 and freed through a call to \fBBN_GENCB_free()\fR.
 258 .PP
 259 For \*(L"new\*(R" style callbacks a \s-1BN_GENCB\s0 structure should be initialised with a
 260 call to \fBBN_GENCB_set()\fR, where \fBgencb\fR is a \fB\s-1BN_GENCB\s0 *\fR, \fBcallback\fR is of
 261 type \fBint (*callback)(int, int, \s-1BN_GENCB\s0 *)\fR and \fBcb_arg\fR is a \fBvoid *\fR.
 262 \&\*(L"Old\*(R" style callbacks are the same except they are initialised with a call
 263 to \fBBN_GENCB_set_old()\fR and \fBcallback\fR is of type
 264 \&\fBvoid (*callback)(int, int, void *)\fR.
 265 .PP
 266 A callback is invoked through a call to \fBBN_GENCB_call\fR. This will check
 267 the type of the callback and will invoke \fBcallback(a, b, gencb)\fR for new
 268 style callbacks or \fBcallback(a, b, cb_arg)\fR for old style.
 269 .PP
 270 It is possible to obtain the argument associated with a \s-1BN_GENCB\s0 structure
 271 (set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.
 272 .PP
 273 \&\fBBN_generate_prime()\fR (deprecated) works in the same way as
 274 \&\fBBN_generate_prime_ex()\fR but expects an old-style callback function
 275 directly in the \fBcallback\fR parameter, and an argument to pass to it in
 276 the \fBcb_arg\fR. \fBBN_is_prime()\fR and \fBBN_is_prime_fasttest()\fR
 277 can similarly be compared to \fBBN_is_prime_ex()\fR and
 278 \&\fBBN_is_prime_fasttest_ex()\fR, respectively.
 279 .SH "RETURN VALUES"
 280 .IX Header "RETURN VALUES"
 281 \&\fBBN_generate_prime_ex()\fR return 1 on success or 0 on error.
 282 .PP
 283 \&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR and
 284 \&\fBBN_is_prime_fasttest()\fR return 0 if the number is composite, 1 if it is
 285 prime with an error probability of less than 0.25^\fBnchecks\fR, and
 286 \&\-1 on error.
 287 .PP
 288 \&\fBBN_generate_prime()\fR returns the prime number on success, \fB\s-1NULL\s0\fR otherwise.
 289 .PP
 290 BN_GENCB_new returns a pointer to a \s-1BN_GENCB\s0 structure on success, or \fB\s-1NULL\s0\fR
 291 otherwise.
 292 .PP
 293 BN_GENCB_get_arg returns the argument previously associated with a \s-1BN_GENCB\s0
 294 structure.
 295 .PP
 296 Callback functions should return 1 on success or 0 on error.
 297 .PP
 298 The error codes can be obtained by \fBERR_get_error\fR\|(3).
 299 .SH "REMOVED FUNCTIONALITY"
 300 .IX Header "REMOVED FUNCTIONALITY"
 301 As of OpenSSL 1.1.0 it is no longer possible to create a \s-1BN_GENCB\s0 structure
 302 directly, as in:
 303 .PP
 304 .Vb 1
 305 \& BN_GENCB callback;
 306 .Ve
 307 .PP
 308 Instead applications should create a \s-1BN_GENCB\s0 structure using BN_GENCB_new:
 309 .PP
 310 .Vb 6
 311 \& BN_GENCB *callback;
 312 \& callback = BN_GENCB_new();
 313 \& if (!callback)
 314 \&     /* error */
 315 \& ...
 316 \& BN_GENCB_free(callback);
 317 .Ve
 318 .SH "SEE ALSO"
 319 .IX Header "SEE ALSO"
 320 \&\fBDH_generate_parameters\fR\|(3), \fBDSA_generate_parameters\fR\|(3),
 321 \&\fBRSA_generate_key\fR\|(3), \fBERR_get_error\fR\|(3), \fBRAND_bytes\fR\|(3)
 322 .SH "HISTORY"
 323 .IX Header "HISTORY"
 324 The \fBBN_GENCB_new()\fR, \fBBN_GENCB_free()\fR,
 325 and \fBBN_GENCB_get_arg()\fR functions were added in OpenSSL 1.1.0.
 326 .SH "COPYRIGHT"
 327 .IX Header "COPYRIGHT"
 328 Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
 329 .PP
 330 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 331 this file except in compliance with the License.  You can obtain a copy
 332 in the file \s-1LICENSE\s0 in the source distribution or at
 333 <https://www.openssl.org/source/license.html>.