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_ALGOR, 158d2i_X509_ALGORS, 159d2i_X509_ATTRIBUTE, 160d2i_X509_CERT_AUX, 161d2i_X509_CINF, 162d2i_X509_CRL, 163d2i_X509_CRL_INFO, 164d2i_X509_CRL_bio, 165d2i_X509_CRL_fp, 166d2i_X509_EXTENSION, 167d2i_X509_EXTENSIONS, 168d2i_X509_NAME, 169d2i_X509_NAME_ENTRY, 170d2i_X509_PUBKEY, 171d2i_X509_PUBKEY_bio, 172d2i_X509_PUBKEY_fp, 173d2i_X509_REQ, 174d2i_X509_REQ_INFO, 175d2i_X509_REQ_bio, 176d2i_X509_REQ_fp, 177d2i_X509_REVOKED, 178d2i_X509_SIG, 179d2i_X509_VAL, 180i2d_ACCESS_DESCRIPTION, 181i2d_ADMISSIONS, 182i2d_ADMISSION_SYNTAX, 183i2d_ASIdOrRange, 184i2d_ASIdentifierChoice, 185i2d_ASIdentifiers, 186i2d_ASN1_BIT_STRING, 187i2d_ASN1_BMPSTRING, 188i2d_ASN1_ENUMERATED, 189i2d_ASN1_GENERALIZEDTIME, 190i2d_ASN1_GENERALSTRING, 191i2d_ASN1_IA5STRING, 192i2d_ASN1_INTEGER, 193i2d_ASN1_NULL, 194i2d_ASN1_OBJECT, 195i2d_ASN1_OCTET_STRING, 196i2d_ASN1_PRINTABLE, 197i2d_ASN1_PRINTABLESTRING, 198i2d_ASN1_SEQUENCE_ANY, 199i2d_ASN1_SET_ANY, 200i2d_ASN1_T61STRING, 201i2d_ASN1_TIME, 202i2d_ASN1_TYPE, 203i2d_ASN1_UNIVERSALSTRING, 204i2d_ASN1_UTCTIME, 205i2d_ASN1_UTF8STRING, 206i2d_ASN1_VISIBLESTRING, 207i2d_ASN1_bio_stream, 208i2d_ASRange, 209i2d_AUTHORITY_INFO_ACCESS, 210i2d_AUTHORITY_KEYID, 211i2d_BASIC_CONSTRAINTS, 212i2d_CERTIFICATEPOLICIES, 213i2d_CMS_ContentInfo, 214i2d_CMS_ReceiptRequest, 215i2d_CMS_bio, 216i2d_CRL_DIST_POINTS, 217i2d_DHxparams, 218i2d_DIRECTORYSTRING, 219i2d_DISPLAYTEXT, 220i2d_DIST_POINT, 221i2d_DIST_POINT_NAME, 222i2d_DSA_SIG, 223i2d_ECDSA_SIG, 224i2d_EDIPARTYNAME, 225i2d_ESS_CERT_ID, 226i2d_ESS_CERT_ID_V2, 227i2d_ESS_ISSUER_SERIAL, 228i2d_ESS_SIGNING_CERT, 229i2d_ESS_SIGNING_CERT_V2, 230i2d_EXTENDED_KEY_USAGE, 231i2d_GENERAL_NAME, 232i2d_GENERAL_NAMES, 233i2d_IPAddressChoice, 234i2d_IPAddressFamily, 235i2d_IPAddressOrRange, 236i2d_IPAddressRange, 237i2d_ISSUER_SIGN_TOOL, 238i2d_ISSUING_DIST_POINT, 239i2d_NAMING_AUTHORITY, 240i2d_NETSCAPE_CERT_SEQUENCE, 241i2d_NETSCAPE_SPKAC, 242i2d_NETSCAPE_SPKI, 243i2d_NOTICEREF, 244i2d_OCSP_BASICRESP, 245i2d_OCSP_CERTID, 246i2d_OCSP_CERTSTATUS, 247i2d_OCSP_CRLID, 248i2d_OCSP_ONEREQ, 249i2d_OCSP_REQINFO, 250i2d_OCSP_REQUEST, 251i2d_OCSP_RESPBYTES, 252i2d_OCSP_RESPDATA, 253i2d_OCSP_RESPID, 254i2d_OCSP_RESPONSE, 255i2d_OCSP_REVOKEDINFO, 256i2d_OCSP_SERVICELOC, 257i2d_OCSP_SIGNATURE, 258i2d_OCSP_SINGLERESP, 259i2d_OSSL_CMP_MSG, 260i2d_OSSL_CMP_PKIHEADER, 261i2d_OSSL_CMP_PKISI, 262i2d_OSSL_CRMF_CERTID, 263i2d_OSSL_CRMF_CERTTEMPLATE, 264i2d_OSSL_CRMF_ENCRYPTEDVALUE, 265i2d_OSSL_CRMF_MSG, 266i2d_OSSL_CRMF_MSGS, 267i2d_OSSL_CRMF_PBMPARAMETER, 268i2d_OSSL_CRMF_PKIPUBLICATIONINFO, 269i2d_OSSL_CRMF_SINGLEPUBINFO, 270i2d_OTHERNAME, 271i2d_PBE2PARAM, 272i2d_PBEPARAM, 273i2d_PBKDF2PARAM, 274i2d_PKCS12, 275i2d_PKCS12_BAGS, 276i2d_PKCS12_MAC_DATA, 277i2d_PKCS12_SAFEBAG, 278i2d_PKCS12_bio, 279i2d_PKCS12_fp, 280i2d_PKCS7, 281i2d_PKCS7_DIGEST, 282i2d_PKCS7_ENCRYPT, 283i2d_PKCS7_ENC_CONTENT, 284i2d_PKCS7_ENVELOPE, 285i2d_PKCS7_ISSUER_AND_SERIAL, 286i2d_PKCS7_NDEF, 287i2d_PKCS7_RECIP_INFO, 288i2d_PKCS7_SIGNED, 289i2d_PKCS7_SIGNER_INFO, 290i2d_PKCS7_SIGN_ENVELOPE, 291i2d_PKCS7_bio, 292i2d_PKCS7_fp, 293i2d_PKCS8PrivateKeyInfo_bio, 294i2d_PKCS8PrivateKeyInfo_fp, 295i2d_PKCS8_PRIV_KEY_INFO, 296i2d_PKCS8_PRIV_KEY_INFO_bio, 297i2d_PKCS8_PRIV_KEY_INFO_fp, 298i2d_PKCS8_bio, 299i2d_PKCS8_fp, 300i2d_PKEY_USAGE_PERIOD, 301i2d_POLICYINFO, 302i2d_POLICYQUALINFO, 303i2d_PROFESSION_INFO, 304i2d_PROXY_CERT_INFO_EXTENSION, 305i2d_PROXY_POLICY, 306i2d_RSA_OAEP_PARAMS, 307i2d_RSA_PSS_PARAMS, 308i2d_SCRYPT_PARAMS, 309i2d_SCT_LIST, 310i2d_SXNET, 311i2d_SXNETID, 312i2d_TS_ACCURACY, 313i2d_TS_MSG_IMPRINT, 314i2d_TS_MSG_IMPRINT_bio, 315i2d_TS_MSG_IMPRINT_fp, 316i2d_TS_REQ, 317i2d_TS_REQ_bio, 318i2d_TS_REQ_fp, 319i2d_TS_RESP, 320i2d_TS_RESP_bio, 321i2d_TS_RESP_fp, 322i2d_TS_STATUS_INFO, 323i2d_TS_TST_INFO, 324i2d_TS_TST_INFO_bio, 325i2d_TS_TST_INFO_fp, 326i2d_USERNOTICE, 327i2d_X509, 328i2d_X509_ALGOR, 329i2d_X509_ALGORS, 330i2d_X509_ATTRIBUTE, 331i2d_X509_CERT_AUX, 332i2d_X509_CINF, 333i2d_X509_CRL, 334i2d_X509_CRL_INFO, 335i2d_X509_CRL_bio, 336i2d_X509_CRL_fp, 337i2d_X509_EXTENSION, 338i2d_X509_EXTENSIONS, 339i2d_X509_NAME, 340i2d_X509_NAME_ENTRY, 341i2d_X509_PUBKEY, 342i2d_X509_PUBKEY_bio, 343i2d_X509_PUBKEY_fp, 344i2d_X509_REQ, 345i2d_X509_REQ_INFO, 346i2d_X509_REQ_bio, 347i2d_X509_REQ_fp, 348i2d_X509_REVOKED, 349i2d_X509_SIG, 350i2d_X509_VAL, 351- convert objects from/to ASN.1/DER representation 352 353=head1 SYNOPSIS 354 355=for openssl generic 356 357 TYPE *d2i_TYPE(TYPE **a, const unsigned char **ppin, long length); 358 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); 359 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); 360 361 int i2d_TYPE(const TYPE *a, unsigned char **ppout); 362 int i2d_TYPE(TYPE *a, unsigned char **ppout); 363 int i2d_TYPE_fp(FILE *fp, const TYPE *a); 364 int i2d_TYPE_fp(FILE *fp, TYPE *a); 365 int i2d_TYPE_bio(BIO *bp, const TYPE *a); 366 int i2d_TYPE_bio(BIO *bp, TYPE *a); 367 368=head1 DESCRIPTION 369 370In the description here, B<I<TYPE>> is used a placeholder 371for any of the OpenSSL datatypes, such as B<X509_CRL>. 372The function parameters I<ppin> and I<ppout> are generally 373either both named I<pp> in the headers, or I<in> and I<out>. 374 375These functions convert OpenSSL objects to and from their ASN.1/DER 376encoding. Unlike the C structures which can have pointers to sub-objects 377within, the DER is a serialized encoding, suitable for sending over the 378network, writing to a file, and so on. 379 380B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a 381pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to 382the byte following the parsed data. If I<a> is not NULL then a pointer 383to the returned structure is also written to I<*a>. If an error occurred 384then NULL is returned. 385 386On a successful return, if I<*a> is not NULL then it is assumed that I<*a> 387contains a valid B<I<TYPE>> structure and an attempt is made to reuse it. This 388"reuse" capability is present for historical compatibility but its use is 389B<strongly discouraged> (see BUGS below, and the discussion in the RETURN 390VALUES section). 391 392B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts 393to parse data from BIO I<bp>. 394 395B<d2i_I<TYPE>_fp>() is similar to B<d2i_I<TYPE>>() except it attempts 396to parse data from FILE pointer I<fp>. 397 398B<i2d_I<TYPE>>() encodes the structure pointed to by I<a> into DER format. 399If I<ppout> is not NULL, it writes the DER encoded data to the buffer 400at I<*ppout>, and increments it to point after the data just written. 401If the return value is negative an error occurred, otherwise it 402returns the length of the encoded data. 403 404If I<*ppout> is NULL memory will be allocated for a buffer and the encoded 405data written to it. In this case I<*ppout> is not incremented and it points 406to the start of the data just written. 407 408B<i2d_I<TYPE>_bio>() is similar to B<i2d_I<TYPE>>() except it writes 409the encoding of the structure I<a> to BIO I<bp> and it 410returns 1 for success and 0 for failure. 411 412B<i2d_I<TYPE>_fp>() is similar to B<i2d_I<TYPE>>() except it writes 413the encoding of the structure I<a> to FILE pointer I<fp> and it 414returns 1 for success and 0 for failure. 415 416These routines do not encrypt private keys and therefore offer no 417security; use L<PEM_write_PrivateKey(3)> or similar for writing to files. 418 419=head1 NOTES 420 421The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for 422"internal" (that is, an internal C structure) and "DER" respectively. 423So B<i2d_I<TYPE>>() converts from internal to DER. 424 425The functions can also understand B<BER> forms. 426 427The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid 428populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an 429empty structure such as that returned by TYPE_new(). 430 431The encoded data is in binary form and may contain embedded zeros. 432Therefore, any FILE pointers or BIOs should be opened in binary mode. 433Functions such as strlen() will B<not> return the correct length 434of the encoded structure. 435 436The ways that I<*ppin> and I<*ppout> are incremented after the operation 437can trap the unwary. See the B<WARNINGS> section for some common 438errors. 439The reason for this-auto increment behaviour is to reflect a typical 440usage of ASN1 functions: after one structure is encoded or decoded 441another will be processed after it. 442 443The following points about the data types might be useful: 444 445=over 4 446 447=item B<ASN1_OBJECT> 448 449Represents an ASN1 OBJECT IDENTIFIER. 450 451=item B<DHparams> 452 453Represents a PKCS#3 DH parameters structure. 454 455=item B<DHxparams> 456 457Represents an ANSI X9.42 DH parameters structure. 458 459=item B<ECDSA_SIG> 460 461Represents an ECDSA signature. 462 463=item B<X509_ALGOR> 464 465Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and 466elsewhere. 467 468=item B<X509_Name> 469 470Represents a B<Name> type as used for subject and issuer names in 471IETF RFC 6960 and elsewhere. 472 473=item B<X509_REQ> 474 475Represents a PKCS#10 certificate request. 476 477=item B<X509_SIG> 478 479Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7. 480 481=back 482 483=head1 RETURN VALUES 484 485B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid 486B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has 487been used with a valid structure being passed in via I<a>, then the object is 488freed in the event of error and I<*a> is set to NULL. 489 490B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative 491value if an error occurs. 492 493B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an 494error occurs. 495 496=head1 EXAMPLES 497 498Allocate and encode the DER encoding of an X509 structure: 499 500 int len; 501 unsigned char *buf; 502 503 buf = NULL; 504 len = i2d_X509(x, &buf); 505 if (len < 0) 506 /* error */ 507 508Attempt to decode a buffer: 509 510 X509 *x; 511 unsigned char *buf; 512 const unsigned char *p; 513 int len; 514 515 /* Set up buf and len to point to the input buffer. */ 516 p = buf; 517 x = d2i_X509(NULL, &p, len); 518 if (x == NULL) 519 /* error */ 520 521Alternative technique: 522 523 X509 *x; 524 unsigned char *buf; 525 const unsigned char *p; 526 int len; 527 528 /* Set up buf and len to point to the input buffer. */ 529 p = buf; 530 x = NULL; 531 532 if (d2i_X509(&x, &p, len) == NULL) 533 /* error */ 534 535=head1 WARNINGS 536 537Using a temporary variable is mandatory. A common 538mistake is to attempt to use a buffer directly as follows: 539 540 int len; 541 unsigned char *buf; 542 543 len = i2d_X509(x, NULL); 544 buf = OPENSSL_malloc(len); 545 ... 546 i2d_X509(x, &buf); 547 ... 548 OPENSSL_free(buf); 549 550This code will result in I<buf> apparently containing garbage because 551it was incremented after the call to point after the data just written. 552Also I<buf> will no longer contain the pointer allocated by OPENSSL_malloc() 553and the subsequent call to OPENSSL_free() is likely to crash. 554 555Another trap to avoid is misuse of the I<a> argument to B<d2i_I<TYPE>>(): 556 557 X509 *x; 558 559 if (d2i_X509(&x, &p, len) == NULL) 560 /* error */ 561 562This will probably crash somewhere in d2i_X509(). The reason for this 563is that the variable I<x> is uninitialized and an attempt will be made to 564interpret its (invalid) value as an B<X509> structure, typically causing 565a segmentation violation. If I<x> is set to NULL first then this will not 566happen. 567 568=head1 BUGS 569 570In some versions of OpenSSL the "reuse" behaviour of B<d2i_I<TYPE>>() when 571I<*a> is valid is broken and some parts of the reused structure may 572persist if they are not present in the new one. Additionally, in versions of 573OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs 574the behaviour is inconsistent. Some functions behaved as described here, while 575some did not free I<*a> on error and did not set I<*a> to NULL. 576 577As a result of the above issues the "reuse" behaviour is strongly discouraged. 578 579B<i2d_I<TYPE>>() will not return an error in many versions of OpenSSL, 580if mandatory fields are not initialized due to a programming error 581then the encoded structure may contain invalid data or omit the 582fields entirely and will not be parsed by B<d2i_I<TYPE>>(). This may be 583fixed in future so code should not assume that B<i2d_I<TYPE>>() will 584always succeed. 585 586Any function which encodes a structure (B<i2d_I<TYPE>>(), 587B<i2d_I<TYPE>>() or B<i2d_I<TYPE>>()) may return a stale encoding if the 588structure has been modified after deserialization or previous 589serialization. This is because some objects cache the encoding for 590efficiency reasons. 591 592=head1 COPYRIGHT 593 594Copyright 1998-2021 The OpenSSL Project Authors. All Rights Reserved. 595 596Licensed under the Apache License 2.0 (the "License"). You may not use 597this file except in compliance with the License. You can obtain a copy 598in the file LICENSE in the source distribution or at 599L<https://www.openssl.org/source/license.html>. 600 601=cut 602