i2d_EC_PUBKEY_fp(3ossl)

1D2I_RSAPRIVATEKEY(3ossl)            OpenSSL           D2I_RSAPRIVATEKEY(3ossl)
2
3
4

NAME

6       d2i_DSAPrivateKey, d2i_DSAPrivateKey_bio, d2i_DSAPrivateKey_fp,
7       d2i_DSAPublicKey, d2i_DSA_PUBKEY, d2i_DSA_PUBKEY_bio,
8       d2i_DSA_PUBKEY_fp, d2i_DSAparams, d2i_RSAPrivateKey,
9       d2i_RSAPrivateKey_bio, d2i_RSAPrivateKey_fp, d2i_RSAPublicKey,
10       d2i_RSAPublicKey_bio, d2i_RSAPublicKey_fp, d2i_RSA_PUBKEY,
11       d2i_RSA_PUBKEY_bio, d2i_RSA_PUBKEY_fp, d2i_DHparams, d2i_DHparams_bio,
12       d2i_DHparams_fp, d2i_ECPKParameters, d2i_ECParameters,
13       d2i_ECPrivateKey, d2i_ECPrivateKey_bio, d2i_ECPrivateKey_fp,
14       d2i_EC_PUBKEY, d2i_EC_PUBKEY_bio, d2i_EC_PUBKEY_fp, i2d_RSAPrivateKey,
15       i2d_RSAPrivateKey_bio, i2d_RSAPrivateKey_fp, i2d_RSAPublicKey,
16       i2d_RSAPublicKey_bio, i2d_RSAPublicKey_fp, i2d_RSA_PUBKEY,
17       i2d_RSA_PUBKEY_bio, i2d_RSA_PUBKEY_fp, i2d_DHparams, i2d_DHparams_bio,
18       i2d_DHparams_fp, i2d_DSAPrivateKey, i2d_DSAPrivateKey_bio,
19       i2d_DSAPrivateKey_fp, i2d_DSAPublicKey, i2d_DSA_PUBKEY,
20       i2d_DSA_PUBKEY_bio, i2d_DSA_PUBKEY_fp, i2d_DSAparams,
21       i2d_ECPKParameters, i2d_ECParameters, i2d_ECPrivateKey,
22       i2d_ECPrivateKey_bio, i2d_ECPrivateKey_fp, i2d_EC_PUBKEY,
23       i2d_EC_PUBKEY_bio, i2d_EC_PUBKEY_fp - DEPRECATED
24

SYNOPSIS

26       The following functions have been deprecated since OpenSSL 3.0, and can
27       be hidden entirely by defining OPENSSL_API_COMPAT with a suitable
28       version value, see openssl_user_macros(7):
29
30        TYPE *d2i_TYPEPrivateKey(TYPE **a, const unsigned char **ppin, long length);
31        TYPE *d2i_TYPEPrivateKey_bio(BIO *bp, TYPE **a);
32        TYPE *d2i_TYPEPrivateKey_fp(FILE *fp, TYPE **a);
33        TYPE *d2i_TYPEPublicKey(TYPE **a, const unsigned char **ppin, long length);
34        TYPE *d2i_TYPEPublicKey_bio(BIO *bp, TYPE **a);
35        TYPE *d2i_TYPEPublicKey_fp(FILE *fp, TYPE **a);
36        TYPE *d2i_TYPEparams(TYPE **a, const unsigned char **ppin, long length);
37        TYPE *d2i_TYPEparams_bio(BIO *bp, TYPE **a);
38        TYPE *d2i_TYPEparams_fp(FILE *fp, TYPE **a);
39        TYPE *d2i_TYPE_PUBKEY(TYPE **a, const unsigned char **ppin, long length);
40        TYPE *d2i_TYPE_PUBKEY_bio(BIO *bp, TYPE **a);
41        TYPE *d2i_TYPE_PUBKEY_fp(FILE *fp, TYPE **a);
42
43        int i2d_TYPEPrivateKey(const TYPE *a, unsigned char **ppout);
44        int i2d_TYPEPrivateKey(TYPE *a, unsigned char **ppout);
45        int i2d_TYPEPrivateKey_fp(FILE *fp, const TYPE *a);
46        int i2d_TYPEPrivateKey_fp(FILE *fp, TYPE *a);
47        int i2d_TYPEPrivateKey_bio(BIO *bp, const TYPE *a);
48        int i2d_TYPEPrivateKey_bio(BIO *bp, TYPE *a);
49        int i2d_TYPEPublicKey(const TYPE *a, unsigned char **ppout);
50        int i2d_TYPEPublicKey(TYPE *a, unsigned char **ppout);
51        int i2d_TYPEPublicKey_fp(FILE *fp, const TYPE *a);
52        int i2d_TYPEPublicKey_fp(FILE *fp, TYPE *a);
53        int i2d_TYPEPublicKey_bio(BIO *bp, const TYPE *a);
54        int i2d_TYPEPublicKey_bio(BIO *bp, TYPE *a);
55        int i2d_TYPEparams(const TYPE *a, unsigned char **ppout);
56        int i2d_TYPEparams(TYPE *a, unsigned char **ppout);
57        int i2d_TYPEparams_fp(FILE *fp, const TYPE *a);
58        int i2d_TYPEparams_fp(FILE *fp, TYPE *a);
59        int i2d_TYPEparams_bio(BIO *bp, const TYPE *a);
60        int i2d_TYPEparams_bio(BIO *bp, TYPE *a);
61        int i2d_TYPE_PUBKEY(const TYPE *a, unsigned char **ppout);
62        int i2d_TYPE_PUBKEY(TYPE *a, unsigned char **ppout);
63        int i2d_TYPE_PUBKEY_fp(FILE *fp, const TYPE *a);
64        int i2d_TYPE_PUBKEY_fp(FILE *fp, TYPE *a);
65        int i2d_TYPE_PUBKEY_bio(BIO *bp, const TYPE *a);
66        int i2d_TYPE_PUBKEY_bio(BIO *bp, TYPE *a);
67

