1D2I_X509(3)                         OpenSSL                        D2I_X509(3)
2
3
4

NAME

6       d2i_ACCESS_DESCRIPTION, d2i_ADMISSIONS, d2i_ADMISSION_SYNTAX,
7       d2i_ASIdOrRange, d2i_ASIdentifierChoice, d2i_ASIdentifiers,
8       d2i_ASN1_BIT_STRING, d2i_ASN1_BMPSTRING, d2i_ASN1_ENUMERATED,
9       d2i_ASN1_GENERALIZEDTIME, d2i_ASN1_GENERALSTRING, d2i_ASN1_IA5STRING,
10       d2i_ASN1_INTEGER, d2i_ASN1_NULL, d2i_ASN1_OBJECT,
11       d2i_ASN1_OCTET_STRING, d2i_ASN1_PRINTABLE, d2i_ASN1_PRINTABLESTRING,
12       d2i_ASN1_SEQUENCE_ANY, d2i_ASN1_SET_ANY, d2i_ASN1_T61STRING,
13       d2i_ASN1_TIME, d2i_ASN1_TYPE, d2i_ASN1_UINTEGER,
14       d2i_ASN1_UNIVERSALSTRING, d2i_ASN1_UTCTIME, d2i_ASN1_UTF8STRING,
15       d2i_ASN1_VISIBLESTRING, d2i_ASRange, d2i_AUTHORITY_INFO_ACCESS,
16       d2i_AUTHORITY_KEYID, d2i_BASIC_CONSTRAINTS, d2i_CERTIFICATEPOLICIES,
17       d2i_CMS_ContentInfo, d2i_CMS_ReceiptRequest, d2i_CMS_bio,
18       d2i_CRL_DIST_POINTS, d2i_DHxparams, d2i_DIRECTORYSTRING,
19       d2i_DISPLAYTEXT, d2i_DIST_POINT, d2i_DIST_POINT_NAME,
20       d2i_DSAPrivateKey, d2i_DSAPrivateKey_bio, d2i_DSAPrivateKey_fp,
21       d2i_DSAPublicKey, d2i_DSA_PUBKEY, d2i_DSA_PUBKEY_bio,
22       d2i_DSA_PUBKEY_fp, d2i_DSA_SIG, d2i_DSAparams, d2i_ECDSA_SIG,
23       d2i_ECPKParameters, d2i_ECParameters, d2i_ECPrivateKey,
24       d2i_ECPrivateKey_bio, d2i_ECPrivateKey_fp, d2i_EC_PUBKEY,
25       d2i_EC_PUBKEY_bio, d2i_EC_PUBKEY_fp, d2i_EDIPARTYNAME, d2i_ESS_CERT_ID,
26       d2i_ESS_ISSUER_SERIAL, d2i_ESS_SIGNING_CERT, d2i_EXTENDED_KEY_USAGE,
27       d2i_GENERAL_NAME, d2i_GENERAL_NAMES, d2i_IPAddressChoice,
28       d2i_IPAddressFamily, d2i_IPAddressOrRange, d2i_IPAddressRange,
29       d2i_ISSUING_DIST_POINT, d2i_NAMING_AUTHORITY,
30       d2i_NETSCAPE_CERT_SEQUENCE, d2i_NETSCAPE_SPKAC, d2i_NETSCAPE_SPKI,
31       d2i_NOTICEREF, d2i_OCSP_BASICRESP, d2i_OCSP_CERTID,
32       d2i_OCSP_CERTSTATUS, d2i_OCSP_CRLID, d2i_OCSP_ONEREQ, d2i_OCSP_REQINFO,
33       d2i_OCSP_REQUEST, d2i_OCSP_RESPBYTES, d2i_OCSP_RESPDATA,
34       d2i_OCSP_RESPID, d2i_OCSP_RESPONSE, d2i_OCSP_REVOKEDINFO,
35       d2i_OCSP_SERVICELOC, d2i_OCSP_SIGNATURE, d2i_OCSP_SINGLERESP,
36       d2i_OTHERNAME, d2i_PBE2PARAM, d2i_PBEPARAM, d2i_PBKDF2PARAM,
37       d2i_PKCS12, d2i_PKCS12_BAGS, d2i_PKCS12_MAC_DATA, d2i_PKCS12_SAFEBAG,
38       d2i_PKCS12_bio, d2i_PKCS12_fp, d2i_PKCS7, d2i_PKCS7_DIGEST,
39       d2i_PKCS7_ENCRYPT, d2i_PKCS7_ENC_CONTENT, d2i_PKCS7_ENVELOPE,
40       d2i_PKCS7_ISSUER_AND_SERIAL, d2i_PKCS7_RECIP_INFO, d2i_PKCS7_SIGNED,
41       d2i_PKCS7_SIGNER_INFO, d2i_PKCS7_SIGN_ENVELOPE, d2i_PKCS7_bio,
42       d2i_PKCS7_fp, d2i_PKCS8_PRIV_KEY_INFO, d2i_PKCS8_PRIV_KEY_INFO_bio,
43       d2i_PKCS8_PRIV_KEY_INFO_fp, d2i_PKCS8_bio, d2i_PKCS8_fp,
44       d2i_PKEY_USAGE_PERIOD, d2i_POLICYINFO, d2i_POLICYQUALINFO,
45       d2i_PROFESSION_INFO, d2i_PROXY_CERT_INFO_EXTENSION, d2i_PROXY_POLICY,
46       d2i_RSAPrivateKey, d2i_RSAPrivateKey_bio, d2i_RSAPrivateKey_fp,
47       d2i_RSAPublicKey, d2i_RSAPublicKey_bio, d2i_RSAPublicKey_fp,
48       d2i_RSA_OAEP_PARAMS, d2i_RSA_PSS_PARAMS, d2i_RSA_PUBKEY,
49       d2i_RSA_PUBKEY_bio, d2i_RSA_PUBKEY_fp, d2i_SCRYPT_PARAMS, d2i_SCT_LIST,
50       d2i_SXNET, d2i_SXNETID, d2i_TS_ACCURACY, d2i_TS_MSG_IMPRINT,
51       d2i_TS_MSG_IMPRINT_bio, d2i_TS_MSG_IMPRINT_fp, d2i_TS_REQ,
52       d2i_TS_REQ_bio, d2i_TS_REQ_fp, d2i_TS_RESP, d2i_TS_RESP_bio,
53       d2i_TS_RESP_fp, d2i_TS_STATUS_INFO, d2i_TS_TST_INFO,
54       d2i_TS_TST_INFO_bio, d2i_TS_TST_INFO_fp, d2i_USERNOTICE, d2i_X509,
55       d2i_X509_ALGOR, d2i_X509_ALGORS, d2i_X509_ATTRIBUTE, d2i_X509_CERT_AUX,
56       d2i_X509_CINF, d2i_X509_CRL, d2i_X509_CRL_INFO, d2i_X509_CRL_bio,
57       d2i_X509_CRL_fp, d2i_X509_EXTENSION, d2i_X509_EXTENSIONS,
58       d2i_X509_NAME, d2i_X509_NAME_ENTRY, d2i_X509_PUBKEY, d2i_X509_REQ,
59       d2i_X509_REQ_INFO, d2i_X509_REQ_bio, d2i_X509_REQ_fp, d2i_X509_REVOKED,
60       d2i_X509_SIG, d2i_X509_VAL, i2d_ACCESS_DESCRIPTION, i2d_ADMISSIONS,
61       i2d_ADMISSION_SYNTAX, i2d_ASIdOrRange, i2d_ASIdentifierChoice,
62       i2d_ASIdentifiers, i2d_ASN1_BIT_STRING, i2d_ASN1_BMPSTRING,
63       i2d_ASN1_ENUMERATED, i2d_ASN1_GENERALIZEDTIME, i2d_ASN1_GENERALSTRING,
64       i2d_ASN1_IA5STRING, i2d_ASN1_INTEGER, i2d_ASN1_NULL, i2d_ASN1_OBJECT,
65       i2d_ASN1_OCTET_STRING, i2d_ASN1_PRINTABLE, i2d_ASN1_PRINTABLESTRING,
66       i2d_ASN1_SEQUENCE_ANY, i2d_ASN1_SET_ANY, i2d_ASN1_T61STRING,
67       i2d_ASN1_TIME, i2d_ASN1_TYPE, i2d_ASN1_UNIVERSALSTRING,
68       i2d_ASN1_UTCTIME, i2d_ASN1_UTF8STRING, i2d_ASN1_VISIBLESTRING,
69       i2d_ASN1_bio_stream, i2d_ASRange, i2d_AUTHORITY_INFO_ACCESS,
70       i2d_AUTHORITY_KEYID, i2d_BASIC_CONSTRAINTS, i2d_CERTIFICATEPOLICIES,
71       i2d_CMS_ContentInfo, i2d_CMS_ReceiptRequest, i2d_CMS_bio,
72       i2d_CRL_DIST_POINTS, i2d_DHxparams, i2d_DIRECTORYSTRING,
73       i2d_DISPLAYTEXT, i2d_DIST_POINT, i2d_DIST_POINT_NAME,
74       i2d_DSAPrivateKey, i2d_DSAPrivateKey_bio, i2d_DSAPrivateKey_fp,
75       i2d_DSAPublicKey, i2d_DSA_PUBKEY, i2d_DSA_PUBKEY_bio,
76       i2d_DSA_PUBKEY_fp, i2d_DSA_SIG, i2d_DSAparams, i2d_ECDSA_SIG,
77       i2d_ECPKParameters, i2d_ECParameters, i2d_ECPrivateKey,
78       i2d_ECPrivateKey_bio, i2d_ECPrivateKey_fp, i2d_EC_PUBKEY,
79       i2d_EC_PUBKEY_bio, i2d_EC_PUBKEY_fp, i2d_EDIPARTYNAME, i2d_ESS_CERT_ID,
80       i2d_ESS_ISSUER_SERIAL, i2d_ESS_SIGNING_CERT, i2d_EXTENDED_KEY_USAGE,
81       i2d_GENERAL_NAME, i2d_GENERAL_NAMES, i2d_IPAddressChoice,
82       i2d_IPAddressFamily, i2d_IPAddressOrRange, i2d_IPAddressRange,
83       i2d_ISSUING_DIST_POINT, i2d_NAMING_AUTHORITY,
84       i2d_NETSCAPE_CERT_SEQUENCE, i2d_NETSCAPE_SPKAC, i2d_NETSCAPE_SPKI,
85       i2d_NOTICEREF, i2d_OCSP_BASICRESP, i2d_OCSP_CERTID,
86       i2d_OCSP_CERTSTATUS, i2d_OCSP_CRLID, i2d_OCSP_ONEREQ, i2d_OCSP_REQINFO,
87       i2d_OCSP_REQUEST, i2d_OCSP_RESPBYTES, i2d_OCSP_RESPDATA,
88       i2d_OCSP_RESPID, i2d_OCSP_RESPONSE, i2d_OCSP_REVOKEDINFO,
89       i2d_OCSP_SERVICELOC, i2d_OCSP_SIGNATURE, i2d_OCSP_SINGLERESP,
90       i2d_OTHERNAME, i2d_PBE2PARAM, i2d_PBEPARAM, i2d_PBKDF2PARAM,
91       i2d_PKCS12, i2d_PKCS12_BAGS, i2d_PKCS12_MAC_DATA, i2d_PKCS12_SAFEBAG,
92       i2d_PKCS12_bio, i2d_PKCS12_fp, i2d_PKCS7, i2d_PKCS7_DIGEST,
93       i2d_PKCS7_ENCRYPT, i2d_PKCS7_ENC_CONTENT, i2d_PKCS7_ENVELOPE,
94       i2d_PKCS7_ISSUER_AND_SERIAL, i2d_PKCS7_NDEF, i2d_PKCS7_RECIP_INFO,
95       i2d_PKCS7_SIGNED, i2d_PKCS7_SIGNER_INFO, i2d_PKCS7_SIGN_ENVELOPE,
96       i2d_PKCS7_bio, i2d_PKCS7_fp, i2d_PKCS8PrivateKeyInfo_bio,
97       i2d_PKCS8PrivateKeyInfo_fp, i2d_PKCS8_PRIV_KEY_INFO,
98       i2d_PKCS8_PRIV_KEY_INFO_bio, i2d_PKCS8_PRIV_KEY_INFO_fp, i2d_PKCS8_bio,
99       i2d_PKCS8_fp, i2d_PKEY_USAGE_PERIOD, i2d_POLICYINFO,
100       i2d_POLICYQUALINFO, i2d_PROFESSION_INFO, i2d_PROXY_CERT_INFO_EXTENSION,
101       i2d_PROXY_POLICY, i2d_RSAPrivateKey, i2d_RSAPrivateKey_bio,
102       i2d_RSAPrivateKey_fp, i2d_RSAPublicKey, i2d_RSAPublicKey_bio,
103       i2d_RSAPublicKey_fp, i2d_RSA_OAEP_PARAMS, i2d_RSA_PSS_PARAMS,
104       i2d_RSA_PUBKEY, i2d_RSA_PUBKEY_bio, i2d_RSA_PUBKEY_fp,
105       i2d_SCRYPT_PARAMS, i2d_SCT_LIST, i2d_SXNET, i2d_SXNETID,
106       i2d_TS_ACCURACY, i2d_TS_MSG_IMPRINT, i2d_TS_MSG_IMPRINT_bio,
107       i2d_TS_MSG_IMPRINT_fp, i2d_TS_REQ, i2d_TS_REQ_bio, i2d_TS_REQ_fp,
108       i2d_TS_RESP, i2d_TS_RESP_bio, i2d_TS_RESP_fp, i2d_TS_STATUS_INFO,
109       i2d_TS_TST_INFO, i2d_TS_TST_INFO_bio, i2d_TS_TST_INFO_fp,
110       i2d_USERNOTICE, i2d_X509, i2d_X509_ALGOR, i2d_X509_ALGORS,
111       i2d_X509_ATTRIBUTE, i2d_X509_CERT_AUX, i2d_X509_CINF, i2d_X509_CRL,
112       i2d_X509_CRL_INFO, i2d_X509_CRL_bio, i2d_X509_CRL_fp,
113       i2d_X509_EXTENSION, i2d_X509_EXTENSIONS, i2d_X509_NAME,
114       i2d_X509_NAME_ENTRY, i2d_X509_PUBKEY, i2d_X509_REQ, i2d_X509_REQ_INFO,
115       i2d_X509_REQ_bio, i2d_X509_REQ_fp, i2d_X509_REVOKED, i2d_X509_SIG,
116       i2d_X509_VAL, - convert objects from/to ASN.1/DER representation
117

