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,
65 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
66 B<OPENSSL_API_COMPAT> with a suitable version value, see
67 L<openssl_user_macros(7)>:
69 TYPE *d2i_TYPEPrivateKey(TYPE **a, const unsigned char **ppin, long length);
70 TYPE *d2i_TYPEPrivateKey_bio(BIO *bp, TYPE **a);
71 TYPE *d2i_TYPEPrivateKey_fp(FILE *fp, TYPE **a);
72 TYPE *d2i_TYPEPublicKey(TYPE **a, const unsigned char **ppin, long length);
73 TYPE *d2i_TYPEPublicKey_bio(BIO *bp, TYPE **a);
74 TYPE *d2i_TYPEPublicKey_fp(FILE *fp, TYPE **a);
75 TYPE *d2i_TYPEparams(TYPE **a, const unsigned char **ppin, long length);
76 TYPE *d2i_TYPEparams_bio(BIO *bp, TYPE **a);
77 TYPE *d2i_TYPEparams_fp(FILE *fp, TYPE **a);
78 TYPE *d2i_TYPE_PUBKEY(TYPE **a, const unsigned char **ppin, long length);
79 TYPE *d2i_TYPE_PUBKEY_bio(BIO *bp, TYPE **a);
80 TYPE *d2i_TYPE_PUBKEY_fp(FILE *fp, TYPE **a);
82 int i2d_TYPEPrivateKey(const TYPE *a, unsigned char **ppout);
83 int i2d_TYPEPrivateKey(TYPE *a, unsigned char **ppout);
84 int i2d_TYPEPrivateKey_fp(FILE *fp, const TYPE *a);
85 int i2d_TYPEPrivateKey_fp(FILE *fp, TYPE *a);
86 int i2d_TYPEPrivateKey_bio(BIO *bp, const TYPE *a);
87 int i2d_TYPEPrivateKey_bio(BIO *bp, TYPE *a);
88 int i2d_TYPEPublicKey(const TYPE *a, unsigned char **ppout);
89 int i2d_TYPEPublicKey(TYPE *a, unsigned char **ppout);
90 int i2d_TYPEPublicKey_fp(FILE *fp, const TYPE *a);
91 int i2d_TYPEPublicKey_fp(FILE *fp, TYPE *a);
92 int i2d_TYPEPublicKey_bio(BIO *bp, const TYPE *a);
93 int i2d_TYPEPublicKey_bio(BIO *bp, TYPE *a);
94 int i2d_TYPEparams(const TYPE *a, unsigned char **ppout);
95 int i2d_TYPEparams(TYPE *a, unsigned char **ppout);
96 int i2d_TYPEparams_fp(FILE *fp, const TYPE *a);
97 int i2d_TYPEparams_fp(FILE *fp, TYPE *a);
98 int i2d_TYPEparams_bio(BIO *bp, const TYPE *a);
99 int i2d_TYPEparams_bio(BIO *bp, TYPE *a);
100 int i2d_TYPE_PUBKEY(const TYPE *a, unsigned char **ppout);
101 int i2d_TYPE_PUBKEY(TYPE *a, unsigned char **ppout);
102 int i2d_TYPE_PUBKEY_fp(FILE *fp, const TYPE *a);
103 int i2d_TYPE_PUBKEY_fp(FILE *fp, TYPE *a);
104 int i2d_TYPE_PUBKEY_bio(BIO *bp, const TYPE *a);
105 int i2d_TYPE_PUBKEY_bio(BIO *bp, TYPE *a);
109 All functions described here are deprecated. Please use L<OSSL_DECODER(3)>
110 instead of the B<d2i> functions and L<OSSL_ENCODER(3)> instead of the B<i2d>
111 functions. See L</Migration> below.
113 In the description here, B<I<TYPE>> is used a placeholder for any of the
114 OpenSSL datatypes, such as B<RSA>.
115 The function parameters I<ppin> and I<ppout> are generally either both named
116 I<pp> in the headers, or I<in> and I<out>.
118 All the functions here behave the way that's described in L<d2i_X509(3)>.
120 Please note that not all functions in the synopsis are available for all key
121 types. For example, there are no d2i_RSAparams() or i2d_RSAparams(),
122 because the PKCS#1 B<RSA> structure doesn't include any key parameters.
124 B<d2i_I<TYPE>PrivateKey>() and derivates thereof decode DER encoded
125 B<I<TYPE>> private key data organized in a type specific structure.
127 B<d2i_I<TYPE>PublicKey>() and derivates thereof decode DER encoded
128 B<I<TYPE>> public key data organized in a type specific structure.
130 B<d2i_I<TYPE>params>() and derivates thereof decode DER encoded B<I<TYPE>>
131 key parameters organized in a type specific structure.
133 B<d2i_I<TYPE>_PUBKEY>() and derivates thereof decode DER encoded B<I<TYPE>>
134 public key data organized in a B<SubjectPublicKeyInfo> structure.
136 B<i2d_I<TYPE>PrivateKey>() and derivates thereof encode the private key
137 B<I<TYPE>> data into a type specific DER encoded structure.
139 B<i2d_I<TYPE>PublicKey>() and derivates thereof encode the public key
140 B<I<TYPE>> data into a type specific DER encoded structure.
142 B<i2d_I<TYPE>params>() and derivates thereof encode the B<I<TYPE>> key
143 parameters data into a type specific DER encoded structure.
145 B<i2d_I<TYPE>_PUBKEY>() and derivates thereof encode the public key
146 B<I<TYPE>> data into a DER encoded B<SubjectPublicKeyInfo> structure.
148 For example, d2i_RSAPrivateKey() and d2i_RSAPublicKey() expects the
149 structure defined by PKCS#1.
150 Similarly, i2d_RSAPrivateKey() and i2d_RSAPublicKey() produce DER encoded
151 string organized according to PKCS#1.
155 Migration from the diverse B<I<TYPE>>s requires using corresponding new
156 OpenSSL types. For all B<I<TYPE>>s described here, the corresponding new
157 type is B<EVP_PKEY>. The rest of this section assumes that this has been
158 done, exactly how to do that is described elsewhere.
160 There are two migration paths:
167 b<d2i_I<TYPE>PrivateKey()> with L<d2i_PrivateKey(3)>,
168 b<d2i_I<TYPE>PublicKey()> with L<d2i_PublicKey(3)>,
169 b<d2i_I<TYPE>params()> with L<d2i_KeyParams(3)>,
170 b<d2i_I<TYPE>_PUBKEY()> with L<d2i_PUBKEY(3)>,
171 b<i2d_I<TYPE>PrivateKey()> with L<i2d_PrivateKey(3)>,
172 b<i2d_I<TYPE>PublicKey()> with L<i2d_PublicKey(3)>,
173 b<i2d_I<TYPE>params()> with L<i2d_KeyParams(3)>,
174 b<i2d_I<TYPE>_PUBKEY()> with L<i2d_PUBKEY(3)>.
175 A caveat is that L<i2d_PrivateKey(3)> may output a DER encoded PKCS#8
176 outermost structure instead of the type specific structure, and that
177 L<d2i_PrivateKey(3)> recognises and unpacks a PKCS#8 structures.
181 Use L<OSSL_DECODER(3)> and L<OSSL_ENCODER(3)>. How to migrate is described
182 below. All those descriptions assume that the key to be encoded is in the
187 =head3 Migrating B<i2d> functions to B<OSSL_ENCODER>
189 The exact L<OSSL_ENCODER(3)> output is driven by arguments rather than by
190 function names. The sample code to get DER encoded output in a type
191 specific structure is uniform, the only things that vary are the selection
192 of what part of the B<EVP_PKEY> should be output, and the structure. The
193 B<i2d> functions names can therefore be translated into two variables,
194 I<selection> and I<structure> as follows:
198 =item B<i2d_I<TYPE>PrivateKey>() translates into:
200 int selection = EVP_PKEY_PRIVATE_KEY;
201 const char *structure = "type-specific";
203 =item B<i2d_I<TYPE>PublicKey>() translates into:
205 int selection = EVP_PKEY_PUBLIC_KEY;
206 const char *structure = "type-specific";
208 =item B<i2d_I<TYPE>params>() translates into:
210 int selection = EVP_PKEY_PARAMETERS;
211 const char *structure = "type-specific";
213 =item B<i2d_I<TYPE>_PUBKEY>() translates into:
215 int selection = EVP_PKEY_PUBLIC_KEY;
216 const char *structure = "SubjectPublicKeyInfo";
220 The following sample code does the rest of the work:
222 unsigned char *p = buffer; /* |buffer| is supplied by the caller */
223 size_t len = buffer_size; /* assumed be the size of |buffer| */
224 OSSL_ENCODER_CTX *ctx =
225 OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "DER", structure,
228 /* fatal error handling */
230 if (OSSL_ENCODER_CTX_get_num_encoders(ctx) == 0) {
231 OSSL_ENCODER_CTX_free(ctx);
232 /* non-fatal error handling */
234 if (!OSSL_ENCODER_to_data(ctx, &p, &len)) {
235 OSSL_ENCODER_CTX_free(ctx);
238 OSSL_ENCODER_CTX_free(ctx);
240 =for comment TODO: a similar section on OSSL_DECODER is to be added
244 The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
245 "internal" (that is, an internal C structure) and "DER" respectively.
246 So B<i2d_I<TYPE>>() converts from internal to DER.
248 The functions can also understand B<BER> forms.
250 The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
251 populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
252 empty structure such as that returned by TYPE_new().
254 The encoded data is in binary form and may contain embedded zeros.
255 Therefore, any FILE pointers or BIOs should be opened in binary mode.
256 Functions such as strlen() will B<not> return the correct length
257 of the encoded structure.
259 The ways that I<*ppin> and I<*ppout> are incremented after the operation
260 can trap the unwary. See the B<WARNINGS> section for some common
262 The reason for this-auto increment behaviour is to reflect a typical
263 usage of ASN1 functions: after one structure is encoded or decoded
264 another will be processed after it.
266 The following points about the data types might be useful:
272 Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
274 =item B<DSAPublicKey>, B<DSAPrivateKey>
276 Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
277 L<PEM_write_PrivateKey(3)>, or similar instead.
283 B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
284 B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has
285 been used with a valid structure being passed in via I<a>, then the object is
286 freed in the event of error and I<*a> is set to NULL.
288 B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
289 value if an error occurs.
291 B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
296 L<OSSL_ENCODER(3)>, L<OSSL_DECODER(3)>,
297 L<d2i_PrivateKey(3)>, L<d2i_PublicKey(3)>, L<d2i_KeyParams(3)>,
299 L<i2d_PrivateKey(3)>, L<i2d_PublicKey(3)>, L<i2d_KeyParams(3)>,
304 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
306 Licensed under the Apache License 2.0 (the "License"). You may not use
307 this file except in compliance with the License. You can obtain a copy
308 in the file LICENSE in the source distribution or at
309 L<https://www.openssl.org/source/license.html>.