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_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
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 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
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 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 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 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 d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts to parse
150 data from BIO bp.
151 d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts to parse data
153 from FILE pointer fp.
154 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 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 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 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 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
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 The functions can also understand BER forms.
182 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 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 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 The following points about the data types might be useful:
199 ASN1_OBJECT
201 Represents an ASN1 OBJECT IDENTIFIER.
202 DHparams
204 Represents a PKCS#3 DH parameters structure.
205 DHxparams
207 Represents an ANSI X9.42 DH parameters structure.
208 DSA_PUBKEY
210 Represents a DSA public key using a SubjectPublicKeyInfo structure.
211 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 ECDSA_SIG
217 Represents an ECDSA signature.
218 RSAPublicKey
220 Represents a PKCS#1 RSA public key structure.
221 X509_ALGOR
223 Represents an AlgorithmIdentifier structure as used in IETF RFC
224 6960 and elsewhere.
225 X509_Name
227 Represents a Name type as used for subject and issuer names in IETF
228 RFC 6960 and elsewhere.
229 X509_REQ
231 Represents a PKCS#10 certificate request.
232 X509_SIG
234 Represents the DigestInfo structure defined in PKCS#1 and PKCS#7.
235
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 i2d_TYPE() returns the number of bytes successfully encoded or a
243 negative value if an error occurs.
244 i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
246 occurs.
247
249 Allocate and encode the DER encoding of an X509 structure:
250 int len;
252 unsigned char *buf;
253 buf = NULL;
255 len = i2d_X509(x, &buf);
256 if (len < 0)
257 /* error */
258 Attempt to decode a buffer:
260 X509 *x;
262 unsigned char *buf;
263 const unsigned char *p;
264 int len;
265 /* 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 Alternative technique:
273 X509 *x;
275 unsigned char *buf;
276 const unsigned char *p;
277 int len;
278 /* Set up buf and len to point to the input buffer. */
280 p = buf;
281 x = NULL;
282 if (d2i_X509(&x, &p, len) == NULL)
284 /* error */
285
287 Using a temporary variable is mandatory. A common mistake is to attempt
288 to use a buffer directly as follows:
289 int len;
291 unsigned char *buf;
292 len = i2d_X509(x, NULL);
294 buf = OPENSSL_malloc(len);
295 ...
296 i2d_X509(x, &buf);
297 ...
298 OPENSSL_free(buf);
299 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 Another trap to avoid is misuse of the a argument to d2i_TYPE():
307 X509 *x;
309 if (d2i_X509(&x, &p, len) == NULL)
311 /* error */
312 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
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 As a result of the above issues the "reuse" behaviour is strongly
329 discouraged.
330 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 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 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>.
3491.1.1i 2021-01-26 D2I_X509(3)