| blob | 85b46d44a08a4baf63e825729c8d9dcb80f06559 |
1 .\" $OpenBSD: d2i_PrivateKey.3,v 1.8 2018/03/27 17:35:50 schwarze Exp $
2 .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3 .\"
4 .\" This file is a derived work.
5 .\" The changes are covered by the following Copyright and license:
6 .\"
7 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
8 .\"
9 .\" Permission to use, copy, modify, and distribute this software for any
10 .\" purpose with or without fee is hereby granted, provided that the above
11 .\" copyright notice and this permission notice appear in all copies.
12 .\"
13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
14 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
16 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 .\"
21 .\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
22 .\" Copyright (c) 2016 The OpenSSL Project. All rights reserved.
23 .\"
24 .\" Redistribution and use in source and binary forms, with or without
25 .\" modification, are permitted provided that the following conditions
26 .\" are met:
27 .\"
28 .\" 1. Redistributions of source code must retain the above copyright
29 .\" notice, this list of conditions and the following disclaimer.
30 .\"
31 .\" 2. Redistributions in binary form must reproduce the above copyright
32 .\" notice, this list of conditions and the following disclaimer in
33 .\" the documentation and/or other materials provided with the
34 .\" distribution.
35 .\"
36 .\" 3. All advertising materials mentioning features or use of this
37 .\" software must display the following acknowledgment:
38 .\" "This product includes software developed by the OpenSSL Project
39 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
40 .\"
41 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
42 .\" endorse or promote products derived from this software without
43 .\" prior written permission. For written permission, please contact
44 .\" openssl-core@openssl.org.
45 .\"
46 .\" 5. Products derived from this software may not be called "OpenSSL"
47 .\" nor may "OpenSSL" appear in their names without prior written
48 .\" permission of the OpenSSL Project.
49 .\"
50 .\" 6. Redistributions of any form whatsoever must retain the following
51 .\" acknowledgment:
52 .\" "This product includes software developed by the OpenSSL Project
53 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
54 .\"
55 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
56 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
57 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
58 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
59 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
60 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
61 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
62 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
63 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
64 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
65 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
66 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
67 .\"
68 .Dd $Mdocdate: March 27 2018 $
69 .Dt D2I_PRIVATEKEY 3
70 .Os
71 .Sh NAME
72 .Nm d2i_PrivateKey ,
73 .Nm d2i_AutoPrivateKey ,
74 .Nm i2d_PrivateKey ,
75 .Nm d2i_PrivateKey_bio ,
76 .Nm d2i_PrivateKey_fp ,
77 .Nm i2d_PKCS8PrivateKeyInfo_bio ,
78 .Nm i2d_PKCS8PrivateKeyInfo_fp ,
79 .Nm d2i_PublicKey ,
80 .Nm i2d_PublicKey
81 .Nd decode and encode EVP_PKEY objects
82 .Sh SYNOPSIS
83 .In openssl/evp.h
84 .Ft EVP_PKEY *
85 .Fo d2i_PrivateKey
86 .Fa "int type"
87 .Fa "EVP_PKEY **val_out"
88 .Fa "const unsigned char **des_in"
89 .Fa "long length"
90 .Fc
91 .Ft EVP_PKEY *
92 .Fo d2i_AutoPrivateKey
93 .Fa "EVP_PKEY **val_out"
94 .Fa "const unsigned char **des_in"
95 .Fa "long length"
96 .Fc
97 .Ft int
98 .Fo i2d_PrivateKey
99 .Fa "EVP_PKEY *val_in"
100 .Fa "unsigned char **des_out"
101 .Fc
102 .Ft EVP_PKEY *
103 .Fo d2i_PrivateKey_bio
104 .Fa "BIO *in_bio"
105 .Fa "EVP_PKEY **val_out"
106 .Fc
107 .Ft EVP_PKEY *
108 .Fo d2i_PrivateKey_fp
109 .Fa "FILE *in_fp"
110 .Fa "EVP_PKEY **val_out"
111 .Fc
112 .Ft int
113 .Fo i2d_PKCS8PrivateKeyInfo_bio
114 .Fa "BIO *out_bio"
115 .Fa "EVP_PKEY *val_in"
116 .Fc
117 .Ft int
118 .Fo i2d_PKCS8PrivateKeyInfo_fp
119 .Fa "FILE *out_fp"
120 .Fa "EVP_PKEY *val_in"
121 .Fc
122 .Ft EVP_PKEY *
123 .Fo d2i_PublicKey
124 .Fa "int type"
125 .Fa "EVP_PKEY **val_out"
126 .Fa "const unsigned char **des_in"
127 .Fa "long length"
128 .Fc
129 .Ft int
130 .Fo i2d_PublicKey
131 .Fa "EVP_PKEY *val_in"
132 .Fa "unsigned char **des_out"
133 .Fc
134 .Sh DESCRIPTION
135 These are algorithm-independent interfaces to decode and encode
136 private and public keys.
137 For details about the semantics, examples, caveats, and bugs, see
138 .Xr ASN1_item_d2i 3 .
139 .Pp
140 .Fn d2i_PrivateKey
141 decodes a private key using algorithm
142 .Fa type .
143 It attempts to use any algorithm specific format or the PKCS#8 unencrypted
144 .Vt PrivateKeyInfo
145 format defined in RFC 5208 section 5.
146 The
147 .Fa type
148 parameter should be a public key algorithm constant such as
149 .Dv EVP_PKEY_RSA .
150 An error occurs if the decoded key does not match
151 .Fa type .
152 .Pp
153 .Fn d2i_AutoPrivateKey
154 is similar to
155 .Fn d2i_PrivateKey
156 except that it attempts to automatically detect the algorithm.
157 .Pp
158 .Fn d2i_PrivateKey_bio
159 and
160 .Fn d2i_PrivateKey_fp
161 are similar to
162 .Fn d2i_PrivateKey
163 except that they read from a
164 .Vt BIO
165 or
166 .Vt FILE
167 pointer.
168 .Pp
169 .Fn i2d_PrivateKey
170 encodes
171 .Fa val_in .
172 It uses an algorithm specific format or, if none is defined for
173 that key type, the PKCS#8 unencrypted
174 .Vt PrivateKeyInfo
175 format.
176 .Pp
177 .Fn i2d_PKCS8PrivateKeyInfo_bio
178 and
179 .Fn i2d_PKCS8PrivateKeyInfo_fp
180 encode
181 .Fa val_in
182 in PKCS#8 unencrypted
183 .Vt PrivateKeyInfo
184 format.
185 They are similar to
186 .Fn i2d_PrivateKey
187 except that they don't use any algorithm-specific formats
188 and that they write to a
189 .Vt BIO
190 or
191 .Vt FILE
192 pointer rather than to a buffer.
193 .Pp
194 All these functions use DER format and unencrypted keys.
195 Applications wishing to encrypt or decrypt private keys should use other
196 functions such as
197 .Xr d2i_PKCS8PrivateKey_bio 3
198 instead.
199 .Pp
200 If
201 .Pf * Fa val_out
202 is not
203 .Dv NULL
204 when calling
205 .Fn d2i_PrivateKey
206 or
207 .Fn d2i_AutoPrivateKey
208 (i.e. an existing structure is being reused) and the key format is
209 PKCS#8, then
210 .Pf * Fa val_out
211 will be freed and replaced on a successful call.
212 .Pp
213 .Fn d2i_PublicKey
214 calls
215 .Xr d2i_DSAPublicKey 3 ,
216 .Xr o2i_ECPublicKey 3 ,
217 or
218 .Xr d2i_RSAPublicKey 3
219 depending on
220 .Fa type
221 and stores the result in the returned
222 .Vt EVP_PKEY
223 object.
224 .Pp
225 .Fn i2d_PublicKey
226 calls
227 .Xr i2d_DSAPublicKey 3 ,
228 .Xr i2o_ECPublicKey 3 ,
229 or
230 .Xr i2d_RSAPublicKey 3
231 depending on the algorithm used by
232 .Fa val_in .
233 .Sh RETURN VALUES
234 .Fn d2i_PrivateKey ,
235 .Fn d2i_AutoPrivateKey ,
236 .Fn d2i_PrivateKey_bio ,
237 .Fn d2i_PrivateKey_fp ,
238 and
239 .Fn d2i_PublicKey
240 return a valid
241 .Vt EVP_PKEY
242 structure or
243 .Dv NULL
244 if an error occurs.
245 .Pp
246 .Fn i2d_PrivateKey
247 and
248 .Fn i2d_PublicKey
249 return the number of bytes successfully encoded or a negative value if
250 an error occurs.
251 .Pp
252 .Fn i2d_PKCS8PrivateKeyInfo_bio
253 and
254 .Fn i2d_PKCS8PrivateKeyInfo_fp
255 return 1 for success or 0 if an error occurs.
256 .Pp
257 For all functions, the error code can be obtained by calling
258 .Xr ERR_get_error 3 .
259 .Sh SEE ALSO
260 .Xr d2i_PKCS8_PRIV_KEY_INFO 3 ,
261 .Xr d2i_PKCS8PrivateKey_bio 3 ,
262 .Xr EVP_PKEY_type 3 ,
263 .Xr PEM_write_PrivateKey 3 ,
264 .Xr PKCS8_PRIV_KEY_INFO_new 3
265 .Sh STANDARDS
266 RFC 5208: Public-Key Cryptography Standards (PKCS) #8: Private-Key
267 Information Syntax Specification
268 .Sh HISTORY
269 .Fn d2i_PrivateKey ,
270 .Fn i2d_PrivateKey ,
271 .Fn d2i_PublicKey ,
272 and
273 .Fn i2d_PublicKey
274 first appeared in SSLeay 0.6.0 and have been available since
275 .Ox 2.4 .
276 .Pp
277 .Fn d2i_AutoPrivateKey ,
278 .Fn d2i_PrivateKey_bio ,
279 .Fn i2d_PrivateKey_bio ,
280 .Fn d2i_PrivateKey_fp ,
281 .Fn i2d_PrivateKey_fp ,
282 .Fn i2d_PKCS8PrivateKeyInfo_bio ,
283 and
284 .Fn i2d_PKCS8PrivateKeyInfo_fp
285 first appeared in OpenSSL 0.9.5 and have been available since
286 .Ox 2.7 .