SYNOPSIS

119        TYPE *d2i_TYPE(TYPE **a, const unsigned char **ppin, long length);
120        TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
121        TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
122
123        int i2d_TYPE(TYPE *a, unsigned char **ppout);
124        int i2d_TYPE_fp(FILE *fp, TYPE *a);
125        int i2d_TYPE_bio(BIO *bp, TYPE *a);
126

DESCRIPTION

128       In the description here, TYPE is used a placeholder for any of the
129       OpenSSL datatypes, such as X509_CRL.  The function parameters ppin and
130       ppout are generally either both named pp in the headers, or in and out.
131
132       These functions convert OpenSSL objects to and from their ASN.1/DER
133       encoding.  Unlike the C structures which can have pointers to sub-
134       objects within, the DER is a serialized encoding, suitable for sending
135       over the network, writing to a file, and so on.
136
137       d2i_TYPE() attempts to decode len bytes at *ppin. If successful a
138       pointer to the TYPE structure is returned and *ppin is incremented to
139       the byte following the parsed data.  If a is not NULL then a pointer to
140       the returned structure is also written to *a.  If an error occurred
141       then NULL is returned.
142
143       On a successful return, if *a is not NULL then it is assumed that *a
144       contains a valid TYPE structure and an attempt is made to reuse it.
145       This "reuse" capability is present for historical compatibility but its
146       use is strongly discouraged (see BUGS below, and the discussion in the
147       RETURN VALUES section).
148
149       d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts to parse
150       data from BIO bp.
151
152       d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts to parse data
153       from FILE pointer fp.
154
155       i2d_TYPE() encodes the structure pointed to by a into DER format.  If
156       ppout is not NULL, it writes the DER encoded data to the buffer at
157       *ppout, and increments it to point after the data just written.  If the
158       return value is negative an error occurred, otherwise it returns the
159       length of the encoded data.
160
161       If *ppout is NULL memory will be allocated for a buffer and the encoded
162       data written to it. In this case *ppout is not incremented and it
163       points to the start of the data just written.
164
165       i2d_TYPE_bio() is similar to i2d_TYPE() except it writes the encoding
166       of the structure a to BIO bp and it returns 1 for success and 0 for
167       failure.
168
169       i2d_TYPE_fp() is similar to i2d_TYPE() except it writes the encoding of
170       the structure a to BIO bp and it returns 1 for success and 0 for
171       failure.
172
173       These routines do not encrypt private keys and therefore offer no
174       security; use PEM_write_PrivateKey(3) or similar for writing to files.
175

