1.\" $OpenBSD: DH_get0_pqg.3,v 1.8 2024/07/21 08:36:43 tb Exp $ 2.\" selective merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 3.\" 4.\" This file was written by Matt Caswell <matt@openssl.org>. 5.\" Copyright (c) 2016, 2018 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: July 21 2024 $ 52.Dt DH_GET0_PQG 3 53.Os 54.Sh NAME 55.Nm DH_get0_pqg , 56.Nm DH_get0_p , 57.Nm DH_get0_q , 58.Nm DH_get0_g , 59.Nm DH_set0_pqg , 60.Nm DH_get0_key , 61.Nm DH_get0_pub_key , 62.Nm DH_get0_priv_key , 63.Nm DH_set0_key , 64.Nm DH_clear_flags , 65.Nm DH_test_flags , 66.Nm DH_set_flags , 67.Nm DH_get0_engine , 68.Nm DH_set_length 69.Nd get data from and set data in a DH object 70.Sh SYNOPSIS 71.In openssl/dh.h 72.Ft void 73.Fo DH_get0_pqg 74.Fa "const DH *dh" 75.Fa "const BIGNUM **p" 76.Fa "const BIGNUM **q" 77.Fa "const BIGNUM **g" 78.Fc 79.Ft "const BIGNUM *" 80.Fo DH_get0_p 81.Fa "const DH *dh" 82.Fc 83.Ft "const BIGNUM *" 84.Fo DH_get0_q 85.Fa "const DH *dh" 86.Fc 87.Ft "const BIGNUM *" 88.Fo DH_get0_g 89.Fa "const DH *dh" 90.Fc 91.Ft int 92.Fo DH_set0_pqg 93.Fa "DH *dh" 94.Fa "BIGNUM *p" 95.Fa "BIGNUM *q" 96.Fa "BIGNUM *g" 97.Fc 98.Ft void 99.Fo DH_get0_key 100.Fa "const DH *dh" 101.Fa "const BIGNUM **pub_key" 102.Fa "const BIGNUM **priv_key" 103.Fc 104.Ft "const BIGNUM *" 105.Fo DH_get0_pub_key 106.Fa "const DH *dh" 107.Fc 108.Ft "const BIGNUM *" 109.Fo DH_get0_priv_key 110.Fa "const DH *dh" 111.Fc 112.Ft int 113.Fo DH_set0_key 114.Fa "DH *dh" 115.Fa "BIGNUM *pub_key" 116.Fa "BIGNUM *priv_key" 117.Fc 118.Ft void 119.Fo DH_clear_flags 120.Fa "DH *dh" 121.Fa "int flags" 122.Fc 123.Ft int 124.Fo DH_test_flags 125.Fa "const DH *dh" 126.Fa "int flags" 127.Fc 128.Ft void 129.Fo DH_set_flags 130.Fa "DH *dh" 131.Fa "int flags" 132.Fc 133.Ft ENGINE * 134.Fo DH_get0_engine 135.Fa "DH *d" 136.Fc 137.Ft int 138.Fo DH_set_length 139.Fa "DH *dh" 140.Fa "long length" 141.Fc 142.Sh DESCRIPTION 143A 144.Vt DH 145object contains the parameters 146.Fa p , 147.Fa g , 148and optionally 149.Fa q . 150It also contains a public key 151.Fa pub_key 152and an optional private key 153.Fa priv_key . 154.Pp 155The 156.Fa p , 157.Fa q , 158and 159.Fa g 160parameters can be obtained by calling 161.Fn DH_get0_pqg . 162If the parameters have not yet been set, then 163.Pf * Fa p , 164.Pf * Fa q , 165and 166.Pf * Fa g 167are set to 168.Dv NULL . 169Otherwise, they are set to pointers to the internal representations 170of the values that should not be freed by the application. 171Any of the out parameters 172.Fa p , 173.Fa q , 174and 175.Fa g 176can be 177.Dv NULL , 178in which case no value is returned for that parameter. 179.Pp 180The 181.Fa p , 182.Fa q , 183and 184.Fa g 185values can be set by calling 186.Fn DH_set0_pqg . 187Calling this function transfers the memory management of the values to 188.Fa dh , 189and therefore they should not be freed by the caller. 190The 191.Fa q 192argument may be 193.Dv NULL . 194.Pp 195The 196.Fn DH_get0_key 197function stores pointers to the internal representations 198of the public key in 199.Pf * Fa pub_key 200and to the private key in 201.Pf * Fa priv_key . 202Either may be 203.Dv NULL 204if it has not yet been set. 205If the private key has been set, then the public key must be. 206Any of the out parameters 207.Fa pub_key 208and 209.Fa priv_key 210can be 211.Dv NULL , 212in which case no value is returned for that parameter. 213.Pp 214The public and private key values can be set using 215.Fn DH_set0_key . 216Either parameter may be 217.Dv NULL , 218which means the corresponding 219.Vt DH 220field is left untouched. 221This function transfers the memory management of the key values to 222.Fa dh , 223and therefore they should not be freed by the caller. 224.Pp 225Values retrieved with 226.Fn DH_get0_pqg 227and 228.Fn DH_get0_key 229are owned by the 230.Vt DH 231object and may therefore not be passed to 232.Fn DH_set0_pqg 233or 234.Fn DH_set0_key . 235If needed, duplicate the received values using 236.Xr BN_dup 3 237and pass the duplicates. 238.Pp 239Any of the values 240.Fa p , 241.Fa q , 242.Fa g , 243.Fa pub_key , 244and 245.Fa priv_key 246can also be retrieved separately by the corresponding functions 247.Fn DH_get0_p , 248.Fn DH_get0_q , 249.Fn DH_get0_g , 250.Fn DH_get0_pub_key , 251and 252.Fn DH_get0_priv_key , 253respectively. 254The pointers are owned by the 255.Vt DH 256object. 257.Pp 258.Fn DH_clear_flags 259clears the specified 260.Fa flags 261in 262.Fa dh . 263.Fn DH_test_flags 264tests the 265.Fa flags 266in 267.Fa dh . 268.Fn DH_set_flags 269sets the 270.Fa flags 271in 272.Fa dh ; 273any flags already set remain set. 274For all three functions, multiple flags can be passed in one call, 275OR'ed together bitwise. 276.Pp 277.Fn DH_set_length 278sets the optional length attribute of 279.Fa dh , 280indicating the length of the secret exponent (private key) in bits. 281If the length attribute is non-zero, it is used, otherwise it is ignored. 282.Sh RETURN VALUES 283+.Fn DH_get0_p , 284+.Fn DH_get0_q , 285+.Fn DH_get0_g , 286+.Fn DH_get0_pub_key , 287+and 288+.Fn DH_get0_priv_key , 289+return a pointer owned by the 290+.Vt DH 291+object if the corresponding value has been set, 292+otherwise they return 293+.Dv NULL . 294.Fn DH_set0_pqg , 295.Fn DH_set0_key , 296and 297.Fn DH_set_length 298return 1 on success or 0 on failure. 299.Pp 300.Fn DH_test_flags 301return those of the given 302.Fa flags 303currently set in 304.Fa dh 305or 0 if none of the given 306.Fa flags 307are set. 308.Pp 309.Fn DH_get0_engine 310always returns 311.Dv NULL . 312.Sh SEE ALSO 313.Xr DH_generate_key 3 , 314.Xr DH_generate_parameters 3 , 315.Xr DH_new 3 , 316.Xr DH_security_bits 3 , 317.Xr DH_size 3 , 318.Xr DHparams_print 3 319.Sh HISTORY 320.Fn DH_get0_pqg , 321.Fn DH_set0_pqg , 322.Fn DH_get0_key , 323.Fn DH_set0_key , 324.Fn DH_clear_flags , 325.Fn DH_test_flags , 326.Fn DH_set_flags , 327.Fn DH_get0_engine , 328and 329.Fn DH_set_length 330first appeared in OpenSSL 1.1.0 331and have been available since 332.Ox 6.3 . 333.Pp 334.Fn DH_get0_p , 335.Fn DH_get0_q , 336.Fn DH_get0_g , 337.Fn DH_get0_pub_key , 338and 339.Fn DH_get0_priv_key 340first appeared in OpenSSL 1.1.1 341and have been available since 342.Ox 7.1 . 343