lib/libcrypto/man/get_rfc3526_prime_8192.3

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