1.\" $OpenBSD: BN_get_rfc3526_prime_8192.3,v 1.1 2023/07/20 16:26:40 tb 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: July 20 2023 $ 19.Dt BN_GET_RFC3526_PRIME_8192 3 20.Os 21.Sh NAME 22.Nm BN_get_rfc2409_prime_768 , 23.Nm BN_get_rfc2409_prime_1024 , 24.Nm BN_get_rfc3526_prime_1536 , 25.Nm BN_get_rfc3526_prime_2048 , 26.Nm BN_get_rfc3526_prime_3072 , 27.Nm BN_get_rfc3526_prime_4096 , 28.Nm BN_get_rfc3526_prime_6144 , 29.Nm BN_get_rfc3526_prime_8192 30.Nd standard moduli for Diffie-Hellman key exchange 31.Sh SYNOPSIS 32.In openssl/bn.h 33.Ft BIGNUM * 34.Fn BN_get_rfc2409_prime_768 "BIGNUM *bn" 35.Ft BIGNUM * 36.Fn BN_get_rfc2409_prime_1024 "BIGNUM *bn" 37.Ft BIGNUM * 38.Fn BN_get_rfc3526_prime_1536 "BIGNUM *bn" 39.Ft BIGNUM * 40.Fn BN_get_rfc3526_prime_2048 "BIGNUM *bn" 41.Ft BIGNUM * 42.Fn BN_get_rfc3526_prime_3072 "BIGNUM *bn" 43.Ft BIGNUM * 44.Fn BN_get_rfc3526_prime_4096 "BIGNUM *bn" 45.Ft BIGNUM * 46.Fn BN_get_rfc3526_prime_6144 "BIGNUM *bn" 47.Ft BIGNUM * 48.Fn BN_get_rfc3526_prime_8192 "BIGNUM *bn" 49.Sh DESCRIPTION 50Each of these functions returns one specific constant Sophie Germain 51prime number 52.Fa p . 53.Pp 54If 55.Fa bn 56is 57.Dv NULL , 58a new 59.Vt BIGNUM 60object is created and returned. 61Otherwise, the number is stored in 62.Pf * Fa bn 63and 64.Fa bn 65is returned. 66.Pp 67All these numbers are of the form 68.Pp 69.EQ 70p = 2 sup s - 2 sup left ( s - 64 right ) - 1 + 2 sup 64 * 71left { left [ 2 sup left ( s - 130 right ) pi right ] + offset right } 72delim $$ 73.EN 74.Pp 75where 76.Ar s 77is the size of the binary representation of the number in bits 78and appears at the end of the function names. 79As long as the offset is sufficiently small, the above form assures 80that the top and bottom 64 bits of each number are all 1. 81.Pp 82The offsets are defined in the standards as follows: 83.Bl -column "8192 = 2 * 2^12" "4743158" -offset indent 84.It size Ar s Ta Ar offset 85.It Ta 86.It \ 768 = 3 * 2^8 Ta 149686 87.It 1024 = 2 * 2^9 Ta 129093 88.It 1536 = 3 * 2^9 Ta 741804 89.It 2048 = 2 * 2^10 Ta 124476 90.It 3072 = 3 * 2^10 Ta 1690314 91.It 4096 = 2 * 2^11 Ta 240904 92.It 6144 = 3 * 2^11 Ta 929484 93.It 8192 = 2 * 2^12 Ta 4743158 94.El 95.Pp 96For each of these prime numbers, the finite group of natural numbers 97smaller than 98.Fa p , 99where the group operation is defined as multiplication modulo 100.Fa p , 101is used for Diffie-Hellman key exchange. 102The first two of these groups are called the First Oakley Group and 103the Second Oakley Group. 104Obviously, all these groups are cyclic groups of order 105.Fa p , 106respectively, and the numbers returned by these functions are not 107secrets. 108.Sh RETURN VALUES 109If memory allocation fails, these functions return 110.Dv NULL . 111That can happen even if 112.Fa bn 113is not 114.Dv NULL . 115.Sh SEE ALSO 116.Xr BN_mod_exp 3 , 117.Xr BN_new 3 , 118.Xr BN_set_flags 3 , 119.Xr DH_new 3 120.Sh STANDARDS 121RFC 2409, "The Internet Key Exchange (IKE)", defines the Oakley Groups. 122.Pp 123RFC 2412, "The OAKLEY Key Determination Protocol", contains additional 124information about these numbers. 125.Pp 126RFC 3526, "More Modular Exponential (MODP) Diffie-Hellman groups 127for Internet Key Exchange (IKE)", defines the other six numbers. 128.Sh HISTORY 129.Fn BN_get_rfc2409_prime_768 , 130.Fn BN_get_rfc2409_prime_1024 , 131.Fn BN_get_rfc3526_prime_1536 , 132.Fn BN_get_rfc3526_prime_2048 , 133.Fn BN_get_rfc3526_prime_3072 , 134.Fn BN_get_rfc3526_prime_4096 , 135.Fn BN_get_rfc3526_prime_6144 , 136and 137.Fn BN_get_rfc3526_prime_8192 138first appeared in OpenSSL 1.1.0 and have been available since 139.Ox 6.3 . 140The same functions without 141.Sy BN_ 142prefix first appeared in OpenSSL 0.9.8a and 143.Ox 4.5 ; 144they were removed in 145.Ox 7.4 . 146.Sh CAVEATS 147As all the memory needed for storing the numbers is dynamically 148allocated, the 149.Dv BN_FLG_STATIC_DATA 150flag is not set on the returned 151.Vt BIGNUM 152objects. 153So be careful to not change the returned numbers. 154