1D2I_X509(3ossl)                     OpenSSL                    D2I_X509(3ossl)
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, d2i_DSA_SIG,
20       d2i_ECDSA_SIG, d2i_EDIPARTYNAME, d2i_ESS_CERT_ID, d2i_ESS_CERT_ID_V2,
21       d2i_ESS_ISSUER_SERIAL, d2i_ESS_SIGNING_CERT, d2i_ESS_SIGNING_CERT_V2,
22       d2i_EXTENDED_KEY_USAGE, d2i_GENERAL_NAME, d2i_GENERAL_NAMES,
23       d2i_IPAddressChoice, d2i_IPAddressFamily, d2i_IPAddressOrRange,
24       d2i_IPAddressRange, d2i_ISSUER_SIGN_TOOL, d2i_ISSUING_DIST_POINT,
25       d2i_NAMING_AUTHORITY, d2i_NETSCAPE_CERT_SEQUENCE, d2i_NETSCAPE_SPKAC,
26       d2i_NETSCAPE_SPKI, d2i_NOTICEREF, d2i_OCSP_BASICRESP, d2i_OCSP_CERTID,
27       d2i_OCSP_CERTSTATUS, d2i_OCSP_CRLID, d2i_OCSP_ONEREQ, d2i_OCSP_REQINFO,
28       d2i_OCSP_REQUEST, d2i_OCSP_RESPBYTES, d2i_OCSP_RESPDATA,
29       d2i_OCSP_RESPID, d2i_OCSP_RESPONSE, d2i_OCSP_REVOKEDINFO,
30       d2i_OCSP_SERVICELOC, d2i_OCSP_SIGNATURE, d2i_OCSP_SINGLERESP,
31       d2i_OSSL_CMP_MSG, d2i_OSSL_CMP_PKIHEADER, d2i_OSSL_CMP_PKISI,
32       d2i_OSSL_CRMF_CERTID, d2i_OSSL_CRMF_CERTTEMPLATE,
33       d2i_OSSL_CRMF_ENCRYPTEDVALUE, d2i_OSSL_CRMF_MSG, d2i_OSSL_CRMF_MSGS,
34       d2i_OSSL_CRMF_PBMPARAMETER, d2i_OSSL_CRMF_PKIPUBLICATIONINFO,
35       d2i_OSSL_CRMF_SINGLEPUBINFO, d2i_OTHERNAME, d2i_PBE2PARAM,
36       d2i_PBEPARAM, d2i_PBKDF2PARAM, d2i_PKCS12, d2i_PKCS12_BAGS,
37       d2i_PKCS12_MAC_DATA, d2i_PKCS12_SAFEBAG, d2i_PKCS12_bio, d2i_PKCS12_fp,
38       d2i_PKCS7, d2i_PKCS7_DIGEST, d2i_PKCS7_ENCRYPT, d2i_PKCS7_ENC_CONTENT,
39       d2i_PKCS7_ENVELOPE, d2i_PKCS7_ISSUER_AND_SERIAL, d2i_PKCS7_RECIP_INFO,
40       d2i_PKCS7_SIGNED, d2i_PKCS7_SIGNER_INFO, d2i_PKCS7_SIGN_ENVELOPE,
41       d2i_PKCS7_bio, d2i_PKCS7_fp, d2i_PKCS8_PRIV_KEY_INFO,
42       d2i_PKCS8_PRIV_KEY_INFO_bio, d2i_PKCS8_PRIV_KEY_INFO_fp, d2i_PKCS8_bio,
43       d2i_PKCS8_fp, d2i_PKEY_USAGE_PERIOD, d2i_POLICYINFO,
44       d2i_POLICYQUALINFO, d2i_PROFESSION_INFO, d2i_PROXY_CERT_INFO_EXTENSION,
45       d2i_PROXY_POLICY, d2i_RSA_OAEP_PARAMS, d2i_RSA_PSS_PARAMS,
46       d2i_SCRYPT_PARAMS, d2i_SCT_LIST, d2i_SXNET, d2i_SXNETID,
47       d2i_TS_ACCURACY, d2i_TS_MSG_IMPRINT, d2i_TS_MSG_IMPRINT_bio,
48       d2i_TS_MSG_IMPRINT_fp, d2i_TS_REQ, d2i_TS_REQ_bio, d2i_TS_REQ_fp,
49       d2i_TS_RESP, d2i_TS_RESP_bio, d2i_TS_RESP_fp, d2i_TS_STATUS_INFO,
50       d2i_TS_TST_INFO, d2i_TS_TST_INFO_bio, d2i_TS_TST_INFO_fp,
51       d2i_USERNOTICE, d2i_X509, d2i_X509_bio, d2i_X509_fp, d2i_X509_ALGOR,
52       d2i_X509_ALGORS, d2i_X509_ATTRIBUTE, d2i_X509_CERT_AUX, d2i_X509_CINF,
53       d2i_X509_CRL, d2i_X509_CRL_INFO, d2i_X509_CRL_bio, d2i_X509_CRL_fp,
54       d2i_X509_EXTENSION, d2i_X509_EXTENSIONS, d2i_X509_NAME,
55       d2i_X509_NAME_ENTRY, d2i_X509_PUBKEY, d2i_X509_PUBKEY_bio,
56       d2i_X509_PUBKEY_fp, d2i_X509_REQ, d2i_X509_REQ_INFO, d2i_X509_REQ_bio,
57       d2i_X509_REQ_fp, d2i_X509_REVOKED, d2i_X509_SIG, d2i_X509_VAL,
58       i2d_ACCESS_DESCRIPTION, i2d_ADMISSIONS, i2d_ADMISSION_SYNTAX,
59       i2d_ASIdOrRange, i2d_ASIdentifierChoice, i2d_ASIdentifiers,
60       i2d_ASN1_BIT_STRING, i2d_ASN1_BMPSTRING, i2d_ASN1_ENUMERATED,
61       i2d_ASN1_GENERALIZEDTIME, i2d_ASN1_GENERALSTRING, i2d_ASN1_IA5STRING,
62       i2d_ASN1_INTEGER, i2d_ASN1_NULL, i2d_ASN1_OBJECT,
63       i2d_ASN1_OCTET_STRING, i2d_ASN1_PRINTABLE, i2d_ASN1_PRINTABLESTRING,
64       i2d_ASN1_SEQUENCE_ANY, i2d_ASN1_SET_ANY, i2d_ASN1_T61STRING,
65       i2d_ASN1_TIME, i2d_ASN1_TYPE, i2d_ASN1_UNIVERSALSTRING,
66       i2d_ASN1_UTCTIME, i2d_ASN1_UTF8STRING, i2d_ASN1_VISIBLESTRING,
67       i2d_ASN1_bio_stream, i2d_ASRange, i2d_AUTHORITY_INFO_ACCESS,
68       i2d_AUTHORITY_KEYID, i2d_BASIC_CONSTRAINTS, i2d_CERTIFICATEPOLICIES,
69       i2d_CMS_ContentInfo, i2d_CMS_ReceiptRequest, i2d_CMS_bio,
70       i2d_CRL_DIST_POINTS, i2d_DHxparams, i2d_DIRECTORYSTRING,
71       i2d_DISPLAYTEXT, i2d_DIST_POINT, i2d_DIST_POINT_NAME, i2d_DSA_SIG,
72       i2d_ECDSA_SIG, i2d_EDIPARTYNAME, i2d_ESS_CERT_ID, i2d_ESS_CERT_ID_V2,
73       i2d_ESS_ISSUER_SERIAL, i2d_ESS_SIGNING_CERT, i2d_ESS_SIGNING_CERT_V2,
74       i2d_EXTENDED_KEY_USAGE, i2d_GENERAL_NAME, i2d_GENERAL_NAMES,
75       i2d_IPAddressChoice, i2d_IPAddressFamily, i2d_IPAddressOrRange,
76       i2d_IPAddressRange, i2d_ISSUER_SIGN_TOOL, i2d_ISSUING_DIST_POINT,
77       i2d_NAMING_AUTHORITY, i2d_NETSCAPE_CERT_SEQUENCE, i2d_NETSCAPE_SPKAC,
78       i2d_NETSCAPE_SPKI, i2d_NOTICEREF, i2d_OCSP_BASICRESP, i2d_OCSP_CERTID,
79       i2d_OCSP_CERTSTATUS, i2d_OCSP_CRLID, i2d_OCSP_ONEREQ, i2d_OCSP_REQINFO,
80       i2d_OCSP_REQUEST, i2d_OCSP_RESPBYTES, i2d_OCSP_RESPDATA,
81       i2d_OCSP_RESPID, i2d_OCSP_RESPONSE, i2d_OCSP_REVOKEDINFO,
82       i2d_OCSP_SERVICELOC, i2d_OCSP_SIGNATURE, i2d_OCSP_SINGLERESP,
83       i2d_OSSL_CMP_MSG, i2d_OSSL_CMP_PKIHEADER, i2d_OSSL_CMP_PKISI,
84       i2d_OSSL_CRMF_CERTID, i2d_OSSL_CRMF_CERTTEMPLATE,
85       i2d_OSSL_CRMF_ENCRYPTEDVALUE, i2d_OSSL_CRMF_MSG, i2d_OSSL_CRMF_MSGS,
86       i2d_OSSL_CRMF_PBMPARAMETER, i2d_OSSL_CRMF_PKIPUBLICATIONINFO,
87       i2d_OSSL_CRMF_SINGLEPUBINFO, i2d_OTHERNAME, i2d_PBE2PARAM,
88       i2d_PBEPARAM, i2d_PBKDF2PARAM, i2d_PKCS12, i2d_PKCS12_BAGS,
89       i2d_PKCS12_MAC_DATA, i2d_PKCS12_SAFEBAG, i2d_PKCS12_bio, i2d_PKCS12_fp,
90       i2d_PKCS7, i2d_PKCS7_DIGEST, i2d_PKCS7_ENCRYPT, i2d_PKCS7_ENC_CONTENT,
91       i2d_PKCS7_ENVELOPE, i2d_PKCS7_ISSUER_AND_SERIAL, i2d_PKCS7_NDEF,
92       i2d_PKCS7_RECIP_INFO, i2d_PKCS7_SIGNED, i2d_PKCS7_SIGNER_INFO,
93       i2d_PKCS7_SIGN_ENVELOPE, i2d_PKCS7_bio, i2d_PKCS7_fp,
94       i2d_PKCS8PrivateKeyInfo_bio, i2d_PKCS8PrivateKeyInfo_fp,
95       i2d_PKCS8_PRIV_KEY_INFO, i2d_PKCS8_PRIV_KEY_INFO_bio,
96       i2d_PKCS8_PRIV_KEY_INFO_fp, i2d_PKCS8_bio, i2d_PKCS8_fp,
97       i2d_PKEY_USAGE_PERIOD, i2d_POLICYINFO, i2d_POLICYQUALINFO,
98       i2d_PROFESSION_INFO, i2d_PROXY_CERT_INFO_EXTENSION, i2d_PROXY_POLICY,
99       i2d_RSA_OAEP_PARAMS, i2d_RSA_PSS_PARAMS, i2d_SCRYPT_PARAMS,
100       i2d_SCT_LIST, i2d_SXNET, i2d_SXNETID, i2d_TS_ACCURACY,
101       i2d_TS_MSG_IMPRINT, i2d_TS_MSG_IMPRINT_bio, i2d_TS_MSG_IMPRINT_fp,
102       i2d_TS_REQ, i2d_TS_REQ_bio, i2d_TS_REQ_fp, i2d_TS_RESP,
103       i2d_TS_RESP_bio, i2d_TS_RESP_fp, i2d_TS_STATUS_INFO, i2d_TS_TST_INFO,
104       i2d_TS_TST_INFO_bio, i2d_TS_TST_INFO_fp, i2d_USERNOTICE, i2d_X509,
105       i2d_X509_bio, i2d_X509_fp, i2d_X509_ALGOR, i2d_X509_ALGORS,
106       i2d_X509_ATTRIBUTE, i2d_X509_CERT_AUX, i2d_X509_CINF, i2d_X509_CRL,
107       i2d_X509_CRL_INFO, i2d_X509_CRL_bio, i2d_X509_CRL_fp,
108       i2d_X509_EXTENSION, i2d_X509_EXTENSIONS, i2d_X509_NAME,
109       i2d_X509_NAME_ENTRY, i2d_X509_PUBKEY, i2d_X509_PUBKEY_bio,
110       i2d_X509_PUBKEY_fp, i2d_X509_REQ, i2d_X509_REQ_INFO, i2d_X509_REQ_bio,
111       i2d_X509_REQ_fp, i2d_X509_REVOKED, i2d_X509_SIG, i2d_X509_VAL, -
112       convert objects from/to ASN.1/DER representation
113

