1.\" $OpenBSD: DH_get0_pqg.3,v 1.5 2018/12/21 21:54:48 schwarze 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: December 21 2018 $ 52.Dt DH_GET0_PQG 3 53.Os 54.Sh NAME 55.Nm DH_get0_pqg , 56.Nm DH_set0_pqg , 57.Nm DH_get0_key , 58.Nm DH_set0_key , 59.Nm DH_clear_flags , 60.Nm DH_test_flags , 61.Nm DH_set_flags , 62.Nm DH_get0_engine , 63.Nm DH_set_length 64.Nd get data from and set data in a DH object 65.Sh SYNOPSIS 66.In openssl/dh.h 67.Ft void 68.Fo DH_get0_pqg 69.Fa "const DH *dh" 70.Fa "const BIGNUM **p" 71.Fa "const BIGNUM **q" 72.Fa "const BIGNUM **g" 73.Fc 74.Ft int 75.Fo DH_set0_pqg 76.Fa "DH *dh" 77.Fa "BIGNUM *p" 78.Fa "BIGNUM *q" 79.Fa "BIGNUM *g" 80.Fc 81.Ft void 82.Fo DH_get0_key 83.Fa "const DH *dh" 84.Fa "const BIGNUM **pub_key" 85.Fa "const BIGNUM **priv_key" 86.Fc 87.Ft int 88.Fo DH_set0_key 89.Fa "DH *dh" 90.Fa "BIGNUM *pub_key" 91.Fa "BIGNUM *priv_key" 92.Fc 93.Ft void 94.Fo DH_clear_flags 95.Fa "DH *dh" 96.Fa "int flags" 97.Fc 98.Ft int 99.Fo DH_test_flags 100.Fa "const DH *dh" 101.Fa "int flags" 102.Fc 103.Ft void 104.Fo DH_set_flags 105.Fa "DH *dh" 106.Fa "int flags" 107.Fc 108.Ft ENGINE * 109.Fo DH_get0_engine 110.Fa "DH *d" 111.Fc 112.Ft int 113.Fo DH_set_length 114.Fa "DH *dh" 115.Fa "long length" 116.Fc 117.Sh DESCRIPTION 118A 119.Vt DH 120object contains the parameters 121.Fa p , 122.Fa g , 123and optionally 124.Fa q . 125It also contains a public key 126.Fa pub_key 127and an optional private key 128.Fa priv_key . 129.Pp 130The 131.Fa p , 132.Fa q , 133and 134.Fa g 135parameters can be obtained by calling 136.Fn DH_get0_pqg . 137If the parameters have not yet been set, then 138.Pf * Fa p , 139.Pf * Fa q , 140and 141.Pf * Fa g 142are set to 143.Dv NULL . 144Otherwise, they are set to pointers to the internal representations 145of the values that should not be freed by the application. 146Any of the out parameters 147.Fa p , 148.Fa q , 149and 150.Fa g 151can be 152.Dv NULL , 153in which case no value is returned for that parameter. 154.Pp 155The 156.Fa p , 157.Fa q , 158and 159.Fa g 160values can be set by calling 161.Fn DH_set0_pqg . 162Calling this function transfers the memory management of the values to 163.Fa dh , 164and therefore they should not be freed by the caller. 165The 166.Fa q 167argument may be 168.Dv NULL . 169.Pp 170The 171.Fn DH_get0_key 172function stores pointers to the internal representations 173of the public key in 174.Pf * Fa pub_key 175and to the private key in 176.Pf * Fa priv_key . 177Either may be 178.Dv NULL 179if it has not yet been set. 180If the private key has been set, then the public key must be. 181Any of the out parameters 182.Fa pub_key 183and 184.Fa priv_key 185can be 186.Dv NULL , 187in which case no value is returned for that parameter. 188.Pp 189The public and private key values can be set using 190.Fn DH_set0_key . 191Either parameter may be 192.Dv NULL , 193which means the corresponding 194.Vt DH 195field is left untouched. 196This function transfers the memory management of the key values to 197.Fa dh , 198and therefore they should not be freed by the caller. 199.Pp 200Values retrieved with 201.Fn DH_get0_pqg 202and 203.Fn DH_get0_key 204are owned by the 205.Vt DH 206object and may therefore not be passed to 207.Fn DH_set0_pqg 208or 209.Fn DH_set0_key . 210If needed, duplicate the received values using 211.Xr BN_dup 3 212and pass the duplicates. 213.Pp 214.Fn DH_clear_flags 215clears the specified 216.Fa flags 217in 218.Fa dh . 219.Fn DH_test_flags 220tests the 221.Fa flags 222in 223.Fa dh . 224.Fn DH_set_flags 225sets the 226.Fa flags 227in 228.Fa dh ; 229any flags already set remain set. 230For all three functions, multiple flags can be passed in one call, 231OR'ed together bitwise. 232.Pp 233.Fn DH_set_length 234sets the optional length attribute of 235.Fa dh , 236indicating the length of the secret exponent (private key) in bits. 237If the length attribute is non-zero, it is used, otherwise it is ignored. 238.Sh RETURN VALUES 239.Fn DH_set0_pqg , 240.Fn DH_set0_key , 241and 242.Fn DH_set_length 243return 1 on success or 0 on failure. 244.Pp 245.Fn DH_test_flags 246return those of the given 247.Fa flags 248currently set in 249.Fa dh 250or 0 if none of the given 251.Fa flags 252are set. 253.Pp 254.Fn DH_get0_engine 255returns a pointer to the 256.Vt ENGINE 257used by the 258.Vt DH 259object 260.Fa dh , 261or 262.Dv NULL 263if no engine was set for this object. 264.Sh SEE ALSO 265.Xr DH_generate_key 3 , 266.Xr DH_generate_parameters 3 , 267.Xr DH_new 3 , 268.Xr DH_size 3 , 269.Xr DHparams_print 3 270.Sh HISTORY 271These functions first appeared in OpenSSL 1.1.0 272and have been available since 273.Ox 6.3 . 274