| blob | c5264a610b63d09aad50afe1a5766b0c28686306 |
1 .\" $OpenBSD: d2i_RSAPublicKey.3,v 1.9 2016/12/26 17:19:23 schwarze Exp $
2 .\" OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400
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 Ulf Moeller <ulf@openssl.org> and
22 .\" Dr. Stephen Henson <steve@openssl.org>.
23 .\" Copyright (c) 2000, 2002, 2003, 2009, 2016 The OpenSSL Project.
24 .\" All rights reserved.
25 .\"
26 .\" Redistribution and use in source and binary forms, with or without
27 .\" modification, are permitted provided that the following conditions
28 .\" are met:
29 .\"
30 .\" 1. Redistributions of source code must retain the above copyright
31 .\" notice, this list of conditions and the following disclaimer.
32 .\"
33 .\" 2. Redistributions in binary form must reproduce the above copyright
34 .\" notice, this list of conditions and the following disclaimer in
35 .\" the documentation and/or other materials provided with the
36 .\" distribution.
37 .\"
38 .\" 3. All advertising materials mentioning features or use of this
39 .\" software must display the following acknowledgment:
40 .\" "This product includes software developed by the OpenSSL Project
41 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
42 .\"
43 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
44 .\" endorse or promote products derived from this software without
45 .\" prior written permission. For written permission, please contact
46 .\" openssl-core@openssl.org.
47 .\"
48 .\" 5. Products derived from this software may not be called "OpenSSL"
49 .\" nor may "OpenSSL" appear in their names without prior written
50 .\" permission of the OpenSSL Project.
51 .\"
52 .\" 6. Redistributions of any form whatsoever must retain the following
53 .\" acknowledgment:
54 .\" "This product includes software developed by the OpenSSL Project
55 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
56 .\"
57 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
58 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
59 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
60 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
61 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
62 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
63 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
64 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
65 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
66 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
67 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
68 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
69 .\"
70 .Dd $Mdocdate: December 26 2016 $
71 .Dt D2I_RSAPUBLICKEY 3
72 .Os
73 .Sh NAME
74 .Nm d2i_RSAPublicKey ,
75 .Nm i2d_RSAPublicKey ,
76 .Nm d2i_RSAPrivateKey ,
77 .Nm i2d_RSAPrivateKey ,
78 .Nm d2i_Netscape_RSA ,
79 .Nm i2d_Netscape_RSA ,
80 .Nm d2i_RSA_PSS_PARAMS ,
81 .Nm i2d_RSA_PSS_PARAMS ,
82 .Nm d2i_RSAPublicKey_bio ,
83 .Nm d2i_RSAPublicKey_fp ,
84 .Nm i2d_RSAPublicKey_bio ,
85 .Nm i2d_RSAPublicKey_fp ,
86 .Nm d2i_RSAPrivateKey_bio ,
87 .Nm d2i_RSAPrivateKey_fp ,
88 .Nm i2d_RSAPrivateKey_bio ,
89 .Nm i2d_RSAPrivateKey_fp ,
90 .Nm d2i_RSA_PUBKEY ,
91 .Nm i2d_RSA_PUBKEY ,
92 .Nm d2i_RSA_PUBKEY_bio ,
93 .Nm d2i_RSA_PUBKEY_fp ,
94 .Nm i2d_RSA_PUBKEY_bio ,
95 .Nm i2d_RSA_PUBKEY_fp
96 .Nd decode and encode RSA keys and parameters
97 .Sh SYNOPSIS
98 .In openssl/rsa.h
99 .Ft RSA *
100 .Fo d2i_RSAPublicKey
101 .Fa "RSA **val_out"
102 .Fa "const unsigned char **der_in"
103 .Fa "long length"
104 .Fc
105 .Ft int
106 .Fo i2d_RSAPublicKey
107 .Fa "RSA *val_in"
108 .Fa "unsigned char **der_out"
109 .Fc
110 .Ft RSA *
111 .Fo d2i_RSAPrivateKey
112 .Fa "RSA **val_out"
113 .Fa "const unsigned char **der_in"
114 .Fa "long length"
115 .Fc
116 .Ft int
117 .Fo i2d_RSAPrivateKey
118 .Fa "RSA *val_in"
119 .Fa "unsigned char **der_out"
120 .Fc
121 .Ft RSA *
122 .Fo d2i_Netscape_RSA
123 .Fa "RSA **val_out"
124 .Fa "const unsigned char **der_in"
125 .Fa "long length"
126 .Fa "int (*cb)()"
127 .Fc
128 .Ft int
129 .Fo i2d_Netscape_RSA
130 .Fa "RSA *val_in"
131 .Fa "unsigned char **der_out"
132 .Fa "int (*cb)()"
133 .Fc
134 .Ft RSA_PSS_PARAMS *
135 .Fo d2i_RSA_PSS_PARAMS
136 .Fa "RSA_PSS_PARAMS **val_out"
137 .Fa "const unsigned char **der_in"
138 .Fa "long length"
139 .Fc
140 .Ft int
141 .Fo i2d_RSA_PSS_PARAMS
142 .Fa "RSA_PSS_PARAMS *val_in"
143 .Fa "unsigned char **der_out"
144 .Fc
145 .In openssl/x509.h
146 .Ft RSA *
147 .Fo d2i_RSAPublicKey_bio
148 .Fa "BIO *in_bio"
149 .Fa "RSA **val_out"
150 .Fc
151 .Ft RSA *
152 .Fo d2i_RSAPublicKey_fp
153 .Fa "FILE *in_fp"
154 .Fa "RSA **val_out"
155 .Fc
156 .Ft int
157 .Fo i2d_RSAPublicKey_bio
158 .Fa "BIO *out_bio"
159 .Fa "RSA *val_in"
160 .Fc
161 .Ft int
162 .Fo i2d_RSAPublicKey_fp
163 .Fa "FILE *out_fp"
164 .Fa "RSA *val_in"
165 .Fc
166 .Ft RSA *
167 .Fo d2i_RSAPrivateKey_bio
168 .Fa "BIO *in_bio"
169 .Fa "RSA **val_out"
170 .Fc
171 .Ft RSA *
172 .Fo d2i_RSAPrivateKey_fp
173 .Fa "FILE *in_fp"
174 .Fa "RSA **val_out"
175 .Fc
176 .Ft int
177 .Fo i2d_RSAPrivateKey_bio
178 .Fa "BIO *out_bio"
179 .Fa "RSA *val_in"
180 .Fc
181 .Ft int
182 .Fo i2d_RSAPrivateKey_fp
183 .Fa "FILE *out_fp"
184 .Fa "RSA *val_in"
185 .Fc
186 .Ft RSA *
187 .Fo d2i_RSA_PUBKEY
188 .Fa "RSA **val_out"
189 .Fa "const unsigned char **der_in"
190 .Fa "long length"
191 .Fc
192 .Ft int
193 .Fo i2d_RSA_PUBKEY
194 .Fa "RSA *val_in"
195 .Fa "unsigned char **der_out"
196 .Fc
197 .Ft RSA *
198 .Fo d2i_RSA_PUBKEY_bio
199 .Fa "BIO *in_bio"
200 .Fa "RSA **val_out"
201 .Fc
202 .Ft RSA *
203 .Fo d2i_RSA_PUBKEY_fp
204 .Fa "FILE *in_fp"
205 .Fa "RSA **val_out"
206 .Fc
207 .Ft int
208 .Fo i2d_RSA_PUBKEY_bio
209 .Fa "BIO *out_bio"
210 .Fa "RSA *val_in"
211 .Fc
212 .Ft int
213 .Fo i2d_RSA_PUBKEY_fp
214 .Fa "FILE *out_fp"
215 .Fa "RSA *val_in"
216 .Fc
217 .Sh DESCRIPTION
218 These functions decode and encode RSA private and public keys.
219 For details about the semantics, examples, caveats, and bugs, see
220 .Xr ASN1_item_d2i 3 .
221 .Pp
222 .Fn d2i_RSAPublicKey
223 and
224 .Fn i2d_RSAPublicKey
225 decode and encode a PKCS#1
226 .Vt RSAPublicKey
227 structure defined in RFC 8017 appendix A.1.1.
228 .Fn d2i_RSAPublicKey_bio ,
229 .Fn d2i_RSAPublicKey_fp ,
230 .Fn i2d_RSAPublicKey_bio ,
231 and
232 .Fn i2d_RSAPublicKey_fp
233 are similar except that they decode or encode using a
234 .Vt BIO
235 or
236 .Vt FILE
237 pointer.
238 .Pp
239 .Fn d2i_RSAPrivateKey
240 and
241 .Fn i2d_RSAPrivateKey
242 decode and encode a PKCS#1
243 .Vt RSAPrivateKey
244 structure defined in RFC 8017 appendix A.1.2.
245 The
246 .Vt RSA
247 structure passed to the private key encoding functions should have
248 all the PKCS#1 private key components present.
249 The data encoded by the private key functions is unencrypted and
250 therefore offers no private key security.
251 .Fn d2i_RSAPrivateKey_bio ,
252 .Fn d2i_RSAPrivateKey_fp ,
253 .Fn i2d_RSAPrivateKey_bio ,
254 and
255 .Fn i2d_RSAPrivateKey_fp
256 are similar except that they decode or encode using a
257 .Vt BIO
258 or
259 .Vt FILE
260 pointer.
261 .Pp
262 .Fn d2i_Netscape_RSA
263 and
264 .Fn i2d_Netscape_RSA
265 decode and encode an RSA private key in NET format.
266 These functions are present to provide compatibility with
267 certain very old software.
268 The NET format has some severe security weaknesses and should be
269 avoided if possible.
270 .Pp
271 .Fn d2i_RSA_PSS_PARAMS
272 and
273 .Fn i2d_RSA_PSS_PARAMS
274 decode and encode a PKCS#1
275 .Vt RSASSA-PSS-params
276 structure defined in RFC 8017 appendix A.2.3 and documented in
277 .Xr RSA_PSS_PARAMS_new 3 .
278 .Pp
279 .Fn d2i_RSA_PUBKEY
280 and
281 .Fn i2d_RSA_PUBKEY
282 decode and encode an RSA public key using an ASN.1
283 .Vt SubjectPublicKeyInfo
284 structure defined in RFC 5280 section 4.1 and documented in
285 .Xr X509_PUBKEY_new 3 .
286 .Fn d2i_RSA_PUBKEY_bio ,
287 .Fn d2i_RSA_PUBKEY_fp ,
288 .Fn i2d_RSA_PUBKEY_bio ,
289 and
290 .Fn i2d_RSA_PUBKEY_fp
291 are similar except that they decode or encode using a
292 .Vt BIO
293 or
294 .Vt FILE
295 pointer.
296 .Sh RETURN VALUES
297 .Fn d2i_RSAPublicKey ,
298 .Fn d2i_RSAPublicKey_bio ,
299 .Fn d2i_RSAPublicKey_fp ,
300 .Fn d2i_RSAPrivateKey ,
301 .Fn d2i_RSAPrivateKey_bio ,
302 .Fn d2i_RSAPrivateKey_fp ,
303 .Fn d2i_Netscape_RSA ,
304 .Fn d2i_RSA_PUBKEY ,
305 .Fn d2i_RSA_PUBKEY_bio ,
306 and
307 .Fn d2i_RSA_PUBKEY_fp
308 return a valid
309 .Vt RSA
310 object or
311 .Dv NULL
312 if an error occurs.
313 .Pp
314 .Fn d2i_RSA_PSS_PARAMS
315 returns a valid
316 .Vt RSA_PSS_PARAMS
317 object or
318 .Dv NULL
319 if an error occurs.
320 .Pp
321 .Fn i2d_RSAPublicKey ,
322 .Fn i2d_RSAPrivateKey ,
323 .Fn i2d_Netscape_RSA ,
324 .Fn i2d_RSA_PSS_PARAMS ,
325 and
326 .Fn i2d_RSA_PUBKEY
327 return the number of bytes successfully encoded or a negative value
328 if an error occurs.
329 .Pp
330 .Fn i2d_RSAPublicKey_bio ,
331 .Fn i2d_RSAPublicKey_fp ,
332 .Fn i2d_RSAPrivateKey_bio ,
333 .Fn i2d_RSAPrivateKey_fp ,
334 .Fn i2d_RSA_PUBKEY_bio ,
335 and
336 .Fn i2d_RSA_PUBKEY_fp
337 return 1 for success or 0 if an error occurs.
338 .Sh SEE ALSO
339 .Xr ASN1_item_d2i 3 ,
340 .Xr EVP_PKEY_set1_RSA 3 ,
341 .Xr PEM_write_RSAPrivateKey 3 ,
342 .Xr RSA_new 3 ,
343 .Xr RSA_PSS_PARAMS_new 3 ,
344 .Xr X509_PUBKEY_new 3
345 .Sh STANDARDS
346 RFC 8017: PKCS #1: RSA Cryptography Specifications
347 .Pp
348 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
349 Certificate Revocation List (CRL) Profile,
350 section 4.1: Basic Certificate Fields