lib/libcrypto/man/get_rfc3526_prime_8192.3

   1 .\" $OpenBSD: get_rfc3526_prime_8192.3,v 1.4 2018/03/23 23:18:17 schwarze Exp $
   2 .\" checked up to: OpenSSL DH_get_1024_160 99d63d46 Oct 26 13:56:48 2016 -0400
   3 .\"
   4 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate: March 23 2018 $
  19 .Dt GET_RFC3526_PRIME_8192 3
  20 .Os
  21 .Sh NAME
  22 .Nm get_rfc2409_prime_768 ,
  23 .Nm get_rfc2409_prime_1024 ,
  24 .Nm get_rfc3526_prime_1536 ,
  25 .Nm get_rfc3526_prime_2048 ,
  26 .Nm get_rfc3526_prime_3072 ,
  27 .Nm get_rfc3526_prime_4096 ,
  28 .Nm get_rfc3526_prime_6144 ,
  29 .Nm get_rfc3526_prime_8192 ,
  30 .Nm BN_get_rfc2409_prime_768 ,
  31 .Nm BN_get_rfc2409_prime_1024 ,
  32 .Nm BN_get_rfc3526_prime_2048 ,
  33 .Nm BN_get_rfc3526_prime_3072 ,
  34 .Nm BN_get_rfc3526_prime_4096 ,
  35 .Nm BN_get_rfc3526_prime_6144 ,
  36 .Nm BN_get_rfc3526_prime_8192
  37 .Nd standard moduli for Diffie-Hellmann key exchange
  38 .Sh SYNOPSIS
  39 .In openssl/bn.h
  40 .Ft BIGNUM *
  41 .Fn get_rfc2409_prime_768 "BIGNUM *bn"
  42 .Ft BIGNUM *
  43 .Fn get_rfc2409_prime_1024 "BIGNUM *bn"
  44 .Ft BIGNUM *
  45 .Fn get_rfc3526_prime_1536 "BIGNUM *bn"
  46 .Ft BIGNUM *
  47 .Fn get_rfc3526_prime_2048 "BIGNUM *bn"
  48 .Ft BIGNUM *
  49 .Fn get_rfc3526_prime_3072 "BIGNUM *bn"
  50 .Ft BIGNUM *
  51 .Fn get_rfc3526_prime_4096 "BIGNUM *bn"
  52 .Ft BIGNUM *
  53 .Fn get_rfc3526_prime_6144 "BIGNUM *bn"
  54 .Ft BIGNUM *
  55 .Fn get_rfc3526_prime_8192 "BIGNUM *bn"
  56 .Ft BIGNUM *
  57 .Fn BN_get_rfc2409_prime_768 "BIGNUM *bn"
  58 .Ft BIGNUM *
  59 .Fn BN_get_rfc2409_prime_1024 "BIGNUM *bn"
  60 .Ft BIGNUM *
  61 .Fn BN_get_rfc3526_prime_1536 "BIGNUM *bn"
  62 .Ft BIGNUM *
  63 .Fn BN_get_rfc3526_prime_2048 "BIGNUM *bn"
  64 .Ft BIGNUM *
  65 .Fn BN_get_rfc3526_prime_3072 "BIGNUM *bn"
  66 .Ft BIGNUM *
  67 .Fn BN_get_rfc3526_prime_4096 "BIGNUM *bn"
  68 .Ft BIGNUM *
  69 .Fn BN_get_rfc3526_prime_6144 "BIGNUM *bn"
  70 .Ft BIGNUM *
  71 .Fn BN_get_rfc3526_prime_8192 "BIGNUM *bn"
  72 .Sh DESCRIPTION
  73 Each of these functions returns one specific constant Sophie Germain
  74 prime number
  75 .Fa p .
  76 The names with the prefix
  77 .Sq BN_
  78 are aliases for the names without that prefix.
  79 .Pp
  80 If
  81 .Fa bn
  82 is
  83 .Dv NULL ,
  84 a new
  85 .Vt BIGNUM
  86 object is created and returned.
  87 Otherwise, the number is stored in
  88 .Pf * Fa bn
  89 and
  90 .Fa bn
  91 is returned.
  92 .Pp
  93 All these numbers are of the form
  94 .Pp
  95 .EQ
  96 p = 2 sup s - 2 sup left ( s - 64 right ) - 1 + 2 sup 64 *
  97 left { left [ 2 sup left ( s - 130 right ) pi right ] + offset right }
  98 delim $$
  99 .EN
 100 .Pp
 101 where
 102 .Ar s
 103 is the size of the binary representation of the number in bits
 104 and appears at the end of the function names.
 105 As long as the offset is sufficiently small, the above form assures
 106 that the top and bottom 64 bits of each number are all 1.
 107 .Pp
 108 The offsets are defined in the standards as follows:
 109 .Bl -column 16n 8n -offset indent
 110 .It size Ar s Ta Ar offset
 111 .It Ta
 112 .It \ 768 = 3 * 2^8  Ta  149686
 113 .It 1024 = 2 * 2^9  Ta  129093
 114 .It 1536 = 3 * 2^9  Ta  741804
 115 .It 2048 = 2 * 2^10 Ta  124476
 116 .It 3072 = 3 * 2^10 Ta 1690314
 117 .It 4096 = 2 * 2^11 Ta  240904
 118 .It 6144 = 3 * 2^11 Ta  929484
 119 .It 8192 = 2 * 2^12 Ta 4743158
 120 .El
 121 .Pp
 122 For each of these prime numbers, the finite group of natural numbers
 123 smaller than
 124 .Fa p ,
 125 where the group operation is defined as multiplication modulo
 126 .Fa p ,
 127 is used for Diffie-Hellmann key exchange.
 128 The first two of these groups are called the First Oakley Group and
 129 the Second Oakley Group.
 130 Obiviously, all these groups are cyclic groups of order
 131 .Fa p ,
 132 respectively, and the numbers returned by these functions are not
 133 secrets.
 134 .Sh RETURN VALUES
 135 If memory allocation fails, these functions return
 136 .Dv NULL .
 137 That can happen even if
 138 .Fa bn
 139 is not
 140 .Dv NULL .
 141 .Sh SEE ALSO
 142 .Xr BN_mod_exp 3 ,
 143 .Xr BN_new 3 ,
 144 .Xr BN_set_flags 3 ,
 145 .Xr DH_new 3
 146 .Sh STANDARDS
 147 RFC 2409, "The Internet Key Exchange (IKE)", defines the Oakley Groups.
 148 .Pp
 149 RFC 2412, "The OAKLEY Key Determination Protocol", contains additional
 150 information about these numbers.
 151 .Pp
 152 RFC 3526, "More Modular Exponential (MODP) Diffie-Hellman groups
 153 for Internet Key Exchange (IKE)", defines the other six numbers.
 154 .Sh HISTORY
 155 .Fn get_rfc2409_prime_768 ,
 156 .Fn get_rfc2409_prime_1024 ,
 157 .Fn get_rfc3526_prime_1536 ,
 158 .Fn get_rfc3526_prime_2048 ,
 159 .Fn get_rfc3526_prime_3072 ,
 160 .Fn get_rfc3526_prime_4096 ,
 161 .Fn get_rfc3526_prime_6144 ,
 162 and
 163 .Fn get_rfc3526_prime_8192
 164 first appeared in OpenSSL 0.9.8a and have been available since
 165 .Ox 4.5 .
 166 .Pp
 167 The
 168 .Sy BN_
 169 aliases first appeared in OpenSSL 1.1.0 and have been available since
 170 .Ox 6.3 .
 171 .Sh CAVEATS
 172 As all the memory needed for storing the numbers is dynamically
 173 allocated, the
 174 .Dv BN_FLG_STATIC_DATA
 175 flag is not set on the returned
 176 .Vt BIGNUM
 177 objects.
 178 So be careful to not change the returned numbers.