xref: /freebsd/crypto/openssl/doc/man3/d2i_RSAPrivateKey.pod (revision 734e82fe33aa764367791a7d603b383996c6b40b) 
1=pod
2
3=begin comment
4
5Any deprecated keypair/params d2i or i2d functions are collected on this page.
6
7=end comment
8
9=head1 NAME
10
11d2i_DSAPrivateKey,
12d2i_DSAPrivateKey_bio,
13d2i_DSAPrivateKey_fp,
14d2i_DSAPublicKey,
15d2i_DSA_PUBKEY,
16d2i_DSA_PUBKEY_bio,
17d2i_DSA_PUBKEY_fp,
18d2i_DSAparams,
19d2i_RSAPrivateKey,
20d2i_RSAPrivateKey_bio,
21d2i_RSAPrivateKey_fp,
22d2i_RSAPublicKey,
23d2i_RSAPublicKey_bio,
24d2i_RSAPublicKey_fp,
25d2i_RSA_PUBKEY,
26d2i_RSA_PUBKEY_bio,
27d2i_RSA_PUBKEY_fp,
28d2i_DHparams,
29d2i_DHparams_bio,
30d2i_DHparams_fp,
31d2i_ECPKParameters,
32d2i_ECParameters,
33d2i_ECPrivateKey,
34d2i_ECPrivateKey_bio,
35d2i_ECPrivateKey_fp,
36d2i_EC_PUBKEY,
37d2i_EC_PUBKEY_bio,
38d2i_EC_PUBKEY_fp,
39i2d_RSAPrivateKey,
40i2d_RSAPrivateKey_bio,
41i2d_RSAPrivateKey_fp,
42i2d_RSAPublicKey,
43i2d_RSAPublicKey_bio,
44i2d_RSAPublicKey_fp,
45i2d_RSA_PUBKEY,
46i2d_RSA_PUBKEY_bio,
47i2d_RSA_PUBKEY_fp,
48i2d_DHparams,
49i2d_DHparams_bio,
50i2d_DHparams_fp,
51i2d_DSAPrivateKey,
52i2d_DSAPrivateKey_bio,
53i2d_DSAPrivateKey_fp,
54i2d_DSAPublicKey,
55i2d_DSA_PUBKEY,
56i2d_DSA_PUBKEY_bio,
57i2d_DSA_PUBKEY_fp,
58i2d_DSAparams,
59i2d_ECPKParameters,
60i2d_ECParameters,
61i2d_ECPrivateKey,
62i2d_ECPrivateKey_bio,
63i2d_ECPrivateKey_fp,
64i2d_EC_PUBKEY,
65i2d_EC_PUBKEY_bio,
66i2d_EC_PUBKEY_fp
67- DEPRECATED
68
69=head1 SYNOPSIS
70
71=for openssl generic
72
73The following functions have been deprecated since OpenSSL 3.0, and can be
74hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
75see L<openssl_user_macros(7)>:
76
77 TYPE *d2i_TYPEPrivateKey(TYPE **a, const unsigned char **ppin, long length);
78 TYPE *d2i_TYPEPrivateKey_bio(BIO *bp, TYPE **a);
79 TYPE *d2i_TYPEPrivateKey_fp(FILE *fp, TYPE **a);
80 TYPE *d2i_TYPEPublicKey(TYPE **a, const unsigned char **ppin, long length);
81 TYPE *d2i_TYPEPublicKey_bio(BIO *bp, TYPE **a);
82 TYPE *d2i_TYPEPublicKey_fp(FILE *fp, TYPE **a);
83 TYPE *d2i_TYPEparams(TYPE **a, const unsigned char **ppin, long length);
84 TYPE *d2i_TYPEparams_bio(BIO *bp, TYPE **a);
85 TYPE *d2i_TYPEparams_fp(FILE *fp, TYPE **a);
86 TYPE *d2i_TYPE_PUBKEY(TYPE **a, const unsigned char **ppin, long length);
87 TYPE *d2i_TYPE_PUBKEY_bio(BIO *bp, TYPE **a);
88 TYPE *d2i_TYPE_PUBKEY_fp(FILE *fp, TYPE **a);
89
90 int i2d_TYPEPrivateKey(const TYPE *a, unsigned char **ppout);
91 int i2d_TYPEPrivateKey(TYPE *a, unsigned char **ppout);
92 int i2d_TYPEPrivateKey_fp(FILE *fp, const TYPE *a);
93 int i2d_TYPEPrivateKey_fp(FILE *fp, TYPE *a);
94 int i2d_TYPEPrivateKey_bio(BIO *bp, const TYPE *a);
95 int i2d_TYPEPrivateKey_bio(BIO *bp, TYPE *a);
96 int i2d_TYPEPublicKey(const TYPE *a, unsigned char **ppout);
97 int i2d_TYPEPublicKey(TYPE *a, unsigned char **ppout);
98 int i2d_TYPEPublicKey_fp(FILE *fp, const TYPE *a);
99 int i2d_TYPEPublicKey_fp(FILE *fp, TYPE *a);
100 int i2d_TYPEPublicKey_bio(BIO *bp, const TYPE *a);
101 int i2d_TYPEPublicKey_bio(BIO *bp, TYPE *a);
102 int i2d_TYPEparams(const TYPE *a, unsigned char **ppout);
103 int i2d_TYPEparams(TYPE *a, unsigned char **ppout);
104 int i2d_TYPEparams_fp(FILE *fp, const TYPE *a);
105 int i2d_TYPEparams_fp(FILE *fp, TYPE *a);
106 int i2d_TYPEparams_bio(BIO *bp, const TYPE *a);
107 int i2d_TYPEparams_bio(BIO *bp, TYPE *a);
108 int i2d_TYPE_PUBKEY(const TYPE *a, unsigned char **ppout);
109 int i2d_TYPE_PUBKEY(TYPE *a, unsigned char **ppout);
110 int i2d_TYPE_PUBKEY_fp(FILE *fp, const TYPE *a);
111 int i2d_TYPE_PUBKEY_fp(FILE *fp, TYPE *a);
112 int i2d_TYPE_PUBKEY_bio(BIO *bp, const TYPE *a);
113 int i2d_TYPE_PUBKEY_bio(BIO *bp, TYPE *a);
114
115=head1 DESCRIPTION
116
117All functions described here are deprecated.  Please use L<OSSL_DECODER(3)>
118instead of the B<d2i> functions and L<OSSL_ENCODER(3)> instead of the B<i2d>
119functions.  See L</Migration> below.
120
121In the description here, B<I<TYPE>> is used a placeholder for any of the
122OpenSSL datatypes, such as B<RSA>.
123The function parameters I<ppin> and I<ppout> are generally either both named
124I<pp> in the headers, or I<in> and I<out>.
125
126All the functions here behave the way that's described in L<d2i_X509(3)>.
127
128Please note that not all functions in the synopsis are available for all key
129types.  For example, there are no d2i_RSAparams() or i2d_RSAparams(),
130because the PKCS#1 B<RSA> structure doesn't include any key parameters.
131
132B<d2i_I<TYPE>PrivateKey>() and derivates thereof decode DER encoded
133B<I<TYPE>> private key data organized in a type specific structure.
134
135B<d2i_I<TYPE>PublicKey>() and derivates thereof decode DER encoded
136B<I<TYPE>> public key data organized in a type specific structure.
137
138B<d2i_I<TYPE>params>() and derivates thereof decode DER encoded B<I<TYPE>>
139key parameters organized in a type specific structure.
140
141B<d2i_I<TYPE>_PUBKEY>() and derivates thereof decode DER encoded B<I<TYPE>>
142public key data organized in a B<SubjectPublicKeyInfo> structure.
143
144B<i2d_I<TYPE>PrivateKey>() and derivates thereof encode the private key
145B<I<TYPE>> data into a type specific DER encoded structure.
146
147B<i2d_I<TYPE>PublicKey>() and derivates thereof encode the public key
148B<I<TYPE>> data into a type specific DER encoded structure.
149
150B<i2d_I<TYPE>params>() and derivates thereof encode the B<I<TYPE>> key
151parameters data into a type specific DER encoded structure.
152
153B<i2d_I<TYPE>_PUBKEY>() and derivates thereof encode the public key
154B<I<TYPE>> data into a DER encoded B<SubjectPublicKeyInfo> structure.
155
156For example, d2i_RSAPrivateKey() and d2i_RSAPublicKey() expects the
157structure defined by PKCS#1.
158Similarly, i2d_RSAPrivateKey() and  i2d_RSAPublicKey() produce DER encoded
159string organized according to PKCS#1.
160
161=head2 Migration
162
163Migration from the diverse B<I<TYPE>>s requires using corresponding new
164OpenSSL types.  For all B<I<TYPE>>s described here, the corresponding new
165type is B<EVP_PKEY>.  The rest of this section assumes that this has been
166done, exactly how to do that is described elsewhere.
167
168There are two migration paths:
169
170=over 4
171
172=item *
173
174Replace
175b<d2i_I<TYPE>PrivateKey()> with L<d2i_PrivateKey(3)>,
176b<d2i_I<TYPE>PublicKey()> with L<d2i_PublicKey(3)>,
177b<d2i_I<TYPE>params()> with L<d2i_KeyParams(3)>,
178b<d2i_I<TYPE>_PUBKEY()> with L<d2i_PUBKEY(3)>,
179b<i2d_I<TYPE>PrivateKey()> with L<i2d_PrivateKey(3)>,
180b<i2d_I<TYPE>PublicKey()> with L<i2d_PublicKey(3)>,
181b<i2d_I<TYPE>params()> with L<i2d_KeyParams(3)>,
182b<i2d_I<TYPE>_PUBKEY()> with L<i2d_PUBKEY(3)>.
183A caveat is that L<i2d_PrivateKey(3)> may output a DER encoded PKCS#8
184outermost structure instead of the type specific structure, and that
185L<d2i_PrivateKey(3)> recognises and unpacks a PKCS#8 structures.
186
187=item *
188
189Use L<OSSL_DECODER(3)> and L<OSSL_ENCODER(3)>.  How to migrate is described
190below.  All those descriptions assume that the key to be encoded is in the
191variable I<pkey>.
192
193=back
194
195=head3 Migrating B<i2d> functions to B<OSSL_ENCODER>
196
197The exact L<OSSL_ENCODER(3)> output is driven by arguments rather than by
198function names.  The sample code to get DER encoded output in a type
199specific structure is uniform, the only things that vary are the selection
200of what part of the B<EVP_PKEY> should be output, and the structure.  The
201B<i2d> functions names can therefore be translated into two variables,
202I<selection> and I<structure> as follows:
203
204=over 4
205
206=item B<i2d_I<TYPE>PrivateKey>() translates into:
207
208 int selection = EVP_PKEY_PRIVATE_KEY;
209 const char *structure = "type-specific";
210
211=item B<i2d_I<TYPE>PublicKey>() translates into:
212
213 int selection = EVP_PKEY_PUBLIC_KEY;
214 const char *structure = "type-specific";
215
216=item B<i2d_I<TYPE>params>() translates into:
217
218 int selection = EVP_PKEY_PARAMETERS;
219 const char *structure = "type-specific";
220
221=item B<i2d_I<TYPE>_PUBKEY>() translates into:
222
223 int selection = EVP_PKEY_PUBLIC_KEY;
224 const char *structure = "SubjectPublicKeyInfo";
225
226=back
227
228The following sample code does the rest of the work:
229
230 unsigned char *p = buffer;     /* |buffer| is supplied by the caller */
231 size_t len = buffer_size;      /* assumed be the size of |buffer| */
232 OSSL_ENCODER_CTX *ctx =
233     OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "DER", structure,
234                                   NULL, NULL);
235 if (ctx == NULL) {
236     /* fatal error handling */
237 }
238 if (OSSL_ENCODER_CTX_get_num_encoders(ctx) == 0) {
239     OSSL_ENCODER_CTX_free(ctx);
240     /* non-fatal error handling */
241 }
242 if (!OSSL_ENCODER_to_data(ctx, &p, &len)) {
243     OSSL_ENCODER_CTX_free(ctx);
244     /* error handling */
245 }
246 OSSL_ENCODER_CTX_free(ctx);
247
248=for comment TODO: a similar section on OSSL_DECODER is to be added
249
250=head1 NOTES
251
252The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
253"internal" (that is, an internal C structure) and "DER" respectively.
254So B<i2d_I<TYPE>>() converts from internal to DER.
255
256The functions can also understand B<BER> forms.
257
258The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
259populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
260empty structure such as that returned by TYPE_new().
261
262The encoded data is in binary form and may contain embedded zeros.
263Therefore, any FILE pointers or BIOs should be opened in binary mode.
264Functions such as strlen() will B<not> return the correct length
265of the encoded structure.
266
267The ways that I<*ppin> and I<*ppout> are incremented after the operation
268can trap the unwary. See the B<WARNINGS> section in L<d2i_X509(3)> for some
269common errors.
270The reason for this-auto increment behaviour is to reflect a typical
271usage of ASN1 functions: after one structure is encoded or decoded
272another will be processed after it.
273
274The following points about the data types might be useful:
275
276=over 4
277
278=item B<DSA_PUBKEY>
279
280Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
281
282=item B<DSAPublicKey>, B<DSAPrivateKey>
283
284Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
285L<PEM_write_PrivateKey(3)>, or similar instead.
286
287=back
288
289=head1 RETURN VALUES
290
291B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
292B<I<TYPE>> structure or NULL if an error occurs.  If the "reuse" capability has
293been used with a valid structure being passed in via I<a>, then the object is
294freed in the event of error and I<*a> is set to NULL.
295
296B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
297value if an error occurs.
298
299B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
300error occurs.
301
302=head1 SEE ALSO
303
304L<OSSL_ENCODER(3)>, L<OSSL_DECODER(3)>,
305L<d2i_PrivateKey(3)>, L<d2i_PublicKey(3)>, L<d2i_KeyParams(3)>,
306L<d2i_PUBKEY(3)>,
307L<i2d_PrivateKey(3)>, L<i2d_PublicKey(3)>, L<i2d_KeyParams(3)>,
308L<i2d_PUBKEY(3)>
309
310=head1 COPYRIGHT
311
312Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
313
314Licensed under the Apache License 2.0 (the "License").  You may not use
315this file except in compliance with the License.  You can obtain a copy
316in the file LICENSE in the source distribution or at
317L<https://www.openssl.org/source/license.html>.
318
319=cut
320