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