NOTES

177       The letters i and d in i2d_TYPE stand for "internal" (that is, an
178       internal C structure) and "DER" respectively.  So i2d_TYPE converts
179       from internal to DER.
180
181       The functions can also understand BER forms.
182
183       The actual TYPE structure passed to i2d_TYPE() must be a valid
184       populated TYPE structure -- it cannot simply be fed with an empty
185       structure such as that returned by TYPE_new().
186
187       The encoded data is in binary form and may contain embedded zeros.
188       Therefore, any FILE pointers or BIOs should be opened in binary mode.
189       Functions such as strlen() will not return the correct length of the
190       encoded structure.
191
192       The ways that *ppin and *ppout are incremented after the operation can
193       trap the unwary. See the WARNINGS section for some common errors.  The
194       reason for this-auto increment behaviour is to reflect a typical usage
195       of ASN1 functions: after one structure is encoded or decoded another
196       will be processed after it.
197
198       The following points about the data types might be useful:
199
200       ASN1_OBJECT
201           Represents an ASN1 OBJECT IDENTIFIER.
202
203       DHparams
204           Represents a PKCS#3 DH parameters structure.
205
206       DHxparams
207           Represents an ANSI X9.42 DH parameters structure.
208
209       DSA_PUBKEY
210           Represents a DSA public key using a SubjectPublicKeyInfo structure.
211
212       DSAPublicKey, DSAPrivateKey
213           Use a non-standard OpenSSL format and should be avoided; use
214           DSA_PUBKEY, PEM_write_PrivateKey(3), or similar instead.
215
216       ECDSA_SIG
217           Represents an ECDSA signature.
218
219       RSAPublicKey
220           Represents a PKCS#1 RSA public key structure.
221
222       X509_ALGOR
223           Represents an AlgorithmIdentifier structure as used in IETF RFC
224           6960 and elsewhere.
225
226       X509_Name
227           Represents a Name type as used for subject and issuer names in IETF
228           RFC 6960 and elsewhere.
229
230       X509_REQ
231           Represents a PKCS#10 certificate request.
232
233       X509_SIG
234           Represents the DigestInfo structure defined in PKCS#1 and PKCS#7.
235

