1D2I_X509(3ossl) OpenSSL D2I_X509(3ossl)
2
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
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 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
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 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 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 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 d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts to parse
149 data from BIO bp.
150 d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts to parse data
152 from FILE pointer fp.
153 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 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 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 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 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
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 The functions can also understand BER forms.
181 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 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 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 The following points about the data types might be useful:
198 ASN1_OBJECT
200 Represents an ASN1 OBJECT IDENTIFIER.
201 DHparams
203 Represents a PKCS#3 DH parameters structure.
204 DHxparams
206 Represents an ANSI X9.42 DH parameters structure.
207 ECDSA_SIG
209 Represents an ECDSA signature.
210 X509_ALGOR
212 Represents an AlgorithmIdentifier structure as used in IETF RFC
213 6960 and elsewhere.
214 X509_NAME
216 Represents a Name type as used for subject and issuer names in IETF
217 RFC 6960 and elsewhere.
218 X509_REQ
220 Represents a PKCS#10 certificate request.
221 X509_SIG
223 Represents the DigestInfo structure defined in PKCS#1 and PKCS#7.
224
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 i2d_TYPE() returns the number of bytes successfully encoded or a
232 negative value if an error occurs.
233 i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
235 occurs.
236
238 Allocate and encode the DER encoding of an X509 structure:
239 int len;
241 unsigned char *buf;
242 buf = NULL;
244 len = i2d_X509(x, &buf);
245 if (len < 0)
246 /* error */
247 Attempt to decode a buffer:
249 X509 *x;
251 unsigned char *buf;
252 const unsigned char *p;
253 int len;
254 /* 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 Alternative technique:
262 X509 *x;
264 unsigned char *buf;
265 const unsigned char *p;
266 int len;
267 /* Set up buf and len to point to the input buffer. */
269 p = buf;
270 x = NULL;
271 if (d2i_X509(&x, &p, len) == NULL)
273 /* error */
274
276 Using a temporary variable is mandatory. A common mistake is to attempt
277 to use a buffer directly as follows:
278 int len;
280 unsigned char *buf;
281 len = i2d_X509(x, NULL);
283 buf = OPENSSL_malloc(len);
284 ...
285 i2d_X509(x, &buf);
286 ...
287 OPENSSL_free(buf);
288 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 Another trap to avoid is misuse of the a argument to d2i_TYPE():
296 X509 *x;
298 if (d2i_X509(&x, &p, len) == NULL)
300 /* error */
301 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
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 As a result of the above issues the "reuse" behaviour is strongly
318 discouraged.
319 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 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 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>.
3383.1.1 2023-08-31 D2I_X509(3ossl)