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