3075b0d0efb9954dceab7641bc125236a63d9891
[openssl.git] / doc / man3 / d2i_X509.pod
1 =pod
2
3 =head1 NAME
4
5 d2i_ACCESS_DESCRIPTION,
6 d2i_ADMISSIONS,
7 d2i_ADMISSION_SYNTAX,
8 d2i_ASIdOrRange,
9 d2i_ASIdentifierChoice,
10 d2i_ASIdentifiers,
11 d2i_ASN1_BIT_STRING,
12 d2i_ASN1_BMPSTRING,
13 d2i_ASN1_ENUMERATED,
14 d2i_ASN1_GENERALIZEDTIME,
15 d2i_ASN1_GENERALSTRING,
16 d2i_ASN1_IA5STRING,
17 d2i_ASN1_INTEGER,
18 d2i_ASN1_NULL,
19 d2i_ASN1_OBJECT,
20 d2i_ASN1_OCTET_STRING,
21 d2i_ASN1_PRINTABLE,
22 d2i_ASN1_PRINTABLESTRING,
23 d2i_ASN1_SEQUENCE_ANY,
24 d2i_ASN1_SET_ANY,
25 d2i_ASN1_T61STRING,
26 d2i_ASN1_TIME,
27 d2i_ASN1_TYPE,
28 d2i_ASN1_UINTEGER,
29 d2i_ASN1_UNIVERSALSTRING,
30 d2i_ASN1_UTCTIME,
31 d2i_ASN1_UTF8STRING,
32 d2i_ASN1_VISIBLESTRING,
33 d2i_ASRange,
34 d2i_AUTHORITY_INFO_ACCESS,
35 d2i_AUTHORITY_KEYID,
36 d2i_BASIC_CONSTRAINTS,
37 d2i_CERTIFICATEPOLICIES,
38 d2i_CMS_ContentInfo,
39 d2i_CMS_ReceiptRequest,
40 d2i_CMS_bio,
41 d2i_CRL_DIST_POINTS,
42 d2i_DHxparams,
43 d2i_DIRECTORYSTRING,
44 d2i_DISPLAYTEXT,
45 d2i_DIST_POINT,
46 d2i_DIST_POINT_NAME,
47 d2i_DSAPrivateKey,
48 d2i_DSAPrivateKey_bio,
49 d2i_DSAPrivateKey_fp,
50 d2i_DSAPublicKey,
51 d2i_DSA_PUBKEY,
52 d2i_DSA_PUBKEY_bio,
53 d2i_DSA_PUBKEY_fp,
54 d2i_DSA_SIG,
55 d2i_DSAparams,
56 d2i_ECPKParameters,
57 d2i_ECParameters,
58 d2i_ECPrivateKey,
59 d2i_ECPrivateKey_bio,
60 d2i_ECPrivateKey_fp,
61 d2i_EC_PUBKEY,
62 d2i_EC_PUBKEY_bio,
63 d2i_EC_PUBKEY_fp,
64 d2i_EDIPARTYNAME,
65 d2i_ESS_CERT_ID,
66 d2i_ESS_CERT_ID_V2,
67 d2i_ESS_ISSUER_SERIAL,
68 d2i_ESS_SIGNING_CERT,
69 d2i_ESS_SIGNING_CERT_V2,
70 d2i_EXTENDED_KEY_USAGE,
71 d2i_GENERAL_NAME,
72 d2i_GENERAL_NAMES,
73 d2i_IPAddressChoice,
74 d2i_IPAddressFamily,
75 d2i_IPAddressOrRange,
76 d2i_IPAddressRange,
77 d2i_ISSUING_DIST_POINT,
78 d2i_NAMING_AUTHORITY,
79 d2i_NETSCAPE_CERT_SEQUENCE,
80 d2i_NETSCAPE_SPKAC,
81 d2i_NETSCAPE_SPKI,
82 d2i_NOTICEREF,
83 d2i_OCSP_BASICRESP,
84 d2i_OCSP_CERTID,
85 d2i_OCSP_CERTSTATUS,
86 d2i_OCSP_CRLID,
87 d2i_OCSP_ONEREQ,
88 d2i_OCSP_REQINFO,
89 d2i_OCSP_REQUEST,
90 d2i_OCSP_RESPBYTES,
91 d2i_OCSP_RESPDATA,
92 d2i_OCSP_RESPID,
93 d2i_OCSP_RESPONSE,
94 d2i_OCSP_REVOKEDINFO,
95 d2i_OCSP_SERVICELOC,
96 d2i_OCSP_SIGNATURE,
97 d2i_OCSP_SINGLERESP,
98 d2i_OSSL_CMP_MSG,
99 d2i_OSSL_CMP_PKIHEADER,
100 d2i_OSSL_CRMF_CERTID,
101 d2i_OSSL_CRMF_CERTTEMPLATE,
102 d2i_OSSL_CRMF_ENCRYPTEDVALUE,
103 d2i_OSSL_CRMF_MSG,
104 d2i_OSSL_CRMF_MSGS,
105 d2i_OSSL_CRMF_PBMPARAMETER,
106 d2i_OSSL_CRMF_PKIPUBLICATIONINFO,
107 d2i_OSSL_CRMF_SINGLEPUBINFO,
108 d2i_OTHERNAME,
109 d2i_PBE2PARAM,
110 d2i_PBEPARAM,
111 d2i_PBKDF2PARAM,
112 d2i_PKCS12,
113 d2i_PKCS12_BAGS,
114 d2i_PKCS12_MAC_DATA,
115 d2i_PKCS12_SAFEBAG,
116 d2i_PKCS12_bio,
117 d2i_PKCS12_fp,
118 d2i_PKCS7,
119 d2i_PKCS7_DIGEST,
120 d2i_PKCS7_ENCRYPT,
121 d2i_PKCS7_ENC_CONTENT,
122 d2i_PKCS7_ENVELOPE,
123 d2i_PKCS7_ISSUER_AND_SERIAL,
124 d2i_PKCS7_RECIP_INFO,
125 d2i_PKCS7_SIGNED,
126 d2i_PKCS7_SIGNER_INFO,
127 d2i_PKCS7_SIGN_ENVELOPE,
128 d2i_PKCS7_bio,
129 d2i_PKCS7_fp,
130 d2i_PKCS8_PRIV_KEY_INFO,
131 d2i_PKCS8_PRIV_KEY_INFO_bio,
132 d2i_PKCS8_PRIV_KEY_INFO_fp,
133 d2i_PKCS8_bio,
134 d2i_PKCS8_fp,
135 d2i_PKEY_USAGE_PERIOD,
136 d2i_POLICYINFO,
137 d2i_POLICYQUALINFO,
138 d2i_PROFESSION_INFO,
139 d2i_PROXY_CERT_INFO_EXTENSION,
140 d2i_PROXY_POLICY,
141 d2i_RSAPrivateKey,
142 d2i_RSAPrivateKey_bio,
143 d2i_RSAPrivateKey_fp,
144 d2i_RSAPublicKey,
145 d2i_RSAPublicKey_bio,
146 d2i_RSAPublicKey_fp,
147 d2i_RSA_OAEP_PARAMS,
148 d2i_RSA_PSS_PARAMS,
149 d2i_RSA_PUBKEY,
150 d2i_RSA_PUBKEY_bio,
151 d2i_RSA_PUBKEY_fp,
152 d2i_SCRYPT_PARAMS,
153 d2i_SCT_LIST,
154 d2i_SXNET,
155 d2i_SXNETID,
156 d2i_TS_ACCURACY,
157 d2i_TS_MSG_IMPRINT,
158 d2i_TS_MSG_IMPRINT_bio,
159 d2i_TS_MSG_IMPRINT_fp,
160 d2i_TS_REQ,
161 d2i_TS_REQ_bio,
162 d2i_TS_REQ_fp,
163 d2i_TS_RESP,
164 d2i_TS_RESP_bio,
165 d2i_TS_RESP_fp,
166 d2i_TS_STATUS_INFO,
167 d2i_TS_TST_INFO,
168 d2i_TS_TST_INFO_bio,
169 d2i_TS_TST_INFO_fp,
170 d2i_USERNOTICE,
171 d2i_X509,
172 d2i_X509_ALGOR,
173 d2i_X509_ALGORS,
174 d2i_X509_ATTRIBUTE,
175 d2i_X509_CERT_AUX,
176 d2i_X509_CINF,
177 d2i_X509_CRL,
178 d2i_X509_CRL_INFO,
179 d2i_X509_CRL_bio,
180 d2i_X509_CRL_fp,
181 d2i_X509_EXTENSION,
182 d2i_X509_EXTENSIONS,
183 d2i_X509_NAME,
184 d2i_X509_NAME_ENTRY,
185 d2i_X509_PUBKEY,
186 d2i_X509_REQ,
187 d2i_X509_REQ_INFO,
188 d2i_X509_REQ_bio,
189 d2i_X509_REQ_fp,
190 d2i_X509_REVOKED,
191 d2i_X509_SIG,
192 d2i_X509_VAL,
193 i2d_ACCESS_DESCRIPTION,
194 i2d_ADMISSIONS,
195 i2d_ADMISSION_SYNTAX,
196 i2d_ASIdOrRange,
197 i2d_ASIdentifierChoice,
198 i2d_ASIdentifiers,
199 i2d_ASN1_BIT_STRING,
200 i2d_ASN1_BMPSTRING,
201 i2d_ASN1_ENUMERATED,
202 i2d_ASN1_GENERALIZEDTIME,
203 i2d_ASN1_GENERALSTRING,
204 i2d_ASN1_IA5STRING,
205 i2d_ASN1_INTEGER,
206 i2d_ASN1_NULL,
207 i2d_ASN1_OBJECT,
208 i2d_ASN1_OCTET_STRING,
209 i2d_ASN1_PRINTABLE,
210 i2d_ASN1_PRINTABLESTRING,
211 i2d_ASN1_SEQUENCE_ANY,
212 i2d_ASN1_SET_ANY,
213 i2d_ASN1_T61STRING,
214 i2d_ASN1_TIME,
215 i2d_ASN1_TYPE,
216 i2d_ASN1_UNIVERSALSTRING,
217 i2d_ASN1_UTCTIME,
218 i2d_ASN1_UTF8STRING,
219 i2d_ASN1_VISIBLESTRING,
220 i2d_ASN1_bio_stream,
221 i2d_ASRange,
222 i2d_AUTHORITY_INFO_ACCESS,
223 i2d_AUTHORITY_KEYID,
224 i2d_BASIC_CONSTRAINTS,
225 i2d_CERTIFICATEPOLICIES,
226 i2d_CMS_ContentInfo,
227 i2d_CMS_ReceiptRequest,
228 i2d_CMS_bio,
229 i2d_CRL_DIST_POINTS,
230 i2d_DHxparams,
231 i2d_DIRECTORYSTRING,
232 i2d_DISPLAYTEXT,
233 i2d_DIST_POINT,
234 i2d_DIST_POINT_NAME,
235 i2d_DSAPrivateKey,
236 i2d_DSAPrivateKey_bio,
237 i2d_DSAPrivateKey_fp,
238 i2d_DSAPublicKey,
239 i2d_DSA_PUBKEY,
240 i2d_DSA_PUBKEY_bio,
241 i2d_DSA_PUBKEY_fp,
242 i2d_DSA_SIG,
243 i2d_DSAparams,
244 i2d_ECPKParameters,
245 i2d_ECParameters,
246 i2d_ECPrivateKey,
247 i2d_ECPrivateKey_bio,
248 i2d_ECPrivateKey_fp,
249 i2d_EC_PUBKEY,
250 i2d_EC_PUBKEY_bio,
251 i2d_EC_PUBKEY_fp,
252 i2d_EDIPARTYNAME,
253 i2d_ESS_CERT_ID,
254 i2d_ESS_CERT_ID_V2,
255 i2d_ESS_ISSUER_SERIAL,
256 i2d_ESS_SIGNING_CERT,
257 i2d_ESS_SIGNING_CERT_V2,
258 i2d_EXTENDED_KEY_USAGE,
259 i2d_GENERAL_NAME,
260 i2d_GENERAL_NAMES,
261 i2d_IPAddressChoice,
262 i2d_IPAddressFamily,
263 i2d_IPAddressOrRange,
264 i2d_IPAddressRange,
265 i2d_ISSUING_DIST_POINT,
266 i2d_NAMING_AUTHORITY,
267 i2d_NETSCAPE_CERT_SEQUENCE,
268 i2d_NETSCAPE_SPKAC,
269 i2d_NETSCAPE_SPKI,
270 i2d_NOTICEREF,
271 i2d_OCSP_BASICRESP,
272 i2d_OCSP_CERTID,
273 i2d_OCSP_CERTSTATUS,
274 i2d_OCSP_CRLID,
275 i2d_OCSP_ONEREQ,
276 i2d_OCSP_REQINFO,
277 i2d_OCSP_REQUEST,
278 i2d_OCSP_RESPBYTES,
279 i2d_OCSP_RESPDATA,
280 i2d_OCSP_RESPID,
281 i2d_OCSP_RESPONSE,
282 i2d_OCSP_REVOKEDINFO,
283 i2d_OCSP_SERVICELOC,
284 i2d_OCSP_SIGNATURE,
285 i2d_OCSP_SINGLERESP,
286 i2d_OSSL_CMP_MSG,
287 i2d_OSSL_CMP_PKIHEADER,
288 i2d_OSSL_CRMF_CERTID,
289 i2d_OSSL_CRMF_CERTTEMPLATE,
290 i2d_OSSL_CRMF_ENCRYPTEDVALUE,
291 i2d_OSSL_CRMF_MSG,
292 i2d_OSSL_CRMF_MSGS,
293 i2d_OSSL_CRMF_PBMPARAMETER,
294 i2d_OSSL_CRMF_PKIPUBLICATIONINFO,
295 i2d_OSSL_CRMF_SINGLEPUBINFO,
296 i2d_OTHERNAME,
297 i2d_PBE2PARAM,
298 i2d_PBEPARAM,
299 i2d_PBKDF2PARAM,
300 i2d_PKCS12,
301 i2d_PKCS12_BAGS,
302 i2d_PKCS12_MAC_DATA,
303 i2d_PKCS12_SAFEBAG,
304 i2d_PKCS12_bio,
305 i2d_PKCS12_fp,
306 i2d_PKCS7,
307 i2d_PKCS7_DIGEST,
308 i2d_PKCS7_ENCRYPT,
309 i2d_PKCS7_ENC_CONTENT,
310 i2d_PKCS7_ENVELOPE,
311 i2d_PKCS7_ISSUER_AND_SERIAL,
312 i2d_PKCS7_NDEF,
313 i2d_PKCS7_RECIP_INFO,
314 i2d_PKCS7_SIGNED,
315 i2d_PKCS7_SIGNER_INFO,
316 i2d_PKCS7_SIGN_ENVELOPE,
317 i2d_PKCS7_bio,
318 i2d_PKCS7_fp,
319 i2d_PKCS8PrivateKeyInfo_bio,
320 i2d_PKCS8PrivateKeyInfo_fp,
321 i2d_PKCS8_PRIV_KEY_INFO,
322 i2d_PKCS8_PRIV_KEY_INFO_bio,
323 i2d_PKCS8_PRIV_KEY_INFO_fp,
324 i2d_PKCS8_bio,
325 i2d_PKCS8_fp,
326 i2d_PKEY_USAGE_PERIOD,
327 i2d_POLICYINFO,
328 i2d_POLICYQUALINFO,
329 i2d_PROFESSION_INFO,
330 i2d_PROXY_CERT_INFO_EXTENSION,
331 i2d_PROXY_POLICY,
332 i2d_RSAPrivateKey,
333 i2d_RSAPrivateKey_bio,
334 i2d_RSAPrivateKey_fp,
335 i2d_RSAPublicKey,
336 i2d_RSAPublicKey_bio,
337 i2d_RSAPublicKey_fp,
338 i2d_RSA_OAEP_PARAMS,
339 i2d_RSA_PSS_PARAMS,
340 i2d_RSA_PUBKEY,
341 i2d_RSA_PUBKEY_bio,
342 i2d_RSA_PUBKEY_fp,
343 i2d_SCRYPT_PARAMS,
344 i2d_SCT_LIST,
345 i2d_SXNET,
346 i2d_SXNETID,
347 i2d_TS_ACCURACY,
348 i2d_TS_MSG_IMPRINT,
349 i2d_TS_MSG_IMPRINT_bio,
350 i2d_TS_MSG_IMPRINT_fp,
351 i2d_TS_REQ,
352 i2d_TS_REQ_bio,
353 i2d_TS_REQ_fp,
354 i2d_TS_RESP,
355 i2d_TS_RESP_bio,
356 i2d_TS_RESP_fp,
357 i2d_TS_STATUS_INFO,
358 i2d_TS_TST_INFO,
359 i2d_TS_TST_INFO_bio,
360 i2d_TS_TST_INFO_fp,
361 i2d_USERNOTICE,
362 i2d_X509,
363 i2d_X509_ALGOR,
364 i2d_X509_ALGORS,
365 i2d_X509_ATTRIBUTE,
366 i2d_X509_CERT_AUX,
367 i2d_X509_CINF,
368 i2d_X509_CRL,
369 i2d_X509_CRL_INFO,
370 i2d_X509_CRL_bio,
371 i2d_X509_CRL_fp,
372 i2d_X509_EXTENSION,
373 i2d_X509_EXTENSIONS,
374 i2d_X509_NAME,
375 i2d_X509_NAME_ENTRY,
376 i2d_X509_PUBKEY,
377 i2d_X509_REQ,
378 i2d_X509_REQ_INFO,
379 i2d_X509_REQ_bio,
380 i2d_X509_REQ_fp,
381 i2d_X509_REVOKED,
382 i2d_X509_SIG,
383 i2d_X509_VAL,
384 - convert objects from/to ASN.1/DER representation
385
386 =head1 SYNOPSIS
387
388 =for comment generic
389
390  TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length);
391  TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
392  TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
393
394  int i2d_TYPE(const TYPE *a, unsigned char **ppout);
395  int i2d_TYPE(TYPE *a, unsigned char **ppout);
396  int i2d_TYPE_fp(FILE *fp, const TYPE *a);
397  int i2d_TYPE_fp(FILE *fp, TYPE *a);
398  int i2d_TYPE_bio(BIO *bp, const TYPE *a);
399  int i2d_TYPE_bio(BIO *bp, TYPE *a);
400
401 =head1 DESCRIPTION
402
403 In the description here, I<TYPE> is used a placeholder
404 for any of the OpenSSL datatypes, such as I<X509_CRL>.
405 The function parameters I<ppin> and I<ppout> are generally
406 either both named I<pp> in the headers, or I<in> and I<out>.
407
408 These functions convert OpenSSL objects to and from their ASN.1/DER
409 encoding.  Unlike the C structures which can have pointers to sub-objects
410 within, the DER is a serialized encoding, suitable for sending over the
411 network, writing to a file, and so on.
412
413 d2i_TYPE() attempts to decode B<len> bytes at B<*ppin>. If successful a
414 pointer to the B<TYPE> structure is returned and B<*ppin> is incremented to
415 the byte following the parsed data.  If B<a> is not B<NULL> then a pointer
416 to the returned structure is also written to B<*a>.  If an error occurred
417 then B<NULL> is returned.
418
419 On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a>
420 contains a valid B<TYPE> structure and an attempt is made to reuse it. This
421 "reuse" capability is present for historical compatibility but its use is
422 B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
423 VALUES section).
424
425 d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts
426 to parse data from BIO B<bp>.
427
428 d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts
429 to parse data from FILE pointer B<fp>.
430
431 i2d_TYPE() encodes the structure pointed to by B<a> into DER format.
432 If B<ppout> is not B<NULL>, it writes the DER encoded data to the buffer
433 at B<*ppout>, and increments it to point after the data just written.
434 If the return value is negative an error occurred, otherwise it
435 returns the length of the encoded data.
436
437 If B<*ppout> is B<NULL> memory will be allocated for a buffer and the encoded
438 data written to it. In this case B<*ppout> is not incremented and it points
439 to the start of the data just written.
440
441 i2d_TYPE_bio() is similar to i2d_TYPE() except it writes
442 the encoding of the structure B<a> to BIO B<bp> and it
443 returns 1 for success and 0 for failure.
444
445 i2d_TYPE_fp() is similar to i2d_TYPE() except it writes
446 the encoding of the structure B<a> to BIO B<bp> and it
447 returns 1 for success and 0 for failure.
448
449 These routines do not encrypt private keys and therefore offer no
450 security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
451
452 =head1 NOTES
453
454 The letters B<i> and B<d> in B<i2d_TYPE> stand for
455 "internal" (that is, an internal C structure) and "DER" respectively.
456 So B<i2d_TYPE> converts from internal to DER.
457
458 The functions can also understand B<BER> forms.
459
460 The actual TYPE structure passed to i2d_TYPE() must be a valid
461 populated B<TYPE> structure -- it B<cannot> simply be fed with an
462 empty structure such as that returned by TYPE_new().
463
464 The encoded data is in binary form and may contain embedded zeroes.
465 Therefore any FILE pointers or BIOs should be opened in binary mode.
466 Functions such as strlen() will B<not> return the correct length
467 of the encoded structure.
468
469 The ways that B<*ppin> and B<*ppout> are incremented after the operation
470 can trap the unwary. See the B<WARNINGS> section for some common
471 errors.
472 The reason for this-auto increment behaviour is to reflect a typical
473 usage of ASN1 functions: after one structure is encoded or decoded
474 another will be processed after it.
475
476 The following points about the data types might be useful:
477
478 =over 4
479
480 =item B<ASN1_OBJECT>
481
482 Represents an ASN1 OBJECT IDENTIFIER.
483
484 =item B<DHparams>
485
486 Represents a PKCS#3 DH parameters structure.
487
488 =item B<DHparamx>
489
490 Represents an ANSI X9.42 DH parameters structure.
491
492 =item B<DSA_PUBKEY>
493
494 Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
495
496 =item B<DSAPublicKey, DSAPrivateKey>
497
498 Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
499 B<PEM_write_PrivateKey(3)>, or similar instead.
500
501 =item B<RSAPublicKey>
502
503 Represents a PKCS#1 RSA public key structure.
504
505 =item B<X509_ALGOR>
506
507 Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and
508 elsewhere.
509
510 =item B<X509_Name>
511
512 Represents a B<Name> type as used for subject and issuer names in
513 IETF RFC 6960 and elsewhere.
514
515 =item B<X509_REQ>
516
517 Represents a PKCS#10 certificate request.
518
519 =item B<X509_SIG>
520
521 Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
522
523 =back
524
525 =head1 RETURN VALUES
526
527 d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
528 or B<NULL> if an error occurs.  If the "reuse" capability has been used with
529 a valid structure being passed in via B<a>, then the object is freed in
530 the event of error and B<*a> is set to NULL.
531
532 i2d_TYPE() returns the number of bytes successfully encoded or a negative
533 value if an error occurs.
534
535 i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
536 occurs.
537
538 =head1 EXAMPLES
539
540 Allocate and encode the DER encoding of an X509 structure:
541
542  int len;
543  unsigned char *buf;
544
545  buf = NULL;
546  len = i2d_X509(x, &buf);
547  if (len < 0)
548      /* error */
549
550 Attempt to decode a buffer:
551
552  X509 *x;
553  unsigned char *buf, *p;
554  int len;
555
556  /* Set up buf and len to point to the input buffer. */
557  p = buf;
558  x = d2i_X509(NULL, &p, len);
559  if (x == NULL)
560      /* error */
561
562 Alternative technique:
563
564  X509 *x;
565  unsigned char *buf, *p;
566  int len;
567
568  /* Set up buf and len to point to the input buffer. */
569  p = buf;
570  x = NULL;
571
572  if (d2i_X509(&x, &p, len) == NULL)
573      /* error */
574
575 =head1 WARNINGS
576
577 Using a temporary variable is mandatory. A common
578 mistake is to attempt to use a buffer directly as follows:
579
580  int len;
581  unsigned char *buf;
582
583  len = i2d_X509(x, NULL);
584  buf = OPENSSL_malloc(len);
585  ...
586  i2d_X509(x, &buf);
587  ...
588  OPENSSL_free(buf);
589
590 This code will result in B<buf> apparently containing garbage because
591 it was incremented after the call to point after the data just written.
592 Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
593 and the subsequent call to OPENSSL_free() is likely to crash.
594
595 Another trap to avoid is misuse of the B<a> argument to d2i_TYPE():
596
597  X509 *x;
598
599  if (d2i_X509(&x, &p, len) == NULL)
600      /* error */
601
602 This will probably crash somewhere in d2i_X509(). The reason for this
603 is that the variable B<x> is uninitialized and an attempt will be made to
604 interpret its (invalid) value as an B<X509> structure, typically causing
605 a segmentation violation. If B<x> is set to NULL first then this will not
606 happen.
607
608 =head1 BUGS
609
610 In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when
611 B<*a> is valid is broken and some parts of the reused structure may
612 persist if they are not present in the new one. Additionally, in versions of
613 OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs
614 the behaviour is inconsistent. Some functions behaved as described here, while
615 some did not free B<*a> on error and did not set B<*a> to NULL.
616
617 As a result of the above issues the "reuse" behaviour is strongly discouraged.
618
619 i2d_TYPE() will not return an error in many versions of OpenSSL,
620 if mandatory fields are not initialized due to a programming error
621 then the encoded structure may contain invalid data or omit the
622 fields entirely and will not be parsed by d2i_TYPE(). This may be
623 fixed in future so code should not assume that i2d_TYPE() will
624 always succeed.
625
626 Any function which encodes a structure (i2d_TYPE(),
627 i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the
628 structure has been modified after deserialization or previous
629 serialization. This is because some objects cache the encoding for
630 efficiency reasons.
631
632 =head1 COPYRIGHT
633
634 Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved.
635
636 Licensed under the Apache License 2.0 (the "License").  You may not use
637 this file except in compliance with the License.  You can obtain a copy
638 in the file LICENSE in the source distribution or at
639 L<https://www.openssl.org/source/license.html>.
640
641 =cut