1.\" $OpenBSD: d2i_DSAPublicKey.3,v 1.14 2018/08/26 17:03:32 tb Exp $ 2.\" OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2002, 2003, 2013, 2015, 2016 The OpenSSL Project. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: August 26 2018 $ 53.Dt D2I_DSAPUBLICKEY 3 54.Os 55.Sh NAME 56.Nm d2i_DSAPublicKey , 57.Nm i2d_DSAPublicKey , 58.Nm d2i_DSA_PUBKEY , 59.Nm i2d_DSA_PUBKEY , 60.Nm d2i_DSA_PUBKEY_bio , 61.Nm d2i_DSA_PUBKEY_fp , 62.Nm i2d_DSA_PUBKEY_bio , 63.Nm i2d_DSA_PUBKEY_fp , 64.Nm d2i_DSAPrivateKey , 65.Nm i2d_DSAPrivateKey , 66.Nm d2i_DSAPrivateKey_bio , 67.Nm d2i_DSAPrivateKey_fp , 68.Nm i2d_DSAPrivateKey_bio , 69.Nm i2d_DSAPrivateKey_fp , 70.Nm d2i_DSAparams , 71.Nm i2d_DSAparams , 72.Nm d2i_DSAparams_bio , 73.Nm i2d_DSAparams_bio , 74.Nm d2i_DSAparams_fp , 75.Nm i2d_DSAparams_fp , 76.Nm DSAparams_dup , 77.Nm d2i_DSA_SIG , 78.Nm i2d_DSA_SIG 79.Nd decode and encode DSA keys 80.Sh SYNOPSIS 81.In openssl/dsa.h 82.Ft DSA * 83.Fo d2i_DSAPublicKey 84.Fa "DSA **val_out" 85.Fa "const unsigned char **der_in" 86.Fa "long length" 87.Fc 88.Ft int 89.Fo i2d_DSAPublicKey 90.Fa "const DSA *val_in" 91.Fa "unsigned char **der_out" 92.Fc 93.In openssl/x509.h 94.Ft DSA * 95.Fo d2i_DSA_PUBKEY 96.Fa "DSA **val_out" 97.Fa "const unsigned char **der_in" 98.Fa "long length" 99.Fc 100.Ft int 101.Fo i2d_DSA_PUBKEY 102.Fa "const DSA *val_in" 103.Fa "unsigned char **der_out" 104.Fc 105.Ft DSA * 106.Fo d2i_DSA_PUBKEY_bio 107.Fa "BIO *in_bio" 108.Fa "DSA **val_out" 109.Fc 110.Ft DSA * 111.Fo d2i_DSA_PUBKEY_fp 112.Fa "FILE *in_fp" 113.Fa "DSA **val_out" 114.Fc 115.Ft int 116.Fo i2d_DSA_PUBKEY_bio 117.Fa "BIO *out_bio" 118.Fa "DSA *val_in" 119.Fc 120.Ft int 121.Fo i2d_DSA_PUBKEY_fp 122.Fa "FILE *out_fp" 123.Fa "DSA *val_in" 124.Fc 125.In openssl/dsa.h 126.Ft DSA * 127.Fo d2i_DSAPrivateKey 128.Fa "DSA **val_out" 129.Fa "const unsigned char **der_in" 130.Fa "long length" 131.Fc 132.Ft int 133.Fo i2d_DSAPrivateKey 134.Fa "const DSA *val_in" 135.Fa "unsigned char **der_out" 136.Fc 137.In openssl/x509.h 138.Ft DSA * 139.Fo d2i_DSAPrivateKey_bio 140.Fa "BIO *in_bio" 141.Fa "DSA **val_out" 142.Fc 143.Ft DSA * 144.Fo d2i_DSAPrivateKey_fp 145.Fa "FILE *in_fp" 146.Fa "DSA **val_out" 147.Fc 148.Ft int 149.Fo i2d_DSAPrivateKey_bio 150.Fa "BIO *out_bio" 151.Fa "DSA *val_in" 152.Fc 153.Ft int 154.Fo i2d_DSAPrivateKey_fp 155.Fa "FILE *out_fp" 156.Fa "DSA *val_in" 157.Fc 158.In openssl/dsa.h 159.Ft DSA * 160.Fo d2i_DSAparams 161.Fa "DSA **val_out" 162.Fa "const unsigned char **der_in" 163.Fa "long length" 164.Fc 165.Ft int 166.Fo i2d_DSAparams 167.Fa "const DSA *val_in" 168.Fa "unsigned char **der_out" 169.Fc 170.Ft DSA * 171.Fo d2i_DSAparams_bio 172.Fa "BIO *in_bio" 173.Fa "DSA **val_out" 174.Fc 175.Ft int 176.Fo i2d_DSAparams_bio 177.Fa "BIO *out_bio" 178.Fa "DSA *val_in" 179.Fc 180.Ft DSA * 181.Fo d2i_DSAparams_fp 182.Fa "FILE *in_fp" 183.Fa "DSA **val_out" 184.Fc 185.Ft int 186.Fo i2d_DSAparams_fp 187.Fa FILE *out_fp 188.Fa "DSA *val_in" 189.Fc 190.Ft DSA * 191.Fo DSAparams_dup 192.Fa "DSA *val_in" 193.Fc 194.Ft DSA_SIG * 195.Fo d2i_DSA_SIG 196.Fa "DSA_SIG **val_out" 197.Fa "const unsigned char **der_in" 198.Fa "long length" 199.Fc 200.Ft int 201.Fo i2d_DSA_SIG 202.Fa "const DSA_SIG *val_in" 203.Fa "unsigned char **der_out" 204.Fc 205.Sh DESCRIPTION 206These functions decode and encode DSA keys and parameters. 207For details about the semantics, examples, caveats, and bugs, see 208.Xr ASN1_item_d2i 3 . 209.Pp 210.Fn d2i_DSAPublicKey 211and 212.Fn i2d_DSAPublicKey 213decode and encode the DSA public key components using a non-standard 214format, so consider using 215.Fn d2i_DSA_PUBKEY 216and 217.Fn i2d_DSA_PUBKEY 218instead. 219The actual data encoded depends on the value of 220.Fa val_in->write_params . 221If 222.Fa val_in->write_params 223is zero, only the 224.Fa val_in->pub_key 225field is encoded as an ASN.1 INTEGER. 226If 227.Fa val_in->write_params 228is 1, then a SEQUENCE consisting of the 229.Fa val_in->p , 230.Fa val_in->q , 231.Fa val_in->g , 232and 233.Fa val_in->pub_key 234fields is encoded. 235.Pp 236.Fn d2i_DSA_PUBKEY 237and 238.Fn i2d_DSA_PUBKEY 239decode and encode a DSA public key using an ASN.1 240.Vt SubjectPublicKeyInfo 241structure defined in RFC 5280 section 4.1 242and documented in 243.Xr X509_PUBKEY_new 3 . 244.Fn d2i_DSA_PUBKEY_bio , 245.Fn d2i_DSA_PUBKEY_fp , 246.Fn i2d_DSA_PUBKEY_bio , 247and 248.Fn i2d_DSA_PUBKEY_fp 249are similar except that they decode or encode using a 250.Vt BIO 251or 252.Vt FILE 253pointer. 254.Pp 255.Fn d2i_DSAPrivateKey 256and 257.Fn i2d_DSAPrivateKey 258decode and encode the DSA private key components. 259The 260.Vt DSA 261object passed to the private key encoding functions should have all 262the private key components present. 263These functions use a non-standard structure consisting of a 264SEQUENCE containing the 265.Fa val_in->p , 266.Fa val_in->q , 267.Fa val_in->g , 268.Fa val_in->pub_key , 269and 270.Fa val_in->priv_key 271fields. 272This data format is unencrypted. 273For private key security when writing private keys to files, 274consider using 275.Xr PEM_write_DSAPrivateKey 3 276instead. 277.Fn d2i_DSAPrivateKey_bio , 278.Fn d2i_DSAPrivateKey_fp , 279.Fn i2d_DSAPrivateKey_bio , 280and 281.Fn i2d_DSAPrivateKey_fp 282are similar except that they decode or encode using a 283.Vt BIO 284or 285.Vt FILE 286pointer. 287.Pp 288.Fn d2i_DSAparams 289and 290.Fn i2d_DSAparams 291decode and encode the DSA parameters using an ASN.1 292.Vt Dss-Parms 293structure defined in RFC 3279 section 2.3.2 294and used for the parameters field of the ASN.1 295.Vt AlgorithmIdentifier 296structure defined in RFC 5280 section 4.1.1.2. 297.Fn d2i_DSAparams_bio , 298.Fn i2d_DSAparams_bio , 299.Fn d2i_DSAparams_fp , 300.Fn i2d_DSAparams_fp 301are similar except that they decode or encode using a 302.Vt BIO 303or 304.Vt FILE 305pointer. 306.Pp 307.Fn DSAparams_dup 308allocates and initializes an empty 309.Vt DSA 310object and copies the DSA parameters from 311.Fa val_in 312to it by calling 313.Fn i2d_DSAparams 314and 315.Fn d2i_DSAparams . 316If a private or public key are present in 317.Fa val_in , 318they are not copied. 319.Pp 320.Fn d2i_DSA_SIG 321and 322.Fn i2d_DSA_SIG 323decode and encode a DSA signature using an ASN.1 324.Vt Dss-Sig-Value 325structure as defined in RFC 3279 section 2.2.2 326and used for the signatureValue field of the ASN.1 327.Vt Certificate 328structure described in RFC 5280 sections 4.1.1.3 and 5.1.1.3. 329.Sh RETURN VALUES 330.Fn d2i_DSAPublicKey , 331.Fn d2i_DSA_PUBKEY , 332.Fn d2i_DSA_PUBKEY_bio , 333.Fn d2i_DSA_PUBKEY_fp , 334.Fn d2i_DSAPrivateKey , 335.Fn d2i_DSAPrivateKey_bio , 336.Fn d2i_DSAPrivateKey_fp , 337.Fn d2i_DSAparams , 338.Fn d2i_DSAparams_bio , 339.Fn d2i_DSAparams_fp , 340and 341.Fn DSAparams_dup 342return a valid 343.Vt DSA 344object or 345.Dv NULL 346if an error occurs. 347.Pp 348.Fn d2i_DSA_SIG 349returns a valid 350.Vt DSA_SIG 351object or 352.Dv NULL 353if an error occurs. 354.Sh SEE ALSO 355.Xr ASN1_item_d2i 3 , 356.Xr DSA_new 3 , 357.Xr DSA_SIG_new 3 , 358.Xr EVP_PKEY_set1_DSA 3 , 359.Xr PEM_write_DSAPrivateKey 3 , 360.Xr X509_PUBKEY_new 3 361.Sh STANDARDS 362RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 363Certificate Revocation List (CRL) Profile, 364section 4.1: Basic Certificate Fields 365.Pp 366RFC 3279: Algorithms and Identifiers for the Internet X.509 Public 367Key Infrastructure Certificate and Certificate Revocation List (CRL) 368Profile: 369.Bl -dash -compact 370.It 371section 2.2.2: DSA Signature Algorithm 372.It 373section 2.3.2: DSA Signature Keys 374.El 375.Sh HISTORY 376.Fn d2i_DSAPublicKey , 377.Fn i2d_DSAPublicKey , 378.Fn d2i_DSAPrivateKey , 379and 380.Fn i2d_DSAPrivateKey 381first appeared in SSLeay 0.6.0. 382.Fn d2i_DSAPrivateKey_bio , 383.Fn d2i_DSAPrivateKey_fp , 384.Fn i2d_DSAPrivateKey_bio , 385.Fn i2d_DSAPrivateKey_fp , 386.Fn d2i_DSAparams , 387.Fn i2d_DSAparams , 388.Fn d2i_DSAparams_bio , 389.Fn i2d_DSAparams_bio , 390.Fn d2i_DSAparams_fp , 391.Fn i2d_DSAparams_fp , 392and 393.Fn DSAparams_dup 394first appeared in SSLeay 0.8.0. 395These functions have been available since 396.Ox 2.4 . 397.Pp 398.Fn d2i_DSA_SIG 399and 400.Fn i2d_DSA_SIG 401first appeared in OpenSSL 0.9.3 and have been available since 402.Ox 2.6 . 403.Pp 404.Fn d2i_DSA_PUBKEY , 405.Fn i2d_DSA_PUBKEY , 406.Fn d2i_DSA_PUBKEY_bio , 407.Fn d2i_DSA_PUBKEY_fp , 408.Fn i2d_DSA_PUBKEY_bio , 409and 410.Fn i2d_DSA_PUBKEY_fp 411first appeared in OpenSSL 0.9.5 and have been available since 412.Ox 2.7 . 413