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_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

SYNOPSIS

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
124        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

DESCRIPTION

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
133       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
138       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
144       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
150       d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts to parse
151       data from BIO bp.
152
153       d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts to parse data
154       from FILE pointer fp.
155
156       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
162       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
166       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
170       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
174       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

NOTES

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
182       The functions can also understand BER forms.
183
184       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
188       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
193       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
199       The following points about the data types might be useful:
200
201       ASN1_OBJECT
202           Represents an ASN1 OBJECT IDENTIFIER.
203
204       DHparams
205           Represents a PKCS#3 DH parameters structure.
206
207       DHxparams
208           Represents an ANSI X9.42 DH parameters structure.
209
210       DSA_PUBKEY
211           Represents a DSA public key using a SubjectPublicKeyInfo structure.
212
213       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
217       ECDSA_SIG
218           Represents an ECDSA signature.
219
220       RSAPublicKey
221           Represents a PKCS#1 RSA public key structure.
222
223       X509_ALGOR
224           Represents an AlgorithmIdentifier structure as used in IETF RFC
225           6960 and elsewhere.
226
227       X509_Name
228           Represents a Name type as used for subject and issuer names in IETF
229           RFC 6960 and elsewhere.
230
231       X509_REQ
232           Represents a PKCS#10 certificate request.
233
234       X509_SIG
235           Represents the DigestInfo structure defined in PKCS#1 and PKCS#7.
236

RETURN VALUES

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
243       i2d_TYPE() returns the number of bytes successfully encoded or a
244       negative value if an error occurs.
245
246       i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
247       occurs.
248

EXAMPLES

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

WARNINGS

288       Using a temporary variable is mandatory. A common mistake is to attempt
289       to use a buffer directly as follows:
290
291        int len;
292        unsigned char *buf;
293
294        len = i2d_X509(x, NULL);
295        buf = OPENSSL_malloc(len);
296        ...
297        i2d_X509(x, &buf);
298        ...
299        OPENSSL_free(buf);
300
301       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
307       Another trap to avoid is misuse of the a argument to d2i_TYPE():
308
309        X509 *x;
310
311        if (d2i_X509(&x, &p, len) == NULL)
312            /* error */
313
314       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

BUGS

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
329       As a result of the above issues the "reuse" behaviour is strongly
330       discouraged.
331
332       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
338       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
346       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>.
350
351
352
3531.1.1q                            2022-07-07                       D2I_X509(3)
Impressum