DESCRIPTION

69       All functions described here are deprecated.  Please use
70       OSSL_DECODER(3) instead of the d2i functions and OSSL_ENCODER(3)
71       instead of the i2d functions.  See "Migration" below.
72
73       In the description here, TYPE is used a placeholder for any of the
74       OpenSSL datatypes, such as RSA.  The function parameters ppin and ppout
75       are generally either both named pp in the headers, or in and out.
76
77       All the functions here behave the way that's described in d2i_X509(3).
78
79       Please note that not all functions in the synopsis are available for
80       all key types.  For example, there are no d2i_RSAparams() or
81       i2d_RSAparams(), because the PKCS#1 RSA structure doesn't include any
82       key parameters.
83
84       d2i_TYPEPrivateKey() and derivates thereof decode DER encoded TYPE
85       private key data organized in a type specific structure.
86
87       d2i_TYPEPublicKey() and derivates thereof decode DER encoded TYPE
88       public key data organized in a type specific structure.
89
90       d2i_TYPEparams() and derivates thereof decode DER encoded TYPE key
91       parameters organized in a type specific structure.
92
93       d2i_TYPE_PUBKEY() and derivates thereof decode DER encoded TYPE public
94       key data organized in a SubjectPublicKeyInfo structure.
95
96       i2d_TYPEPrivateKey() and derivates thereof encode the private key TYPE
97       data into a type specific DER encoded structure.
98
99       i2d_TYPEPublicKey() and derivates thereof encode the public key TYPE
100       data into a type specific DER encoded structure.
101
102       i2d_TYPEparams() and derivates thereof encode the TYPE key parameters
103       data into a type specific DER encoded structure.
104
105       i2d_TYPE_PUBKEY() and derivates thereof encode the public key TYPE data
106       into a DER encoded SubjectPublicKeyInfo structure.
107
108       For example, d2i_RSAPrivateKey() and d2i_RSAPublicKey() expects the
109       structure defined by PKCS#1.  Similarly, i2d_RSAPrivateKey() and
110       i2d_RSAPublicKey() produce DER encoded string organized according to
111       PKCS#1.
112
113   Migration
114       Migration from the diverse TYPEs requires using corresponding new
115       OpenSSL types.  For all TYPEs described here, the corresponding new
116       type is EVP_PKEY.  The rest of this section assumes that this has been
117       done, exactly how to do that is described elsewhere.
118
119       There are two migration paths:
120
121       •   Replace b<d2i_TYPEPrivateKey()> with d2i_PrivateKey(3),
122           b<d2i_TYPEPublicKey()> with d2i_PublicKey(3), b<d2i_TYPEparams()>
123           with d2i_KeyParams(3), b<d2i_TYPE_PUBKEY()> with d2i_PUBKEY(3),
124           b<i2d_TYPEPrivateKey()> with i2d_PrivateKey(3),
125           b<i2d_TYPEPublicKey()> with i2d_PublicKey(3), b<i2d_TYPEparams()>
126           with i2d_KeyParams(3), b<i2d_TYPE_PUBKEY()> with i2d_PUBKEY(3).  A
127           caveat is that i2d_PrivateKey(3) may output a DER encoded PKCS#8
128           outermost structure instead of the type specific structure, and
129           that d2i_PrivateKey(3) recognises and unpacks a PKCS#8 structures.
130
131       •   Use OSSL_DECODER(3) and OSSL_ENCODER(3).  How to migrate is
132           described below.  All those descriptions assume that the key to be
133           encoded is in the variable pkey.
134
135       Migrating i2d functions to OSSL_ENCODER
136
137       The exact OSSL_ENCODER(3) output is driven by arguments rather than by
138       function names.  The sample code to get DER encoded output in a type
139       specific structure is uniform, the only things that vary are the
140       selection of what part of the EVP_PKEY should be output, and the
141       structure.  The i2d functions names can therefore be translated into
142       two variables, selection and structure as follows:
143
144       i2d_TYPEPrivateKey() translates into:
145            int selection = EVP_PKEY_PRIVATE_KEY;
146            const char *structure = "type-specific";
147
148       i2d_TYPEPublicKey() translates into:
149            int selection = EVP_PKEY_PUBLIC_KEY;
150            const char *structure = "type-specific";
151
152       i2d_TYPEparams() translates into:
153            int selection = EVP_PKEY_PARAMETERS;
154            const char *structure = "type-specific";
155
156       i2d_TYPE_PUBKEY() translates into:
157            int selection = EVP_PKEY_PUBLIC_KEY;
158            const char *structure = "SubjectPublicKeyInfo";
159
160       The following sample code does the rest of the work:
161
162        unsigned char *p = buffer;     /* |buffer| is supplied by the caller */
163        size_t len = buffer_size;      /* assumed be the size of |buffer| */
164        OSSL_ENCODER_CTX *ctx =
165            OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "DER", structure,
166                                          NULL, NULL);
167        if (ctx == NULL) {
168            /* fatal error handling */
169        }
170        if (OSSL_ENCODER_CTX_get_num_encoders(ctx) == 0) {
171            OSSL_ENCODER_CTX_free(ctx);
172            /* non-fatal error handling */
173        }
174        if (!OSSL_ENCODER_to_data(ctx, &p, &len)) {
175            OSSL_ENCODER_CTX_free(ctx);
176            /* error handling */
177        }
178        OSSL_ENCODER_CTX_free(ctx);
179

