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