doc/man3/d2i_X509.pod

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