1D2I_X509(3) OpenSSL D2I_X509(3)
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,
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_bio, d2i_X509_fp, d2i_X509_ALGOR, d2i_X509_ALGORS,
56 d2i_X509_ATTRIBUTE, d2i_X509_CERT_AUX, d2i_X509_CINF, d2i_X509_CRL,
57 d2i_X509_CRL_INFO, d2i_X509_CRL_bio, d2i_X509_CRL_fp,
58 d2i_X509_EXTENSION, d2i_X509_EXTENSIONS, d2i_X509_NAME,
59 d2i_X509_NAME_ENTRY, d2i_X509_PUBKEY, d2i_X509_REQ, d2i_X509_REQ_INFO,
60 d2i_X509_REQ_bio, d2i_X509_REQ_fp, d2i_X509_REVOKED, d2i_X509_SIG,
61 d2i_X509_VAL, i2d_ACCESS_DESCRIPTION, i2d_ADMISSIONS,
62 i2d_ADMISSION_SYNTAX, i2d_ASIdOrRange, i2d_ASIdentifierChoice,
63 i2d_ASIdentifiers, i2d_ASN1_BIT_STRING, i2d_ASN1_BMPSTRING,
64 i2d_ASN1_ENUMERATED, i2d_ASN1_GENERALIZEDTIME, i2d_ASN1_GENERALSTRING,
65 i2d_ASN1_IA5STRING, i2d_ASN1_INTEGER, i2d_ASN1_NULL, i2d_ASN1_OBJECT,
66 i2d_ASN1_OCTET_STRING, i2d_ASN1_PRINTABLE, i2d_ASN1_PRINTABLESTRING,
67 i2d_ASN1_SEQUENCE_ANY, i2d_ASN1_SET_ANY, i2d_ASN1_T61STRING,
68 i2d_ASN1_TIME, i2d_ASN1_TYPE, i2d_ASN1_UNIVERSALSTRING,
69 i2d_ASN1_UTCTIME, i2d_ASN1_UTF8STRING, i2d_ASN1_VISIBLESTRING,
70 i2d_ASN1_bio_stream, i2d_ASRange, i2d_AUTHORITY_INFO_ACCESS,
71 i2d_AUTHORITY_KEYID, i2d_BASIC_CONSTRAINTS, i2d_CERTIFICATEPOLICIES,
72 i2d_CMS_ContentInfo, i2d_CMS_ReceiptRequest, i2d_CMS_bio,
73 i2d_CRL_DIST_POINTS, i2d_DHxparams, i2d_DIRECTORYSTRING,
74 i2d_DISPLAYTEXT, i2d_DIST_POINT, i2d_DIST_POINT_NAME,
75 i2d_DSAPrivateKey, i2d_DSAPrivateKey_bio, i2d_DSAPrivateKey_fp,
76 i2d_DSAPublicKey, i2d_DSA_PUBKEY, i2d_DSA_PUBKEY_bio,
77 i2d_DSA_PUBKEY_fp, i2d_DSA_SIG, i2d_DSAparams, i2d_ECDSA_SIG,
78 i2d_ECPKParameters, i2d_ECParameters, i2d_ECPrivateKey,
79 i2d_ECPrivateKey_bio, i2d_ECPrivateKey_fp, i2d_EC_PUBKEY,
80 i2d_EC_PUBKEY_bio, i2d_EC_PUBKEY_fp, i2d_EDIPARTYNAME, i2d_ESS_CERT_ID,
81 i2d_ESS_ISSUER_SERIAL, i2d_ESS_SIGNING_CERT, i2d_EXTENDED_KEY_USAGE,
82 i2d_GENERAL_NAME, i2d_GENERAL_NAMES, i2d_IPAddressChoice,
83 i2d_IPAddressFamily, i2d_IPAddressOrRange, i2d_IPAddressRange,
84 i2d_ISSUING_DIST_POINT, i2d_NAMING_AUTHORITY,
85 i2d_NETSCAPE_CERT_SEQUENCE, i2d_NETSCAPE_SPKAC, i2d_NETSCAPE_SPKI,
86 i2d_NOTICEREF, i2d_OCSP_BASICRESP, i2d_OCSP_CERTID,
87 i2d_OCSP_CERTSTATUS, i2d_OCSP_CRLID, i2d_OCSP_ONEREQ, i2d_OCSP_REQINFO,
88 i2d_OCSP_REQUEST, i2d_OCSP_RESPBYTES, i2d_OCSP_RESPDATA,
89 i2d_OCSP_RESPID, i2d_OCSP_RESPONSE, i2d_OCSP_REVOKEDINFO,
90 i2d_OCSP_SERVICELOC, i2d_OCSP_SIGNATURE, i2d_OCSP_SINGLERESP,
91 i2d_OTHERNAME, i2d_PBE2PARAM, i2d_PBEPARAM, i2d_PBKDF2PARAM,
92 i2d_PKCS12, i2d_PKCS12_BAGS, i2d_PKCS12_MAC_DATA, i2d_PKCS12_SAFEBAG,
93 i2d_PKCS12_bio, i2d_PKCS12_fp, i2d_PKCS7, i2d_PKCS7_DIGEST,
94 i2d_PKCS7_ENCRYPT, i2d_PKCS7_ENC_CONTENT, i2d_PKCS7_ENVELOPE,
95 i2d_PKCS7_ISSUER_AND_SERIAL, i2d_PKCS7_NDEF, i2d_PKCS7_RECIP_INFO,
96 i2d_PKCS7_SIGNED, i2d_PKCS7_SIGNER_INFO, i2d_PKCS7_SIGN_ENVELOPE,
97 i2d_PKCS7_bio, i2d_PKCS7_fp, i2d_PKCS8PrivateKeyInfo_bio,
98 i2d_PKCS8PrivateKeyInfo_fp, i2d_PKCS8_PRIV_KEY_INFO,
99 i2d_PKCS8_PRIV_KEY_INFO_bio, i2d_PKCS8_PRIV_KEY_INFO_fp, i2d_PKCS8_bio,
100 i2d_PKCS8_fp, i2d_PKEY_USAGE_PERIOD, i2d_POLICYINFO,
101 i2d_POLICYQUALINFO, i2d_PROFESSION_INFO, i2d_PROXY_CERT_INFO_EXTENSION,
102 i2d_PROXY_POLICY, i2d_RSAPrivateKey, i2d_RSAPrivateKey_bio,
103 i2d_RSAPrivateKey_fp, i2d_RSAPublicKey, i2d_RSAPublicKey_bio,
104 i2d_RSAPublicKey_fp, i2d_RSA_OAEP_PARAMS, i2d_RSA_PSS_PARAMS,
105 i2d_RSA_PUBKEY, i2d_RSA_PUBKEY_bio, i2d_RSA_PUBKEY_fp,
106 i2d_SCRYPT_PARAMS, i2d_SCT_LIST, i2d_SXNET, i2d_SXNETID,
107 i2d_TS_ACCURACY, i2d_TS_MSG_IMPRINT, i2d_TS_MSG_IMPRINT_bio,
108 i2d_TS_MSG_IMPRINT_fp, i2d_TS_REQ, i2d_TS_REQ_bio, i2d_TS_REQ_fp,
109 i2d_TS_RESP, i2d_TS_RESP_bio, i2d_TS_RESP_fp, i2d_TS_STATUS_INFO,
110 i2d_TS_TST_INFO, i2d_TS_TST_INFO_bio, i2d_TS_TST_INFO_fp,
111 i2d_USERNOTICE, i2d_X509, i2d_X509_bio, i2d_X509_fp, i2d_X509_ALGOR,
112 i2d_X509_ALGORS, i2d_X509_ATTRIBUTE, i2d_X509_CERT_AUX, i2d_X509_CINF,
113 i2d_X509_CRL, i2d_X509_CRL_INFO, i2d_X509_CRL_bio, i2d_X509_CRL_fp,
114 i2d_X509_EXTENSION, i2d_X509_EXTENSIONS, i2d_X509_NAME,
115 i2d_X509_NAME_ENTRY, i2d_X509_PUBKEY, i2d_X509_REQ, i2d_X509_REQ_INFO,
116 i2d_X509_REQ_bio, i2d_X509_REQ_fp, i2d_X509_REVOKED, i2d_X509_SIG,
117 i2d_X509_VAL, - convert objects from/to ASN.1/DER representation
118
120 TYPE *d2i_TYPE(TYPE **a, const unsigned char **ppin, long length);
121 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
122 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
123 int i2d_TYPE(TYPE *a, unsigned char **ppout);
125 int i2d_TYPE_fp(FILE *fp, TYPE *a);
126 int i2d_TYPE_bio(BIO *bp, TYPE *a);
127
129 In the description here, TYPE is used a placeholder for any of the
130 OpenSSL datatypes, such as X509_CRL. The function parameters ppin and
131 ppout are generally either both named pp in the headers, or in and out.
132 These functions convert OpenSSL objects to and from their ASN.1/DER
134 encoding. Unlike the C structures which can have pointers to sub-
135 objects within, the DER is a serialized encoding, suitable for sending
136 over the network, writing to a file, and so on.
137 d2i_TYPE() attempts to decode len bytes at *ppin. If successful a
139 pointer to the TYPE structure is returned and *ppin is incremented to
140 the byte following the parsed data. If a is not NULL then a pointer to
141 the returned structure is also written to *a. If an error occurred
142 then NULL is returned.
143 On a successful return, if *a is not NULL then it is assumed that *a
145 contains a valid TYPE structure and an attempt is made to reuse it.
146 This "reuse" capability is present for historical compatibility but its
147 use is strongly discouraged (see BUGS below, and the discussion in the
148 RETURN VALUES section).
149 d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts to parse
151 data from BIO bp.
152 d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts to parse data
154 from FILE pointer fp.
155 i2d_TYPE() encodes the structure pointed to by a into DER format. If
157 ppout is not NULL, it writes the DER encoded data to the buffer at
158 *ppout, and increments it to point after the data just written. If the
159 return value is negative an error occurred, otherwise it returns the
160 length of the encoded data.
161 If *ppout is NULL memory will be allocated for a buffer and the encoded
163 data written to it. In this case *ppout is not incremented and it
164 points to the start of the data just written.
165 i2d_TYPE_bio() is similar to i2d_TYPE() except it writes the encoding
167 of the structure a to BIO bp and it returns 1 for success and 0 for
168 failure.
169 i2d_TYPE_fp() is similar to i2d_TYPE() except it writes the encoding of
171 the structure a to BIO bp and it returns 1 for success and 0 for
172 failure.
173 These routines do not encrypt private keys and therefore offer no
175 security; use PEM_write_PrivateKey(3) or similar for writing to files.
176
178 The letters i and d in i2d_TYPE stand for "internal" (that is, an
179 internal C structure) and "DER" respectively. So i2d_TYPE converts
180 from internal to DER.
181 The functions can also understand BER forms.
183 The actual TYPE structure passed to i2d_TYPE() must be a valid
185 populated TYPE structure -- it cannot simply be fed with an empty
186 structure such as that returned by TYPE_new().
187 The encoded data is in binary form and may contain embedded zeros.
189 Therefore, any FILE pointers or BIOs should be opened in binary mode.
190 Functions such as strlen() will not return the correct length of the
191 encoded structure.
192 The ways that *ppin and *ppout are incremented after the operation can
194 trap the unwary. See the WARNINGS section for some common errors. The
195 reason for this-auto increment behaviour is to reflect a typical usage
196 of ASN1 functions: after one structure is encoded or decoded another
197 will be processed after it.
198 The following points about the data types might be useful:
200 ASN1_OBJECT
202 Represents an ASN1 OBJECT IDENTIFIER.
203 DHparams
205 Represents a PKCS#3 DH parameters structure.
206 DHxparams
208 Represents an ANSI X9.42 DH parameters structure.
209 DSA_PUBKEY
211 Represents a DSA public key using a SubjectPublicKeyInfo structure.
212 DSAPublicKey, DSAPrivateKey
214 Use a non-standard OpenSSL format and should be avoided; use
215 DSA_PUBKEY, PEM_write_PrivateKey(3), or similar instead.
216 ECDSA_SIG
218 Represents an ECDSA signature.
219 RSAPublicKey
221 Represents a PKCS#1 RSA public key structure.
222 X509_ALGOR
224 Represents an AlgorithmIdentifier structure as used in IETF RFC
225 6960 and elsewhere.
226 X509_Name
228 Represents a Name type as used for subject and issuer names in IETF
229 RFC 6960 and elsewhere.
230 X509_REQ
232 Represents a PKCS#10 certificate request.
233 X509_SIG
235 Represents the DigestInfo structure defined in PKCS#1 and PKCS#7.
236
238 d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid TYPE
239 structure or NULL if an error occurs. If the "reuse" capability has
240 been used with a valid structure being passed in via a, then the object
241 is freed in the event of error and *a is set to NULL.
242 i2d_TYPE() returns the number of bytes successfully encoded or a
244 negative value if an error occurs.
245 i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
247 occurs.
248
250 Allocate and encode the DER encoding of an X509 structure:
251 int len;
253 unsigned char *buf;
254 buf = NULL;
256 len = i2d_X509(x, &buf);
257 if (len < 0)
258 /* error */
259 Attempt to decode a buffer:
261 X509 *x;
263 unsigned char *buf;
264 const unsigned char *p;
265 int len;
266 /* Set up buf and len to point to the input buffer. */
268 p = buf;
269 x = d2i_X509(NULL, &p, len);
270 if (x == NULL)
271 /* error */
272 Alternative technique:
274 X509 *x;
276 unsigned char *buf;
277 const unsigned char *p;
278 int len;
279 /* Set up buf and len to point to the input buffer. */
281 p = buf;
282 x = NULL;
283 if (d2i_X509(&x, &p, len) == NULL)
285 /* error */
286
288 Using a temporary variable is mandatory. A common mistake is to attempt
289 to use a buffer directly as follows:
290 int len;
292 unsigned char *buf;
293 len = i2d_X509(x, NULL);
295 buf = OPENSSL_malloc(len);
296 ...
297 i2d_X509(x, &buf);
298 ...
299 OPENSSL_free(buf);
300 This code will result in buf apparently containing garbage because it
302 was incremented after the call to point after the data just written.
303 Also buf will no longer contain the pointer allocated by
304 OPENSSL_malloc() and the subsequent call to OPENSSL_free() is likely to
305 crash.
306 Another trap to avoid is misuse of the a argument to d2i_TYPE():
308 X509 *x;
310 if (d2i_X509(&x, &p, len) == NULL)
312 /* error */
313 This will probably crash somewhere in d2i_X509(). The reason for this
315 is that the variable x is uninitialized and an attempt will be made to
316 interpret its (invalid) value as an X509 structure, typically causing a
317 segmentation violation. If x is set to NULL first then this will not
318 happen.
319
321 In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when *a
322 is valid is broken and some parts of the reused structure may persist
323 if they are not present in the new one. Additionally, in versions of
324 OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error
325 occurs the behaviour is inconsistent. Some functions behaved as
326 described here, while some did not free *a on error and did not set *a
327 to NULL.
328 As a result of the above issues the "reuse" behaviour is strongly
330 discouraged.
331 i2d_TYPE() will not return an error in many versions of OpenSSL, if
333 mandatory fields are not initialized due to a programming error then
334 the encoded structure may contain invalid data or omit the fields
335 entirely and will not be parsed by d2i_TYPE(). This may be fixed in
336 future so code should not assume that i2d_TYPE() will always succeed.
337 Any function which encodes a structure (i2d_TYPE(), i2d_TYPE() or
339 i2d_TYPE()) may return a stale encoding if the structure has been
340 modified after deserialization or previous serialization. This is
341 because some objects cache the encoding for efficiency reasons.
342
344 Copyright 1998-2021 The OpenSSL Project Authors. All Rights Reserved.
345 Licensed under the OpenSSL license (the "License"). You may not use
347 this file except in compliance with the License. You can obtain a copy
348 in the file LICENSE in the source distribution or at
349 <https://www.openssl.org/source/license.html>.
3501.1.1q 2023-02-06 D2I_X509(3)