doc/man3/d2i_X509.pod

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