RETURN VALUES

237       d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid TYPE
238       structure or NULL if an error occurs.  If the "reuse" capability has
239       been used with a valid structure being passed in via a, then the object
240       is freed in the event of error and *a is set to NULL.
241
242       i2d_TYPE() returns the number of bytes successfully encoded or a
243       negative value if an error occurs.
244
245       i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
246       occurs.
247

EXAMPLES

249       Allocate and encode the DER encoding of an X509 structure:
250
251        int len;
252        unsigned char *buf;
253
254        buf = NULL;
255        len = i2d_X509(x, &buf);
256        if (len < 0)
257            /* error */
258
259       Attempt to decode a buffer:
260
261        X509 *x;
262        unsigned char *buf;
263        const unsigned char *p;
264        int len;
265
266        /* Set up buf and len to point to the input buffer. */
267        p = buf;
268        x = d2i_X509(NULL, &p, len);
269        if (x == NULL)
270            /* error */
271
272       Alternative technique:
273
274        X509 *x;
275        unsigned char *buf;
276        const unsigned char *p;
277        int len;
278
279        /* Set up buf and len to point to the input buffer. */
280        p = buf;
281        x = NULL;
282
283        if (d2i_X509(&x, &p, len) == NULL)
284            /* error */
285

WARNINGS

