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