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