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