| blob | 660159b376bdb476ce989b485d756f9dd949677f |
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
178 These functions decode and encode DSA keys and parameters.
179 For details about the semantics, examples, caveats, and bugs, see
180 .Xr ASN1_item_d2i 3 .
181 .Pp
182 .Fn d2i_DSAPublicKey
183 and
184 .Fn i2d_DSAPublicKey
185 decode and encode the DSA public key components using a non-standard
186 format, so consider using
187 .Fn d2i_DSA_PUBKEY
188 and
189 .Fn i2d_DSA_PUBKEY
190 instead.
191 The actual data encoded depends on the value of
192 .Fa val_in->write_params .
193 If
194 .Fa val_in->write_params
195 is zero, only the
196 .Fa val_in->pub_key
197 field is encoded as an ASN.1 INTEGER.
198 If
199 .Fa val_in->write_params
200 is 1, then a SEQUENCE consisting of the
201 .Fa val_in->p ,
202 .Fa val_in->q ,
203 .Fa val_in->g ,
204 and
205 .Fa val_in->pub_key
206 fields is encoded.
207 .Pp
208 .Fn d2i_DSA_PUBKEY
209 and
210 .Fn i2d_DSA_PUBKEY
211 decode and encode a DSA public key using an ASN.1
212 .Vt SubjectPublicKeyInfo
213 structure defined in RFC 5280 section 4.1
214 and 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 ,
219 and
220 .Fn i2d_DSA_PUBKEY_fp
221 are similar except that they decode or encode using a
222 .Vt BIO
223 or
224 .Vt FILE
225 pointer.
226 .Pp
227 .Fn d2i_DSAPrivateKey
228 and
229 .Fn i2d_DSAPrivateKey
230 decode and encode the DSA private key components.
231 The
232 .Vt DSA
233 object passed to the private key encoding functions should have all
234 the private key components present.
235 These functions use a non-standard structure consisting of a
236 SEQUENCE containing the
237 .Fa val_in->p ,
238 .Fa val_in->q ,
239 .Fa val_in->g ,
240 .Fa val_in->pub_key ,
241 and
242 .Fa val_in->priv_key
243 fields.
244 This data format is unencrypted.
245 For private key security when writing private keys to files,
246 consider using
247 .Xr PEM_write_DSAPrivateKey 3
248 instead.
249 The
250 .Fn d2i_DSAPrivateKey_bio ,
251 .Fn d2i_DSAPrivateKey_fp ,
252 .Fn i2d_DSAPrivateKey_bio ,
253 and
254 .Fn i2d_DSAPrivateKey_fp
255 are similar except that they decode or encode using a
256 .Vt BIO
257 or
258 .Vt FILE
259 pointer.
260 .Pp
261 .Fn d2i_DSAparams
262 and
263 .Fn i2d_DSAparams
264 decode and encode the DSA parameters using an ASN.1
265 .Vt Dss-Parms
266 structure defined in RFC 3279 section 2.3.2
267 and used for the parameters field of the ASN.1
268 .Vt AlgorithmIdentifier
269 structure defined in RFC 5280 section 4.1.1.2.
270 .Pp
271 .Fn DSAparams_dup
272 allocates and initializes an empty
273 .Vt DSA
274 object and copies the DSA parameters from
275 .Fa val_in
276 to it by calling
277 .Fn i2d_DSAparams
278 and
279 .Fn d2i_DSAparams .
280 If a private or public key are present in
281 .Fa val_in ,
282 they are not copied.
283 .Pp
284 .Fn d2i_DSA_SIG
285 and
286 .Fn i2d_DSA_SIG
287 decode and encode a DSA signature using an ASN.1
288 .Vt Dss-Sig-Value
289 structure as defined in RFC 3279 section 2.2.2
290 and used for the signatureValue field of the ASN.1
291 .Vt Certificate
292 structure 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 ,
302 and
303 .Fn DSAparams_dup
304 return a valid
305 .Vt DSA
306 object or
307 .Dv NULL
308 if an error occurs.
309 .Pp
310 .Fn d2i_DSA_SIG
311 returns a valid
312 .Vt DSA_SIG
313 object or
314 .Dv NULL
315 if 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
324 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
325 Certificate Revocation List (CRL) Profile,
326 section 4.1: Basic Certificate Fields
327 .Pp
328 RFC 3279: Algorithms and Identifiers for the Internet X.509 Public
329 Key Infrastructure Certificate and Certificate Revocation List (CRL)
330 Profile:
331 .Bl -dash -compact
332 .It
333 section 2.2.2: DSA Signature Algorithm
334 .It
335 section 2.3.2: DSA Signature Keys
336 .El