5 Any deprecated keypair/params d2i or i2d functions are collected on this page.
12 d2i_DSAPrivateKey_bio,
20 d2i_RSAPrivateKey_bio,
40 i2d_RSAPrivateKey_bio,
52 i2d_DSAPrivateKey_bio,
73 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
74 B<OPENSSL_API_COMPAT> with a suitable version value, see
75 L<openssl_user_macros(7)>:
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);
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);
117 All functions described here are deprecated. Please use L<OSSL_DECODER(3)>
118 instead of the B<d2i> functions and L<OSSL_ENCODER(3)> instead of the B<i2d>
119 functions. See L</Migration> below.
121 In the description here, B<I<TYPE>> is used a placeholder for any of the
122 OpenSSL datatypes, such as B<RSA>.
123 The function parameters I<ppin> and I<ppout> are generally either both named
124 I<pp> in the headers, or I<in> and I<out>.
126 All the functions here behave the way that's described in L<d2i_X509(3)>.
128 Please note that not all functions in the synopsis are available for all key
129 types. For example, there are no d2i_RSAparams() or i2d_RSAparams(),
130 because the PKCS#1 B<RSA> structure doesn't include any key parameters.
132 B<d2i_I<TYPE>PrivateKey>() and derivates thereof decode DER encoded
133 B<I<TYPE>> private key data organized in a type specific structure.
135 B<d2i_I<TYPE>PublicKey>() and derivates thereof decode DER encoded
136 B<I<TYPE>> public key data organized in a type specific structure.
138 B<d2i_I<TYPE>params>() and derivates thereof decode DER encoded B<I<TYPE>>
139 key parameters organized in a type specific structure.
141 B<d2i_I<TYPE>_PUBKEY>() and derivates thereof decode DER encoded B<I<TYPE>>
142 public key data organized in a B<SubjectPublicKeyInfo> structure.
144 B<i2d_I<TYPE>PrivateKey>() and derivates thereof encode the private key
145 B<I<TYPE>> data into a type specific DER encoded structure.
147 B<i2d_I<TYPE>PublicKey>() and derivates thereof encode the public key
148 B<I<TYPE>> data into a type specific DER encoded structure.
150 B<i2d_I<TYPE>params>() and derivates thereof encode the B<I<TYPE>> key
151 parameters data into a type specific DER encoded structure.
153 B<i2d_I<TYPE>_PUBKEY>() and derivates thereof encode the public key
154 B<I<TYPE>> data into a DER encoded B<SubjectPublicKeyInfo> structure.
156 For example, d2i_RSAPrivateKey() and d2i_RSAPublicKey() expects the
157 structure defined by PKCS#1.
158 Similarly, i2d_RSAPrivateKey() and i2d_RSAPublicKey() produce DER encoded
159 string organized according to PKCS#1.
163 Migration from the diverse B<I<TYPE>>s requires using corresponding new
164 OpenSSL types. For all B<I<TYPE>>s described here, the corresponding new
165 type is B<EVP_PKEY>. The rest of this section assumes that this has been
166 done, exactly how to do that is described elsewhere.
168 There are two migration paths:
175 b<d2i_I<TYPE>PrivateKey()> with L<d2i_PrivateKey(3)>,
176 b<d2i_I<TYPE>PublicKey()> with L<d2i_PublicKey(3)>,
177 b<d2i_I<TYPE>params()> with L<d2i_KeyParams(3)>,
178 b<d2i_I<TYPE>_PUBKEY()> with L<d2i_PUBKEY(3)>,
179 b<i2d_I<TYPE>PrivateKey()> with L<i2d_PrivateKey(3)>,
180 b<i2d_I<TYPE>PublicKey()> with L<i2d_PublicKey(3)>,
181 b<i2d_I<TYPE>params()> with L<i2d_KeyParams(3)>,
182 b<i2d_I<TYPE>_PUBKEY()> with L<i2d_PUBKEY(3)>.
183 A caveat is that L<i2d_PrivateKey(3)> may output a DER encoded PKCS#8
184 outermost structure instead of the type specific structure, and that
185 L<d2i_PrivateKey(3)> recognises and unpacks a PKCS#8 structures.
189 Use L<OSSL_DECODER(3)> and L<OSSL_ENCODER(3)>. How to migrate is described
190 below. All those descriptions assume that the key to be encoded is in the
195 =head3 Migrating B<i2d> functions to B<OSSL_ENCODER>
197 The exact L<OSSL_ENCODER(3)> output is driven by arguments rather than by
198 function names. The sample code to get DER encoded output in a type
199 specific structure is uniform, the only things that vary are the selection
200 of what part of the B<EVP_PKEY> should be output, and the structure. The
201 B<i2d> functions names can therefore be translated into two variables,
202 I<selection> and I<structure> as follows:
206 =item B<i2d_I<TYPE>PrivateKey>() translates into:
208 int selection = EVP_PKEY_PRIVATE_KEY;
209 const char *structure = "type-specific";
211 =item B<i2d_I<TYPE>PublicKey>() translates into:
213 int selection = EVP_PKEY_PUBLIC_KEY;
214 const char *structure = "type-specific";
216 =item B<i2d_I<TYPE>params>() translates into:
218 int selection = EVP_PKEY_PARAMETERS;
219 const char *structure = "type-specific";
221 =item B<i2d_I<TYPE>_PUBKEY>() translates into:
223 int selection = EVP_PKEY_PUBLIC_KEY;
224 const char *structure = "SubjectPublicKeyInfo";
228 The following sample code does the rest of the work:
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,
236 /* fatal error handling */
238 if (OSSL_ENCODER_CTX_get_num_encoders(ctx) == 0) {
239 OSSL_ENCODER_CTX_free(ctx);
240 /* non-fatal error handling */
242 if (!OSSL_ENCODER_to_data(ctx, &p, &len)) {
243 OSSL_ENCODER_CTX_free(ctx);
246 OSSL_ENCODER_CTX_free(ctx);
248 =for comment TODO: a similar section on OSSL_DECODER is to be added
252 The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
253 "internal" (that is, an internal C structure) and "DER" respectively.
254 So B<i2d_I<TYPE>>() converts from internal to DER.
256 The functions can also understand B<BER> forms.
258 The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
259 populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
260 empty structure such as that returned by TYPE_new().
262 The encoded data is in binary form and may contain embedded zeros.
263 Therefore, any FILE pointers or BIOs should be opened in binary mode.
264 Functions such as strlen() will B<not> return the correct length
265 of the encoded structure.
267 The ways that I<*ppin> and I<*ppout> are incremented after the operation
268 can trap the unwary. See the B<WARNINGS> section in L<d2i_X509(3)> for some
270 The reason for this-auto increment behaviour is to reflect a typical
271 usage of ASN1 functions: after one structure is encoded or decoded
272 another will be processed after it.
274 The following points about the data types might be useful:
280 Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
282 =item B<DSAPublicKey>, B<DSAPrivateKey>
284 Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
285 L<PEM_write_PrivateKey(3)>, or similar instead.
291 B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
292 B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has
293 been used with a valid structure being passed in via I<a>, then the object is
294 freed in the event of error and I<*a> is set to NULL.
296 B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
297 value if an error occurs.
299 B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
304 L<OSSL_ENCODER(3)>, L<OSSL_DECODER(3)>,
305 L<d2i_PrivateKey(3)>, L<d2i_PublicKey(3)>, L<d2i_KeyParams(3)>,
307 L<i2d_PrivateKey(3)>, L<i2d_PublicKey(3)>, L<i2d_KeyParams(3)>,
312 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
314 Licensed under the Apache License 2.0 (the "License"). You may not use
315 this file except in compliance with the License. You can obtain a copy
316 in the file LICENSE in the source distribution or at
317 L<https://www.openssl.org/source/license.html>.