SYNOPSIS

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

DESCRIPTION

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

NOTES

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

RETURN VALUES

226       d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid TYPE
227       structure or NULL if an error occurs.  If the "reuse" capability has
228       been used with a valid structure being passed in via a, then the object
229       is freed in the event of error and *a is set to NULL.
230
231       i2d_TYPE() returns the number of bytes successfully encoded or a
232       negative value if an error occurs.
233
234       i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
235       occurs.
236

EXAMPLES

238       Allocate and encode the DER encoding of an X509 structure:
239
240        int len;
241        unsigned char *buf;
242
243        buf = NULL;
244        len = i2d_X509(x, &buf);
245        if (len < 0)
246            /* error */
247
248       Attempt to decode a buffer:
249
250        X509 *x;
251        unsigned char *buf;
252        const unsigned char *p;
253        int len;
254
255        /* Set up buf and len to point to the input buffer. */
256        p = buf;
257        x = d2i_X509(NULL, &p, len);
258        if (x == NULL)
259            /* error */
260
261       Alternative technique:
262
263        X509 *x;
264        unsigned char *buf;
265        const unsigned char *p;
266        int len;
267
268        /* Set up buf and len to point to the input buffer. */
269        p = buf;
270        x = NULL;
271
272        if (d2i_X509(&x, &p, len) == NULL)
273            /* error */
274

WARNINGS

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

BUGS

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