NOTES

181       The letters i and d in i2d_TYPE() stand for "internal" (that is, an
182       internal C structure) and "DER" respectively.  So i2d_TYPE() converts
183       from internal to DER.
184
185       The functions can also understand BER forms.
186
187       The actual TYPE structure passed to i2d_TYPE() must be a valid
188       populated TYPE structure -- it cannot simply be fed with an empty
189       structure such as that returned by TYPE_new().
190
191       The encoded data is in binary form and may contain embedded zeros.
192       Therefore, any FILE pointers or BIOs should be opened in binary mode.
193       Functions such as strlen() will not return the correct length of the
194       encoded structure.
195
196       The ways that *ppin and *ppout are incremented after the operation can
197       trap the unwary. See the WARNINGS section in d2i_X509(3) for some
198       common errors.  The reason for this-auto increment behaviour is to
199       reflect a typical usage of ASN1 functions: after one structure is
200       encoded or decoded another will be processed after it.
201
202       The following points about the data types might be useful:
203
204       DSA_PUBKEY
205           Represents a DSA public key using a SubjectPublicKeyInfo structure.
206
207       DSAPublicKey, DSAPrivateKey
208           Use a non-standard OpenSSL format and should be avoided; use
209           DSA_PUBKEY, PEM_write_PrivateKey(3), or similar instead.
210

RETURN VALUES

212       d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid TYPE
213       structure or NULL if an error occurs.  If the "reuse" capability has
214       been used with a valid structure being passed in via a, then the object
215       is freed in the event of error and *a is set to NULL.
216
217       i2d_TYPE() returns the number of bytes successfully encoded or a
218       negative value if an error occurs.
219
220       i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
221       occurs.
222

COPYRIGHT

229       Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
230
231       Licensed under the Apache License 2.0 (the "License").  You may not use
232       this file except in compliance with the License.  You can obtain a copy
233       in the file LICENSE in the source distribution or at
234       <https://www.openssl.org/source/license.html>.
235
236
237
2383.1.1                             2023-08-31          D2I_RSAPRIVATEKEY(3ossl)

NAME

SYNOPSIS

DESCRIPTION

NOTES

RETURN VALUES

SEE ALSO

COPYRIGHT