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