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