287       Using a temporary variable is mandatory. A common mistake is to attempt
288       to use a buffer directly as follows:
289
290        int len;
291        unsigned char *buf;
292
293        len = i2d_X509(x, NULL);
294        buf = OPENSSL_malloc(len);
295        ...
296        i2d_X509(x, &buf);
297        ...
298        OPENSSL_free(buf);
299
300       This code will result in buf apparently containing garbage because it
301       was incremented after the call to point after the data just written.
302       Also buf will no longer contain the pointer allocated by
303       OPENSSL_malloc() and the subsequent call to OPENSSL_free() is likely to
304       crash.
305
306       Another trap to avoid is misuse of the a argument to d2i_TYPE():
307
308        X509 *x;
309
310        if (d2i_X509(&x, &p, len) == NULL)
311            /* error */
312
313       This will probably crash somewhere in d2i_X509(). The reason for this
314       is that the variable x is uninitialized and an attempt will be made to
315       interpret its (invalid) value as an X509 structure, typically causing a
316       segmentation violation. If x is set to NULL first then this will not
317       happen.
318

BUGS

320       In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when *a
321       is valid is broken and some parts of the reused structure may persist
322       if they are not present in the new one. Additionally, in versions of
323       OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error
324       occurs the behaviour is inconsistent. Some functions behaved as
325       described here, while some did not free *a on error and did not set *a
326       to NULL.
327
328       As a result of the above issues the "reuse" behaviour is strongly
329       discouraged.
330
331       i2d_TYPE() will not return an error in many versions of OpenSSL, if
332       mandatory fields are not initialized due to a programming error then
333       the encoded structure may contain invalid data or omit the fields
334       entirely and will not be parsed by d2i_TYPE(). This may be fixed in
335       future so code should not assume that i2d_TYPE() will always succeed.
336
337       Any function which encodes a structure (i2d_TYPE(), i2d_TYPE() or
338       i2d_TYPE()) may return a stale encoding if the structure has been
339       modified after deserialization or previous serialization. This is
340       because some objects cache the encoding for efficiency reasons.
341
343       Copyright 1998-2020 The OpenSSL Project Authors. All Rights Reserved.
344
345       Licensed under the OpenSSL license (the "License").  You may not use
346       this file except in compliance with the License.  You can obtain a copy
347       in the file LICENSE in the source distribution or at
348       <https://www.openssl.org/source/license.html>.
349
350
351
3521.1.1l                            2021-09-15                       D2I_X509(3)
Impressum