1.\" $OpenBSD: d2i_DSAPublicKey.3,v 1.8 2016/12/25 14:38:55 schwarze 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: December 25 2016 $ 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 DSAparams_dup , 73.Nm d2i_DSA_SIG , 74.Nm i2d_DSA_SIG 75.Nd decode and encode DSA keys 76.Sh SYNOPSIS 77.In openssl/dsa.h 78.Ft DSA * 79.Fo d2i_DSAPublicKey 80.Fa "DSA **val_out" 81.Fa "const unsigned char **der_in" 82.Fa "long length" 83.Fc 84.Ft int 85.Fo i2d_DSAPublicKey 86.Fa "const DSA *val_in" 87.Fa "unsigned char **der_out" 88.Fc 89.Ft DSA * 90.Fo d2i_DSA_PUBKEY 91.Fa "DSA **val_out" 92.Fa "const unsigned char **der_in" 93.Fa "long length" 94.Fc 95.Ft int 96.Fo i2d_DSA_PUBKEY 97.Fa "const DSA *val_in" 98.Fa "unsigned char **der_out" 99.Fc 100.Ft DSA * 101.Fo d2i_DSA_PUBKEY_bio 102.Fa "BIO *in_bio" 103.Fa "DSA **val_out" 104.Fc 105.Ft DSA * 106.Fo d2i_DSA_PUBKEY_fp 107.Fa "FILE *in_fp" 108.Fa "DSA **val_out" 109.Fc 110.Ft int 111.Fo i2d_DSA_PUBKEY_bio 112.Fa "BIO *out_bio" 113.Fa "DSA *val_in" 114.Fc 115.Ft int 116.Fo i2d_DSA_PUBKEY_fp 117.Fa "FILE *out_fp" 118.Fa "DSA *val_in" 119.Fc 120.Ft DSA * 121.Fo d2i_DSAPrivateKey 122.Fa "DSA **val_out" 123.Fa "const unsigned char **der_in" 124.Fa "long length" 125.Fc 126.Ft int 127.Fo i2d_DSAPrivateKey 128.Fa "const DSA *val_in" 129.Fa "unsigned char **der_out" 130.Fc 131.Ft DSA * 132.Fo d2i_DSAPrivateKey_bio 133.Fa "BIO *in_bio" 134.Fa "DSA **val_out" 135.Fc 136.Ft DSA * 137.Fo d2i_DSAPrivateKey_fp 138.Fa "FILE *in_fp" 139.Fa "DSA **val_out" 140.Fc 141.Ft int 142.Fo i2d_DSAPrivateKey_bio 143.Fa "BIO *out_bio" 144.Fa "DSA *val_in" 145.Fc 146.Ft int 147.Fo i2d_DSAPrivateKey_fp 148.Fa "FILE *out_fp" 149.Fa "DSA *val_in" 150.Fc 151.Ft DSA * 152.Fo d2i_DSAparams 153.Fa "DSA **val_out" 154.Fa "const unsigned char **der_in" 155.Fa "long length" 156.Fc 157.Ft int 158.Fo i2d_DSAparams 159.Fa "const DSA *val_in" 160.Fa "unsigned char **der_out" 161.Fc 162.Ft DSA * 163.Fo DSAparams_dup 164.Fa "DSA *val_in" 165.Fc 166.Ft DSA_SIG * 167.Fo d2i_DSA_SIG 168.Fa "DSA_SIG **val_out" 169.Fa "const unsigned char **der_in" 170.Fa "long length" 171.Fc 172.Ft int 173.Fo i2d_DSA_SIG 174.Fa "const DSA_SIG *val_in" 175.Fa "unsigned char **der_out" 176.Fc 177.Sh DESCRIPTION 178These functions decode and encode DSA keys and parameters. 179For details about the semantics, examples, caveats, and bugs, see 180.Xr ASN1_item_d2i 3 . 181.Pp 182.Fn d2i_DSAPublicKey 183and 184.Fn i2d_DSAPublicKey 185decode and encode the DSA public key components using a non-standard 186format, so consider using 187.Fn d2i_DSA_PUBKEY 188and 189.Fn i2d_DSA_PUBKEY 190instead. 191The actual data encoded depends on the value of 192.Fa val_in->write_params . 193If 194.Fa val_in->write_params 195is zero, only the 196.Fa val_in->pub_key 197field is encoded as an ASN.1 INTEGER. 198If 199.Fa val_in->write_params 200is 1, then a SEQUENCE consisting of the 201.Fa val_in->p , 202.Fa val_in->q , 203.Fa val_in->g , 204and 205.Fa val_in->pub_key 206fields is encoded. 207.Pp 208.Fn d2i_DSA_PUBKEY 209and 210.Fn i2d_DSA_PUBKEY 211decode and encode a DSA public key using an ASN.1 212.Vt SubjectPublicKeyInfo 213structure defined in RFC 5280 section 4.1 214and documented in 215.Xr X509_PUBKEY_new 3 . 216.Fn d2i_DSA_PUBKEY_bio , 217.Fn d2i_DSA_PUBKEY_fp , 218.Fn i2d_DSA_PUBKEY_bio , 219and 220.Fn i2d_DSA_PUBKEY_fp 221are similar except that they decode or encode using a 222.Vt BIO 223or 224.Vt FILE 225pointer. 226.Pp 227.Fn d2i_DSAPrivateKey 228and 229.Fn i2d_DSAPrivateKey 230decode and encode the DSA private key components. 231The 232.Vt DSA 233object passed to the private key encoding functions should have all 234the private key components present. 235These functions use a non-standard structure consisting of a 236SEQUENCE containing the 237.Fa val_in->p , 238.Fa val_in->q , 239.Fa val_in->g , 240.Fa val_in->pub_key , 241and 242.Fa val_in->priv_key 243fields. 244This data format is unencrypted. 245For private key security when writing private keys to files, 246consider using 247.Xr PEM_write_DSAPrivateKey 3 248instead. 249The 250.Fn d2i_DSAPrivateKey_bio , 251.Fn d2i_DSAPrivateKey_fp , 252.Fn i2d_DSAPrivateKey_bio , 253and 254.Fn i2d_DSAPrivateKey_fp 255are similar except that they decode or encode using a 256.Vt BIO 257or 258.Vt FILE 259pointer. 260.Pp 261.Fn d2i_DSAparams 262and 263.Fn i2d_DSAparams 264decode and encode the DSA parameters using an ASN.1 265.Vt Dss-Parms 266structure defined in RFC 3279 section 2.3.2 267and used for the parameters field of the ASN.1 268.Vt AlgorithmIdentifier 269structure defined in RFC 5280 section 4.1.1.2. 270.Pp 271.Fn DSAparams_dup 272allocates and initializes an empty 273.Vt DSA 274object and copies the DSA parameters from 275.Fa val_in 276to it by calling 277.Fn i2d_DSAparams 278and 279.Fn d2i_DSAparams . 280If a private or public key are present in 281.Fa val_in , 282they are not copied. 283.Pp 284.Fn d2i_DSA_SIG 285and 286.Fn i2d_DSA_SIG 287decode and encode a DSA signature using an ASN.1 288.Vt Dss-Sig-Value 289structure as defined in RFC 3279 section 2.2.2 290and used for the signatureValue field of the ASN.1 291.Vt Certificate 292structure described in RFC 5280 sections 4.1.1.3 and 5.1.1.3. 293.Sh RETURN VALUES 294.Fn d2i_DSAPublicKey , 295.Fn d2i_DSA_PUBKEY , 296.Fn d2i_DSA_PUBKEY_bio , 297.Fn d2i_DSA_PUBKEY_fp , 298.Fn d2i_DSAPrivateKey , 299.Fn d2i_DSAPrivateKey_bio , 300.Fn d2i_DSAPrivateKey_fp , 301.Fn d2i_DSAparams , 302and 303.Fn DSAparams_dup 304return a valid 305.Vt DSA 306object or 307.Dv NULL 308if an error occurs. 309.Pp 310.Fn d2i_DSA_SIG 311returns a valid 312.Vt DSA_SIG 313object or 314.Dv NULL 315if an error occurs. 316.Sh SEE ALSO 317.Xr ASN1_item_d2i 3 , 318.Xr DSA_new 3 , 319.Xr DSA_SIG_new 3 , 320.Xr EVP_PKEY_set1_DSA 3 , 321.Xr PEM_write_DSAPrivateKey 3 , 322.Xr X509_PUBKEY_new 3 323.Sh STANDARDS 324RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 325Certificate Revocation List (CRL) Profile, 326section 4.1: Basic Certificate Fields 327.Pp 328RFC 3279: Algorithms and Identifiers for the Internet X.509 Public 329Key Infrastructure Certificate and Certificate Revocation List (CRL) 330Profile: 331.Bl -dash -compact 332.It 333section 2.2.2: DSA Signature Algorithm 334.It 335section 2.3.2: DSA Signature Keys 336.El 337