secure/lib/libcrypto/man/BN_generate_prime.3

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