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