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_PublicKey, 311i2d_RSAPrivateKey, 312i2d_RSAPrivateKey_bio, 313i2d_RSAPrivateKey_fp, 314i2d_RSAPublicKey, 315i2d_RSAPublicKey_bio, 316i2d_RSAPublicKey_fp, 317i2d_RSA_OAEP_PARAMS, 318i2d_RSA_PSS_PARAMS, 319i2d_RSA_PUBKEY, 320i2d_RSA_PUBKEY_bio, 321i2d_RSA_PUBKEY_fp, 322i2d_SCRYPT_PARAMS, 323i2d_SCT_LIST, 324i2d_SXNET, 325i2d_SXNETID, 326i2d_TS_ACCURACY, 327i2d_TS_MSG_IMPRINT, 328i2d_TS_MSG_IMPRINT_bio, 329i2d_TS_MSG_IMPRINT_fp, 330i2d_TS_REQ, 331i2d_TS_REQ_bio, 332i2d_TS_REQ_fp, 333i2d_TS_RESP, 334i2d_TS_RESP_bio, 335i2d_TS_RESP_fp, 336i2d_TS_STATUS_INFO, 337i2d_TS_TST_INFO, 338i2d_TS_TST_INFO_bio, 339i2d_TS_TST_INFO_fp, 340i2d_USERNOTICE, 341i2d_X509, 342i2d_X509_ALGOR, 343i2d_X509_ALGORS, 344i2d_X509_ATTRIBUTE, 345i2d_X509_CERT_AUX, 346i2d_X509_CINF, 347i2d_X509_CRL, 348i2d_X509_CRL_INFO, 349i2d_X509_CRL_bio, 350i2d_X509_CRL_fp, 351i2d_X509_EXTENSION, 352i2d_X509_EXTENSIONS, 353i2d_X509_NAME, 354i2d_X509_NAME_ENTRY, 355i2d_X509_PUBKEY, 356i2d_X509_REQ, 357i2d_X509_REQ_INFO, 358i2d_X509_REQ_bio, 359i2d_X509_REQ_fp, 360i2d_X509_REVOKED, 361i2d_X509_SIG, 362i2d_X509_VAL, 363- convert objects from/to ASN.1/DER representation 364 365=head1 SYNOPSIS 366 367=for comment generic 368 369 TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length); 370 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); 371 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); 372 373 int i2d_TYPE(TYPE *a, unsigned char **ppout); 374 int i2d_TYPE_fp(FILE *fp, TYPE *a); 375 int i2d_TYPE_bio(BIO *bp, TYPE *a); 376 377=head1 DESCRIPTION 378 379In the description here, I<TYPE> is used a placeholder 380for any of the OpenSSL datatypes, such as I<X509_CRL>. 381The function parameters I<ppin> and I<ppout> are generally 382either both named I<pp> in the headers, or I<in> and I<out>. 383 384These functions convert OpenSSL objects to and from their ASN.1/DER 385encoding. Unlike the C structures which can have pointers to sub-objects 386within, the DER is a serialized encoding, suitable for sending over the 387network, writing to a file, and so on. 388 389d2i_TYPE() attempts to decode B<len> bytes at B<*ppin>. If successful a 390pointer to the B<TYPE> structure is returned and B<*ppin> is incremented to 391the byte following the parsed data. If B<a> is not B<NULL> then a pointer 392to the returned structure is also written to B<*a>. If an error occurred 393then B<NULL> is returned. 394 395On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a> 396contains a valid B<TYPE> structure and an attempt is made to reuse it. This 397"reuse" capability is present for historical compatibility but its use is 398B<strongly discouraged> (see BUGS below, and the discussion in the RETURN 399VALUES section). 400 401d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts 402to parse data from BIO B<bp>. 403 404d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts 405to parse data from FILE pointer B<fp>. 406 407i2d_TYPE() encodes the structure pointed to by B<a> into DER format. 408If B<ppout> is not B<NULL>, it writes the DER encoded data to the buffer 409at B<*ppout>, and increments it to point after the data just written. 410If the return value is negative an error occurred, otherwise it 411returns the length of the encoded data. 412 413If B<*ppout> is B<NULL> memory will be allocated for a buffer and the encoded 414data written to it. In this case B<*ppout> is not incremented and it points 415to the start of the data just written. 416 417i2d_TYPE_bio() is similar to i2d_TYPE() except it writes 418the encoding of the structure B<a> to BIO B<bp> and it 419returns 1 for success and 0 for failure. 420 421i2d_TYPE_fp() is similar to i2d_TYPE() except it writes 422the encoding of the structure B<a> to BIO B<bp> and it 423returns 1 for success and 0 for failure. 424 425These routines do not encrypt private keys and therefore offer no 426security; use L<PEM_write_PrivateKey(3)> or similar for writing to files. 427 428=head1 NOTES 429 430The letters B<i> and B<d> in B<i2d_TYPE> stand for 431"internal" (that is, an internal C structure) and "DER" respectively. 432So B<i2d_TYPE> converts from internal to DER. 433 434The functions can also understand B<BER> forms. 435 436The actual TYPE structure passed to i2d_TYPE() must be a valid 437populated B<TYPE> structure -- it B<cannot> simply be fed with an 438empty structure such as that returned by TYPE_new(). 439 440The encoded data is in binary form and may contain embedded zeroes. 441Therefore any FILE pointers or BIOs should be opened in binary mode. 442Functions such as strlen() will B<not> return the correct length 443of the encoded structure. 444 445The ways that B<*ppin> and B<*ppout> are incremented after the operation 446can trap the unwary. See the B<WARNINGS> section for some common 447errors. 448The reason for this-auto increment behaviour is to reflect a typical 449usage of ASN1 functions: after one structure is encoded or decoded 450another will be processed after it. 451 452The following points about the data types might be useful: 453 454=over 4 455 456=item B<ASN1_OBJECT> 457 458Represents an ASN1 OBJECT IDENTIFIER. 459 460=item B<DHparams> 461 462Represents a PKCS#3 DH parameters structure. 463 464=item B<DHparamx> 465 466Represents an ANSI X9.42 DH parameters structure. 467 468=item B<DSA_PUBKEY> 469 470Represents a DSA public key using a B<SubjectPublicKeyInfo> structure. 471 472=item B<DSAPublicKey, DSAPrivateKey> 473 474Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>, 475B<PEM_write_PrivateKey(3)>, or similar instead. 476 477=item B<ECDSA_SIG> 478 479Represents an ECDSA signature. 480 481=item B<RSAPublicKey> 482 483Represents a PKCS#1 RSA public key structure. 484 485=item B<X509_ALGOR> 486 487Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and 488elsewhere. 489 490=item B<X509_Name> 491 492Represents a B<Name> type as used for subject and issuer names in 493IETF RFC 6960 and elsewhere. 494 495=item B<X509_REQ> 496 497Represents a PKCS#10 certificate request. 498 499=item B<X509_SIG> 500 501Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7. 502 503=back 504 505=head1 RETURN VALUES 506 507d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure 508or B<NULL> if an error occurs. If the "reuse" capability has been used with 509a valid structure being passed in via B<a>, then the object is freed in 510the event of error and B<*a> is set to NULL. 511 512i2d_TYPE() returns the number of bytes successfully encoded or a negative 513value if an error occurs. 514 515i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error 516occurs. 517 518=head1 EXAMPLES 519 520Allocate and encode the DER encoding of an X509 structure: 521 522 int len; 523 unsigned char *buf; 524 525 buf = NULL; 526 len = i2d_X509(x, &buf); 527 if (len < 0) 528 /* error */ 529 530Attempt to decode a buffer: 531 532 X509 *x; 533 unsigned char *buf, *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, *p; 546 int len; 547 548 /* Set up buf and len to point to the input buffer. */ 549 p = buf; 550 x = NULL; 551 552 if (d2i_X509(&x, &p, len) == NULL) 553 /* error */ 554 555=head1 WARNINGS 556 557Using a temporary variable is mandatory. A common 558mistake is to attempt to use a buffer directly as follows: 559 560 int len; 561 unsigned char *buf; 562 563 len = i2d_X509(x, NULL); 564 buf = OPENSSL_malloc(len); 565 ... 566 i2d_X509(x, &buf); 567 ... 568 OPENSSL_free(buf); 569 570This code will result in B<buf> apparently containing garbage because 571it was incremented after the call to point after the data just written. 572Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc() 573and the subsequent call to OPENSSL_free() is likely to crash. 574 575Another trap to avoid is misuse of the B<a> argument to d2i_TYPE(): 576 577 X509 *x; 578 579 if (d2i_X509(&x, &p, len) == NULL) 580 /* error */ 581 582This will probably crash somewhere in d2i_X509(). The reason for this 583is that the variable B<x> is uninitialized and an attempt will be made to 584interpret its (invalid) value as an B<X509> structure, typically causing 585a segmentation violation. If B<x> is set to NULL first then this will not 586happen. 587 588=head1 BUGS 589 590In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when 591B<*a> is valid is broken and some parts of the reused structure may 592persist if they are not present in the new one. Additionally, in versions of 593OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs 594the behaviour is inconsistent. Some functions behaved as described here, while 595some did not free B<*a> on error and did not set B<*a> to NULL. 596 597As a result of the above issues the "reuse" behaviour is strongly discouraged. 598 599i2d_TYPE() will not return an error in many versions of OpenSSL, 600if mandatory fields are not initialized due to a programming error 601then the encoded structure may contain invalid data or omit the 602fields entirely and will not be parsed by d2i_TYPE(). This may be 603fixed in future so code should not assume that i2d_TYPE() will 604always succeed. 605 606Any function which encodes a structure (i2d_TYPE(), 607i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the 608structure has been modified after deserialization or previous 609serialization. This is because some objects cache the encoding for 610efficiency reasons. 611 612=head1 COPYRIGHT 613 614Copyright 1998-2019 The OpenSSL Project Authors. All Rights Reserved. 615 616Licensed under the OpenSSL license (the "License"). You may not use 617this file except in compliance with the License. You can obtain a copy 618in the file LICENSE in the source distribution or at 619L<https://www.openssl.org/source/license.html>. 620 621=cut 622