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