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