1=pod 2 3=begin comment 4 5Any keypair function here that gets deprecated should be moved to 6d2i_RSAPrivateKey.pod. 7 8=end comment 9 10=head1 NAME 11 12d2i_ACCESS_DESCRIPTION, 13d2i_ADMISSIONS, 14d2i_ADMISSION_SYNTAX, 15d2i_ASIdOrRange, 16d2i_ASIdentifierChoice, 17d2i_ASIdentifiers, 18d2i_ASN1_BIT_STRING, 19d2i_ASN1_BMPSTRING, 20d2i_ASN1_ENUMERATED, 21d2i_ASN1_GENERALIZEDTIME, 22d2i_ASN1_GENERALSTRING, 23d2i_ASN1_IA5STRING, 24d2i_ASN1_INTEGER, 25d2i_ASN1_NULL, 26d2i_ASN1_OBJECT, 27d2i_ASN1_OCTET_STRING, 28d2i_ASN1_PRINTABLE, 29d2i_ASN1_PRINTABLESTRING, 30d2i_ASN1_SEQUENCE_ANY, 31d2i_ASN1_SET_ANY, 32d2i_ASN1_T61STRING, 33d2i_ASN1_TIME, 34d2i_ASN1_TYPE, 35d2i_ASN1_UINTEGER, 36d2i_ASN1_UNIVERSALSTRING, 37d2i_ASN1_UTCTIME, 38d2i_ASN1_UTF8STRING, 39d2i_ASN1_VISIBLESTRING, 40d2i_ASRange, 41d2i_AUTHORITY_INFO_ACCESS, 42d2i_AUTHORITY_KEYID, 43d2i_BASIC_CONSTRAINTS, 44d2i_CERTIFICATEPOLICIES, 45d2i_CMS_ContentInfo, 46d2i_CMS_ReceiptRequest, 47d2i_CMS_bio, 48d2i_CRL_DIST_POINTS, 49d2i_DHxparams, 50d2i_DIRECTORYSTRING, 51d2i_DISPLAYTEXT, 52d2i_DIST_POINT, 53d2i_DIST_POINT_NAME, 54d2i_DSA_SIG, 55d2i_ECDSA_SIG, 56d2i_EDIPARTYNAME, 57d2i_ESS_CERT_ID, 58d2i_ESS_CERT_ID_V2, 59d2i_ESS_ISSUER_SERIAL, 60d2i_ESS_SIGNING_CERT, 61d2i_ESS_SIGNING_CERT_V2, 62d2i_EXTENDED_KEY_USAGE, 63d2i_GENERAL_NAME, 64d2i_GENERAL_NAMES, 65d2i_IPAddressChoice, 66d2i_IPAddressFamily, 67d2i_IPAddressOrRange, 68d2i_IPAddressRange, 69d2i_ISSUER_SIGN_TOOL, 70d2i_ISSUING_DIST_POINT, 71d2i_NAMING_AUTHORITY, 72d2i_NETSCAPE_CERT_SEQUENCE, 73d2i_NETSCAPE_SPKAC, 74d2i_NETSCAPE_SPKI, 75d2i_NOTICEREF, 76d2i_OCSP_BASICRESP, 77d2i_OCSP_CERTID, 78d2i_OCSP_CERTSTATUS, 79d2i_OCSP_CRLID, 80d2i_OCSP_ONEREQ, 81d2i_OCSP_REQINFO, 82d2i_OCSP_REQUEST, 83d2i_OCSP_RESPBYTES, 84d2i_OCSP_RESPDATA, 85d2i_OCSP_RESPID, 86d2i_OCSP_RESPONSE, 87d2i_OCSP_REVOKEDINFO, 88d2i_OCSP_SERVICELOC, 89d2i_OCSP_SIGNATURE, 90d2i_OCSP_SINGLERESP, 91d2i_OSSL_CMP_MSG, 92d2i_OSSL_CMP_PKIHEADER, 93d2i_OSSL_CMP_PKISI, 94d2i_OSSL_CRMF_CERTID, 95d2i_OSSL_CRMF_CERTTEMPLATE, 96d2i_OSSL_CRMF_ENCRYPTEDVALUE, 97d2i_OSSL_CRMF_MSG, 98d2i_OSSL_CRMF_MSGS, 99d2i_OSSL_CRMF_PBMPARAMETER, 100d2i_OSSL_CRMF_PKIPUBLICATIONINFO, 101d2i_OSSL_CRMF_SINGLEPUBINFO, 102d2i_OTHERNAME, 103d2i_PBE2PARAM, 104d2i_PBEPARAM, 105d2i_PBKDF2PARAM, 106d2i_PKCS12, 107d2i_PKCS12_BAGS, 108d2i_PKCS12_MAC_DATA, 109d2i_PKCS12_SAFEBAG, 110d2i_PKCS12_bio, 111d2i_PKCS12_fp, 112d2i_PKCS7, 113d2i_PKCS7_DIGEST, 114d2i_PKCS7_ENCRYPT, 115d2i_PKCS7_ENC_CONTENT, 116d2i_PKCS7_ENVELOPE, 117d2i_PKCS7_ISSUER_AND_SERIAL, 118d2i_PKCS7_RECIP_INFO, 119d2i_PKCS7_SIGNED, 120d2i_PKCS7_SIGNER_INFO, 121d2i_PKCS7_SIGN_ENVELOPE, 122d2i_PKCS7_bio, 123d2i_PKCS7_fp, 124d2i_PKCS8_PRIV_KEY_INFO, 125d2i_PKCS8_PRIV_KEY_INFO_bio, 126d2i_PKCS8_PRIV_KEY_INFO_fp, 127d2i_PKCS8_bio, 128d2i_PKCS8_fp, 129d2i_PKEY_USAGE_PERIOD, 130d2i_POLICYINFO, 131d2i_POLICYQUALINFO, 132d2i_PROFESSION_INFO, 133d2i_PROXY_CERT_INFO_EXTENSION, 134d2i_PROXY_POLICY, 135d2i_RSA_OAEP_PARAMS, 136d2i_RSA_PSS_PARAMS, 137d2i_SCRYPT_PARAMS, 138d2i_SCT_LIST, 139d2i_SXNET, 140d2i_SXNETID, 141d2i_TS_ACCURACY, 142d2i_TS_MSG_IMPRINT, 143d2i_TS_MSG_IMPRINT_bio, 144d2i_TS_MSG_IMPRINT_fp, 145d2i_TS_REQ, 146d2i_TS_REQ_bio, 147d2i_TS_REQ_fp, 148d2i_TS_RESP, 149d2i_TS_RESP_bio, 150d2i_TS_RESP_fp, 151d2i_TS_STATUS_INFO, 152d2i_TS_TST_INFO, 153d2i_TS_TST_INFO_bio, 154d2i_TS_TST_INFO_fp, 155d2i_USERNOTICE, 156d2i_X509, 157d2i_X509_bio, 158d2i_X509_fp, 159d2i_X509_ALGOR, 160d2i_X509_ALGORS, 161d2i_X509_ATTRIBUTE, 162d2i_X509_CERT_AUX, 163d2i_X509_CINF, 164d2i_X509_CRL, 165d2i_X509_CRL_INFO, 166d2i_X509_CRL_bio, 167d2i_X509_CRL_fp, 168d2i_X509_EXTENSION, 169d2i_X509_EXTENSIONS, 170d2i_X509_NAME, 171d2i_X509_NAME_ENTRY, 172d2i_X509_PUBKEY, 173d2i_X509_PUBKEY_bio, 174d2i_X509_PUBKEY_fp, 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_DSA_SIG, 225i2d_ECDSA_SIG, 226i2d_EDIPARTYNAME, 227i2d_ESS_CERT_ID, 228i2d_ESS_CERT_ID_V2, 229i2d_ESS_ISSUER_SERIAL, 230i2d_ESS_SIGNING_CERT, 231i2d_ESS_SIGNING_CERT_V2, 232i2d_EXTENDED_KEY_USAGE, 233i2d_GENERAL_NAME, 234i2d_GENERAL_NAMES, 235i2d_IPAddressChoice, 236i2d_IPAddressFamily, 237i2d_IPAddressOrRange, 238i2d_IPAddressRange, 239i2d_ISSUER_SIGN_TOOL, 240i2d_ISSUING_DIST_POINT, 241i2d_NAMING_AUTHORITY, 242i2d_NETSCAPE_CERT_SEQUENCE, 243i2d_NETSCAPE_SPKAC, 244i2d_NETSCAPE_SPKI, 245i2d_NOTICEREF, 246i2d_OCSP_BASICRESP, 247i2d_OCSP_CERTID, 248i2d_OCSP_CERTSTATUS, 249i2d_OCSP_CRLID, 250i2d_OCSP_ONEREQ, 251i2d_OCSP_REQINFO, 252i2d_OCSP_REQUEST, 253i2d_OCSP_RESPBYTES, 254i2d_OCSP_RESPDATA, 255i2d_OCSP_RESPID, 256i2d_OCSP_RESPONSE, 257i2d_OCSP_REVOKEDINFO, 258i2d_OCSP_SERVICELOC, 259i2d_OCSP_SIGNATURE, 260i2d_OCSP_SINGLERESP, 261i2d_OSSL_CMP_MSG, 262i2d_OSSL_CMP_PKIHEADER, 263i2d_OSSL_CMP_PKISI, 264i2d_OSSL_CRMF_CERTID, 265i2d_OSSL_CRMF_CERTTEMPLATE, 266i2d_OSSL_CRMF_ENCRYPTEDVALUE, 267i2d_OSSL_CRMF_MSG, 268i2d_OSSL_CRMF_MSGS, 269i2d_OSSL_CRMF_PBMPARAMETER, 270i2d_OSSL_CRMF_PKIPUBLICATIONINFO, 271i2d_OSSL_CRMF_SINGLEPUBINFO, 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_RSA_OAEP_PARAMS, 309i2d_RSA_PSS_PARAMS, 310i2d_SCRYPT_PARAMS, 311i2d_SCT_LIST, 312i2d_SXNET, 313i2d_SXNETID, 314i2d_TS_ACCURACY, 315i2d_TS_MSG_IMPRINT, 316i2d_TS_MSG_IMPRINT_bio, 317i2d_TS_MSG_IMPRINT_fp, 318i2d_TS_REQ, 319i2d_TS_REQ_bio, 320i2d_TS_REQ_fp, 321i2d_TS_RESP, 322i2d_TS_RESP_bio, 323i2d_TS_RESP_fp, 324i2d_TS_STATUS_INFO, 325i2d_TS_TST_INFO, 326i2d_TS_TST_INFO_bio, 327i2d_TS_TST_INFO_fp, 328i2d_USERNOTICE, 329i2d_X509, 330i2d_X509_bio, 331i2d_X509_fp, 332i2d_X509_ALGOR, 333i2d_X509_ALGORS, 334i2d_X509_ATTRIBUTE, 335i2d_X509_CERT_AUX, 336i2d_X509_CINF, 337i2d_X509_CRL, 338i2d_X509_CRL_INFO, 339i2d_X509_CRL_bio, 340i2d_X509_CRL_fp, 341i2d_X509_EXTENSION, 342i2d_X509_EXTENSIONS, 343i2d_X509_NAME, 344i2d_X509_NAME_ENTRY, 345i2d_X509_PUBKEY, 346i2d_X509_PUBKEY_bio, 347i2d_X509_PUBKEY_fp, 348i2d_X509_REQ, 349i2d_X509_REQ_INFO, 350i2d_X509_REQ_bio, 351i2d_X509_REQ_fp, 352i2d_X509_REVOKED, 353i2d_X509_SIG, 354i2d_X509_VAL, 355- convert objects from/to ASN.1/DER representation 356 357=head1 SYNOPSIS 358 359=for openssl generic 360 361 TYPE *d2i_TYPE(TYPE **a, const unsigned char **ppin, long length); 362 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); 363 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); 364 365 int i2d_TYPE(const TYPE *a, unsigned char **ppout); 366 int i2d_TYPE(TYPE *a, unsigned char **ppout); 367 int i2d_TYPE_fp(FILE *fp, const TYPE *a); 368 int i2d_TYPE_fp(FILE *fp, TYPE *a); 369 int i2d_TYPE_bio(BIO *bp, const TYPE *a); 370 int i2d_TYPE_bio(BIO *bp, TYPE *a); 371 372=head1 DESCRIPTION 373 374In the description here, B<I<TYPE>> is used a placeholder 375for any of the OpenSSL datatypes, such as B<X509_CRL>. 376The function parameters I<ppin> and I<ppout> are generally 377either both named I<pp> in the headers, or I<in> and I<out>. 378 379These functions convert OpenSSL objects to and from their ASN.1/DER 380encoding. Unlike the C structures which can have pointers to sub-objects 381within, the DER is a serialized encoding, suitable for sending over the 382network, writing to a file, and so on. 383 384B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a 385pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to 386the byte following the parsed data. If I<a> is not NULL then a pointer 387to the returned structure is also written to I<*a>. If an error occurred 388then NULL is returned. 389 390On a successful return, if I<*a> is not NULL then it is assumed that I<*a> 391contains a valid B<I<TYPE>> structure and an attempt is made to reuse it. This 392"reuse" capability is present for historical compatibility but its use is 393B<strongly discouraged> (see BUGS below, and the discussion in the RETURN 394VALUES section). 395 396B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts 397to parse data from BIO I<bp>. 398 399B<d2i_I<TYPE>_fp>() is similar to B<d2i_I<TYPE>>() except it attempts 400to parse data from FILE pointer I<fp>. 401 402B<i2d_I<TYPE>>() encodes the structure pointed to by I<a> into DER format. 403If I<ppout> is not NULL, it writes the DER encoded data to the buffer 404at I<*ppout>, and increments it to point after the data just written. 405If the return value is negative an error occurred, otherwise it 406returns the length of the encoded data. 407 408If I<*ppout> is NULL memory will be allocated for a buffer and the encoded 409data written to it. In this case I<*ppout> is not incremented and it points 410to the start of the data just written. 411 412B<i2d_I<TYPE>_bio>() is similar to B<i2d_I<TYPE>>() except it writes 413the encoding of the structure I<a> to BIO I<bp> and it 414returns 1 for success and 0 for failure. 415 416B<i2d_I<TYPE>_fp>() is similar to B<i2d_I<TYPE>>() except it writes 417the encoding of the structure I<a> to FILE pointer I<fp> and it 418returns 1 for success and 0 for failure. 419 420These routines do not encrypt private keys and therefore offer no 421security; use L<PEM_write_PrivateKey(3)> or similar for writing to files. 422 423=head1 NOTES 424 425The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for 426"internal" (that is, an internal C structure) and "DER" respectively. 427So B<i2d_I<TYPE>>() converts from internal to DER. 428 429The functions can also understand B<BER> forms. 430 431The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid 432populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an 433empty structure such as that returned by TYPE_new(). 434 435The encoded data is in binary form and may contain embedded zeros. 436Therefore, any FILE pointers or BIOs should be opened in binary mode. 437Functions such as strlen() will B<not> return the correct length 438of the encoded structure. 439 440The ways that I<*ppin> and I<*ppout> are incremented after the operation 441can trap the unwary. See the B<WARNINGS> section for some common 442errors. 443The reason for this-auto increment behaviour is to reflect a typical 444usage of ASN1 functions: after one structure is encoded or decoded 445another will be processed after it. 446 447The following points about the data types might be useful: 448 449=over 4 450 451=item B<ASN1_OBJECT> 452 453Represents an ASN1 OBJECT IDENTIFIER. 454 455=item B<DHparams> 456 457Represents a PKCS#3 DH parameters structure. 458 459=item B<DHxparams> 460 461Represents an ANSI X9.42 DH parameters structure. 462 463=item B<ECDSA_SIG> 464 465Represents an ECDSA signature. 466 467=item B<X509_ALGOR> 468 469Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and 470elsewhere. 471 472=item B<X509_NAME> 473 474Represents a B<Name> type as used for subject and issuer names in 475IETF RFC 6960 and elsewhere. 476 477=item B<X509_REQ> 478 479Represents a PKCS#10 certificate request. 480 481=item B<X509_SIG> 482 483Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7. 484 485=back 486 487=head1 RETURN VALUES 488 489B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid 490B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has 491been used with a valid structure being passed in via I<a>, then the object is 492freed in the event of error and I<*a> is set to NULL. 493 494B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative 495value if an error occurs. 496 497B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an 498error occurs. 499 500=head1 EXAMPLES 501 502Allocate and encode the DER encoding of an X509 structure: 503 504 int len; 505 unsigned char *buf; 506 507 buf = NULL; 508 len = i2d_X509(x, &buf); 509 if (len < 0) 510 /* error */ 511 512Attempt to decode a buffer: 513 514 X509 *x; 515 unsigned char *buf; 516 const unsigned char *p; 517 int len; 518 519 /* Set up buf and len to point to the input buffer. */ 520 p = buf; 521 x = d2i_X509(NULL, &p, len); 522 if (x == NULL) 523 /* error */ 524 525Alternative technique: 526 527 X509 *x; 528 unsigned char *buf; 529 const unsigned char *p; 530 int len; 531 532 /* Set up buf and len to point to the input buffer. */ 533 p = buf; 534 x = NULL; 535 536 if (d2i_X509(&x, &p, len) == NULL) 537 /* error */ 538 539=head1 WARNINGS 540 541Using a temporary variable is mandatory. A common 542mistake is to attempt to use a buffer directly as follows: 543 544 int len; 545 unsigned char *buf; 546 547 len = i2d_X509(x, NULL); 548 buf = OPENSSL_malloc(len); 549 ... 550 i2d_X509(x, &buf); 551 ... 552 OPENSSL_free(buf); 553 554This code will result in I<buf> apparently containing garbage because 555it was incremented after the call to point after the data just written. 556Also I<buf> will no longer contain the pointer allocated by OPENSSL_malloc() 557and the subsequent call to OPENSSL_free() is likely to crash. 558 559Another trap to avoid is misuse of the I<a> argument to B<d2i_I<TYPE>>(): 560 561 X509 *x; 562 563 if (d2i_X509(&x, &p, len) == NULL) 564 /* error */ 565 566This will probably crash somewhere in d2i_X509(). The reason for this 567is that the variable I<x> is uninitialized and an attempt will be made to 568interpret its (invalid) value as an B<X509> structure, typically causing 569a segmentation violation. If I<x> is set to NULL first then this will not 570happen. 571 572=head1 BUGS 573 574In some versions of OpenSSL the "reuse" behaviour of B<d2i_I<TYPE>>() when 575I<*a> is valid is broken and some parts of the reused structure may 576persist if they are not present in the new one. Additionally, in versions of 577OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs 578the behaviour is inconsistent. Some functions behaved as described here, while 579some did not free I<*a> on error and did not set I<*a> to NULL. 580 581As a result of the above issues the "reuse" behaviour is strongly discouraged. 582 583B<i2d_I<TYPE>>() will not return an error in many versions of OpenSSL, 584if mandatory fields are not initialized due to a programming error 585then the encoded structure may contain invalid data or omit the 586fields entirely and will not be parsed by B<d2i_I<TYPE>>(). This may be 587fixed in future so code should not assume that B<i2d_I<TYPE>>() will 588always succeed. 589 590Any function which encodes a structure (B<i2d_I<TYPE>>(), 591B<i2d_I<TYPE>_bio>() or B<i2d_I<TYPE>_fp>()) may return a stale encoding if the 592structure has been modified after deserialization or previous 593serialization. This is because some objects cache the encoding for 594efficiency reasons. 595 596=head1 COPYRIGHT 597 598Copyright 1998-2023 The OpenSSL Project Authors. All Rights Reserved. 599 600Licensed under the Apache License 2.0 (the "License"). You may not use 601this file except in compliance with the License. You can obtain a copy 602in the file LICENSE in the source distribution or at 603L<https://www.openssl.org/source/license.html>. 604 605=cut 606