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