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_AA_DIST_POINT, 93d2i_OSSL_ALLOWED_ATTRIBUTES_CHOICE, 94d2i_OSSL_ALLOWED_ATTRIBUTES_ITEM, 95d2i_OSSL_ALLOWED_ATTRIBUTES_SYNTAX, 96d2i_OSSL_ATAV, 97d2i_OSSL_ATTRIBUTE_DESCRIPTOR, 98d2i_OSSL_ATTRIBUTE_MAPPING, 99d2i_OSSL_ATTRIBUTE_MAPPINGS, 100d2i_OSSL_ATTRIBUTE_TYPE_MAPPING, 101d2i_OSSL_ATTRIBUTE_VALUE_MAPPING, 102d2i_OSSL_ATTRIBUTES_SYNTAX, 103d2i_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX, 104d2i_OSSL_BASIC_ATTR_CONSTRAINTS, 105d2i_OSSL_CMP_ATAVS, 106d2i_OSSL_CMP_MSG, 107d2i_OSSL_CMP_PKIHEADER, 108d2i_OSSL_CMP_PKISI, 109d2i_OSSL_CRMF_CERTID, 110d2i_OSSL_CRMF_CERTTEMPLATE, 111d2i_OSSL_CRMF_ENCRYPTEDKEY, 112d2i_OSSL_CRMF_ENCRYPTEDVALUE, 113d2i_OSSL_CRMF_MSG, 114d2i_OSSL_CRMF_MSGS, 115d2i_OSSL_CRMF_PBMPARAMETER, 116d2i_OSSL_CRMF_PKIPUBLICATIONINFO, 117d2i_OSSL_CRMF_SINGLEPUBINFO, 118d2i_OSSL_DAY_TIME, 119d2i_OSSL_DAY_TIME_BAND, 120d2i_OSSL_HASH, 121d2i_OSSL_IETF_ATTR_SYNTAX, 122d2i_OSSL_INFO_SYNTAX, 123d2i_OSSL_INFO_SYNTAX_POINTER, 124d2i_OSSL_ISSUER_SERIAL, 125d2i_OSSL_NAMED_DAY, 126d2i_OSSL_OBJECT_DIGEST_INFO, 127d2i_OSSL_PRIVILEGE_POLICY_ID, 128d2i_OSSL_ROLE_SPEC_CERT_ID, 129d2i_OSSL_ROLE_SPEC_CERT_ID_SYNTAX, 130d2i_OSSL_TARGET_CERT, 131d2i_OSSL_TARGET, 132d2i_OSSL_TARGETING_INFORMATION, 133d2i_OSSL_TARGETS, 134d2i_OSSL_TIME_PERIOD, 135d2i_OSSL_TIME_SPEC, 136d2i_OSSL_TIME_SPEC_ABSOLUTE, 137d2i_OSSL_TIME_SPEC_DAY, 138d2i_OSSL_TIME_SPEC_MONTH, 139d2i_OSSL_TIME_SPEC_TIME, 140d2i_OSSL_TIME_SPEC_WEEKS, 141d2i_OSSL_TIME_SPEC_X_DAY_OF, 142d2i_OSSL_USER_NOTICE_SYNTAX, 143d2i_OTHERNAME, 144d2i_PBE2PARAM, 145d2i_PBEPARAM, 146d2i_PBKDF2PARAM, 147d2i_PBMAC1PARAM, 148d2i_PKCS12, 149d2i_PKCS12_BAGS, 150d2i_PKCS12_MAC_DATA, 151d2i_PKCS12_SAFEBAG, 152d2i_PKCS12_bio, 153d2i_PKCS12_fp, 154d2i_PKCS7, 155d2i_PKCS7_DIGEST, 156d2i_PKCS7_ENCRYPT, 157d2i_PKCS7_ENC_CONTENT, 158d2i_PKCS7_ENVELOPE, 159d2i_PKCS7_ISSUER_AND_SERIAL, 160d2i_PKCS7_RECIP_INFO, 161d2i_PKCS7_SIGNED, 162d2i_PKCS7_SIGNER_INFO, 163d2i_PKCS7_SIGN_ENVELOPE, 164d2i_PKCS7_bio, 165d2i_PKCS7_fp, 166d2i_PKCS8_PRIV_KEY_INFO, 167d2i_PKCS8_PRIV_KEY_INFO_bio, 168d2i_PKCS8_PRIV_KEY_INFO_fp, 169d2i_PKCS8_bio, 170d2i_PKCS8_fp, 171d2i_PKEY_USAGE_PERIOD, 172d2i_POLICYINFO, 173d2i_POLICYQUALINFO, 174d2i_PROFESSION_INFO, 175d2i_PROXY_CERT_INFO_EXTENSION, 176d2i_PROXY_POLICY, 177d2i_RSA_OAEP_PARAMS, 178d2i_RSA_PSS_PARAMS, 179d2i_SCRYPT_PARAMS, 180d2i_SCT_LIST, 181d2i_SXNET, 182d2i_SXNETID, 183d2i_TS_ACCURACY, 184d2i_TS_MSG_IMPRINT, 185d2i_TS_MSG_IMPRINT_bio, 186d2i_TS_MSG_IMPRINT_fp, 187d2i_TS_REQ, 188d2i_TS_REQ_bio, 189d2i_TS_REQ_fp, 190d2i_TS_RESP, 191d2i_TS_RESP_bio, 192d2i_TS_RESP_fp, 193d2i_TS_STATUS_INFO, 194d2i_TS_TST_INFO, 195d2i_TS_TST_INFO_bio, 196d2i_TS_TST_INFO_fp, 197d2i_USERNOTICE, 198d2i_X509, 199d2i_X509_bio, 200d2i_X509_fp, 201d2i_X509_ACERT, 202d2i_X509_ACERT_bio, 203d2i_X509_ACERT_fp, 204d2i_X509_ALGOR, 205d2i_X509_ALGORS, 206d2i_X509_ATTRIBUTE, 207d2i_X509_CERT_AUX, 208d2i_X509_CINF, 209d2i_X509_CRL, 210d2i_X509_CRL_INFO, 211d2i_X509_CRL_bio, 212d2i_X509_CRL_fp, 213d2i_X509_EXTENSION, 214d2i_X509_EXTENSIONS, 215d2i_X509_NAME, 216d2i_X509_NAME_ENTRY, 217d2i_X509_PUBKEY, 218d2i_X509_PUBKEY_bio, 219d2i_X509_PUBKEY_fp, 220d2i_X509_REQ, 221d2i_X509_REQ_INFO, 222d2i_X509_REQ_bio, 223d2i_X509_REQ_fp, 224d2i_X509_REVOKED, 225d2i_X509_SIG, 226d2i_X509_VAL, 227i2d_ACCESS_DESCRIPTION, 228i2d_ADMISSIONS, 229i2d_ADMISSION_SYNTAX, 230i2d_ASIdOrRange, 231i2d_ASIdentifierChoice, 232i2d_ASIdentifiers, 233i2d_ASN1_BIT_STRING, 234i2d_ASN1_BMPSTRING, 235i2d_ASN1_ENUMERATED, 236i2d_ASN1_GENERALIZEDTIME, 237i2d_ASN1_GENERALSTRING, 238i2d_ASN1_IA5STRING, 239i2d_ASN1_INTEGER, 240i2d_ASN1_NULL, 241i2d_ASN1_OBJECT, 242i2d_ASN1_OCTET_STRING, 243i2d_ASN1_PRINTABLE, 244i2d_ASN1_PRINTABLESTRING, 245i2d_ASN1_SEQUENCE_ANY, 246i2d_ASN1_SET_ANY, 247i2d_ASN1_T61STRING, 248i2d_ASN1_TIME, 249i2d_ASN1_TYPE, 250i2d_ASN1_UNIVERSALSTRING, 251i2d_ASN1_UTCTIME, 252i2d_ASN1_UTF8STRING, 253i2d_ASN1_VISIBLESTRING, 254i2d_ASN1_bio_stream, 255i2d_ASRange, 256i2d_AUTHORITY_INFO_ACCESS, 257i2d_AUTHORITY_KEYID, 258i2d_BASIC_CONSTRAINTS, 259i2d_CERTIFICATEPOLICIES, 260i2d_CMS_ContentInfo, 261i2d_CMS_ReceiptRequest, 262i2d_CMS_bio, 263i2d_CRL_DIST_POINTS, 264i2d_DHxparams, 265i2d_DIRECTORYSTRING, 266i2d_DISPLAYTEXT, 267i2d_DIST_POINT, 268i2d_DIST_POINT_NAME, 269i2d_DSA_SIG, 270i2d_ECDSA_SIG, 271i2d_ECPKParameters, 272i2d_EDIPARTYNAME, 273i2d_ESS_CERT_ID, 274i2d_ESS_CERT_ID_V2, 275i2d_ESS_ISSUER_SERIAL, 276i2d_ESS_SIGNING_CERT, 277i2d_ESS_SIGNING_CERT_V2, 278i2d_EXTENDED_KEY_USAGE, 279i2d_GENERAL_NAME, 280i2d_GENERAL_NAMES, 281i2d_IPAddressChoice, 282i2d_IPAddressFamily, 283i2d_IPAddressOrRange, 284i2d_IPAddressRange, 285i2d_ISSUER_SIGN_TOOL, 286i2d_ISSUING_DIST_POINT, 287i2d_NAMING_AUTHORITY, 288i2d_NETSCAPE_CERT_SEQUENCE, 289i2d_NETSCAPE_SPKAC, 290i2d_NETSCAPE_SPKI, 291i2d_NOTICEREF, 292i2d_OCSP_BASICRESP, 293i2d_OCSP_CERTID, 294i2d_OCSP_CERTSTATUS, 295i2d_OCSP_CRLID, 296i2d_OCSP_ONEREQ, 297i2d_OCSP_REQINFO, 298i2d_OCSP_REQUEST, 299i2d_OCSP_RESPBYTES, 300i2d_OCSP_RESPDATA, 301i2d_OCSP_RESPID, 302i2d_OCSP_RESPONSE, 303i2d_OCSP_REVOKEDINFO, 304i2d_OCSP_SERVICELOC, 305i2d_OCSP_SIGNATURE, 306i2d_OCSP_SINGLERESP, 307i2d_OSSL_AA_DIST_POINT, 308i2d_OSSL_ALLOWED_ATTRIBUTES_CHOICE, 309i2d_OSSL_ALLOWED_ATTRIBUTES_ITEM, 310i2d_OSSL_ALLOWED_ATTRIBUTES_SYNTAX, 311i2d_OSSL_ATAV, 312i2d_OSSL_ATTRIBUTE_DESCRIPTOR, 313i2d_OSSL_ATTRIBUTE_MAPPING, 314i2d_OSSL_ATTRIBUTE_MAPPINGS, 315i2d_OSSL_ATTRIBUTE_TYPE_MAPPING, 316i2d_OSSL_ATTRIBUTE_VALUE_MAPPING, 317i2d_OSSL_ATTRIBUTES_SYNTAX, 318i2d_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX, 319i2d_OSSL_BASIC_ATTR_CONSTRAINTS, 320i2d_OSSL_CMP_ATAVS, 321i2d_OSSL_CMP_MSG, 322i2d_OSSL_CMP_PKIHEADER, 323i2d_OSSL_CMP_PKISI, 324i2d_OSSL_CRMF_CERTID, 325i2d_OSSL_CRMF_CERTTEMPLATE, 326i2d_OSSL_CRMF_ENCRYPTEDKEY, 327i2d_OSSL_CRMF_ENCRYPTEDVALUE, 328i2d_OSSL_CRMF_MSG, 329i2d_OSSL_CRMF_MSGS, 330i2d_OSSL_CRMF_PBMPARAMETER, 331i2d_OSSL_CRMF_PKIPUBLICATIONINFO, 332i2d_OSSL_CRMF_SINGLEPUBINFO, 333i2d_OSSL_HASH, 334i2d_OSSL_DAY_TIME, 335i2d_OSSL_DAY_TIME_BAND, 336i2d_OSSL_IETF_ATTR_SYNTAX, 337i2d_OSSL_INFO_SYNTAX, 338i2d_OSSL_INFO_SYNTAX_POINTER, 339i2d_OSSL_ISSUER_SERIAL, 340i2d_OSSL_NAMED_DAY, 341i2d_OSSL_OBJECT_DIGEST_INFO, 342i2d_OSSL_PRIVILEGE_POLICY_ID, 343i2d_OSSL_ROLE_SPEC_CERT_ID, 344i2d_OSSL_ROLE_SPEC_CERT_ID_SYNTAX, 345i2d_OSSL_TARGET_CERT, 346i2d_OSSL_TARGET, 347i2d_OSSL_TARGETING_INFORMATION, 348i2d_OSSL_TARGETS, 349i2d_OSSL_TIME_PERIOD, 350i2d_OSSL_TIME_SPEC, 351i2d_OSSL_TIME_SPEC_ABSOLUTE, 352i2d_OSSL_TIME_SPEC_DAY, 353i2d_OSSL_TIME_SPEC_MONTH, 354i2d_OSSL_TIME_SPEC_TIME, 355i2d_OSSL_TIME_SPEC_WEEKS, 356i2d_OSSL_TIME_SPEC_X_DAY_OF, 357i2d_OSSL_USER_NOTICE_SYNTAX, 358i2d_OTHERNAME, 359i2d_PBE2PARAM, 360i2d_PBEPARAM, 361i2d_PBKDF2PARAM, 362i2d_PBMAC1PARAM, 363i2d_PKCS12, 364i2d_PKCS12_BAGS, 365i2d_PKCS12_MAC_DATA, 366i2d_PKCS12_SAFEBAG, 367i2d_PKCS12_bio, 368i2d_PKCS12_fp, 369i2d_PKCS7, 370i2d_PKCS7_DIGEST, 371i2d_PKCS7_ENCRYPT, 372i2d_PKCS7_ENC_CONTENT, 373i2d_PKCS7_ENVELOPE, 374i2d_PKCS7_ISSUER_AND_SERIAL, 375i2d_PKCS7_NDEF, 376i2d_PKCS7_RECIP_INFO, 377i2d_PKCS7_SIGNED, 378i2d_PKCS7_SIGNER_INFO, 379i2d_PKCS7_SIGN_ENVELOPE, 380i2d_PKCS7_bio, 381i2d_PKCS7_fp, 382i2d_PKCS8PrivateKeyInfo_bio, 383i2d_PKCS8PrivateKeyInfo_fp, 384i2d_PKCS8_PRIV_KEY_INFO, 385i2d_PKCS8_PRIV_KEY_INFO_bio, 386i2d_PKCS8_PRIV_KEY_INFO_fp, 387i2d_PKCS8_bio, 388i2d_PKCS8_fp, 389i2d_PKEY_USAGE_PERIOD, 390i2d_POLICYINFO, 391i2d_POLICYQUALINFO, 392i2d_PROFESSION_INFO, 393i2d_PROXY_CERT_INFO_EXTENSION, 394i2d_PROXY_POLICY, 395i2d_RSA_OAEP_PARAMS, 396i2d_RSA_PSS_PARAMS, 397i2d_SCRYPT_PARAMS, 398i2d_SCT_LIST, 399i2d_SXNET, 400i2d_SXNETID, 401i2d_TS_ACCURACY, 402i2d_TS_MSG_IMPRINT, 403i2d_TS_MSG_IMPRINT_bio, 404i2d_TS_MSG_IMPRINT_fp, 405i2d_TS_REQ, 406i2d_TS_REQ_bio, 407i2d_TS_REQ_fp, 408i2d_TS_RESP, 409i2d_TS_RESP_bio, 410i2d_TS_RESP_fp, 411i2d_TS_STATUS_INFO, 412i2d_TS_TST_INFO, 413i2d_TS_TST_INFO_bio, 414i2d_TS_TST_INFO_fp, 415i2d_USERNOTICE, 416i2d_X509, 417i2d_X509_bio, 418i2d_X509_fp, 419i2d_X509_ACERT, 420i2d_X509_ACERT_bio, 421i2d_X509_ACERT_fp, 422i2d_X509_ALGOR, 423i2d_X509_ALGORS, 424i2d_X509_ATTRIBUTE, 425i2d_X509_CERT_AUX, 426i2d_X509_CINF, 427i2d_X509_CRL, 428i2d_X509_CRL_INFO, 429i2d_X509_CRL_bio, 430i2d_X509_CRL_fp, 431i2d_X509_EXTENSION, 432i2d_X509_EXTENSIONS, 433i2d_X509_NAME, 434i2d_X509_NAME_ENTRY, 435i2d_X509_PUBKEY, 436i2d_X509_PUBKEY_bio, 437i2d_X509_PUBKEY_fp, 438i2d_X509_REQ, 439i2d_X509_REQ_INFO, 440i2d_X509_REQ_bio, 441i2d_X509_REQ_fp, 442i2d_X509_REVOKED, 443i2d_X509_SIG, 444i2d_X509_VAL, 445- convert objects from/to ASN.1/DER representation 446 447=head1 SYNOPSIS 448 449=for openssl generic 450 451 TYPE *d2i_TYPE(TYPE **a, const unsigned char **ppin, long length); 452 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); 453 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); 454 455 int i2d_TYPE(const TYPE *a, unsigned char **ppout); 456 int i2d_TYPE(TYPE *a, unsigned char **ppout); 457 int i2d_TYPE_fp(FILE *fp, const TYPE *a); 458 int i2d_TYPE_fp(FILE *fp, TYPE *a); 459 int i2d_TYPE_bio(BIO *bp, const TYPE *a); 460 int i2d_TYPE_bio(BIO *bp, TYPE *a); 461 462=head1 DESCRIPTION 463 464In the description here, B<I<TYPE>> is used a placeholder 465for any of the OpenSSL datatypes, such as B<X509_CRL>. 466The function parameters I<ppin> and I<ppout> are generally 467either both named I<pp> in the headers, or I<in> and I<out>. 468 469These functions convert OpenSSL objects to and from their ASN.1/DER 470encoding. Unlike the C structures which can have pointers to sub-objects 471within, the DER is a serialized encoding, suitable for sending over the 472network, writing to a file, and so on. 473 474B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a 475pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to 476the byte following the parsed data. If I<a> is not NULL then a pointer 477to the returned structure is also written to I<*a>. If an error occurred 478then NULL is returned. The caller retains ownership of the 479returned object and needs to free it when it is no longer needed, e.g. 480using X509_free() for X509 objects or DSA_SIG_free() for DSA_SIG objects. 481 482On a successful return, if I<*a> is not NULL then it is assumed that I<*a> 483contains a valid B<I<TYPE>> structure and an attempt is made to reuse it. 484For B<I<TYPE>> structures where it matters it is possible to set up a library 485context on the decoded structure this way (see the B<EXAMPLES> section). 486However using the "reuse" capability for other purposes is B<strongly 487discouraged> (see B<BUGS> below, and the discussion in the B<RETURN VALUES> 488section). 489 490B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts 491to parse data from BIO I<bp>. 492 493B<d2i_I<TYPE>_fp>() is similar to B<d2i_I<TYPE>>() except it attempts 494to parse data from FILE pointer I<fp>. 495 496B<i2d_I<TYPE>>() encodes the structure pointed to by I<a> into DER format. 497If I<ppout> is not NULL, it writes the DER encoded data to the buffer 498at I<*ppout>, and increments it to point after the data just written. 499If the return value is negative an error occurred, otherwise it 500returns the length of the encoded data. 501 502If I<*ppout> is NULL memory will be allocated for a buffer and the encoded 503data written to it. In this case I<*ppout> is not incremented and it points 504to the start of the data just written. 505 506B<i2d_I<TYPE>_bio>() is similar to B<i2d_I<TYPE>>() except it writes 507the encoding of the structure I<a> to BIO I<bp> and it 508returns 1 for success and 0 for failure. 509 510B<i2d_I<TYPE>_fp>() is similar to B<i2d_I<TYPE>>() except it writes 511the encoding of the structure I<a> to FILE pointer I<fp> and it 512returns 1 for success and 0 for failure. 513 514These routines do not encrypt private keys and therefore offer no 515security; use L<PEM_write_PrivateKey(3)> or similar for writing to files. 516 517=head1 NOTES 518 519The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for 520"internal" (that is, an internal C structure) and "DER" respectively. 521So B<i2d_I<TYPE>>() converts from internal to DER. 522 523The functions can also understand B<BER> forms. 524 525The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid 526populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an 527empty structure such as that returned by TYPE_new(). 528 529The encoded data is in binary form and may contain embedded zeros. 530Therefore, any FILE pointers or BIOs should be opened in binary mode. 531Functions such as strlen() will B<not> return the correct length 532of the encoded structure. 533 534The ways that I<*ppin> and I<*ppout> are incremented after the operation 535can trap the unwary. See the B<WARNINGS> section for some common 536errors. 537The reason for this-auto increment behaviour is to reflect a typical 538usage of ASN1 functions: after one structure is encoded or decoded 539another will be processed after it. 540 541The following points about the data types might be useful: 542 543=over 4 544 545=item B<ASN1_OBJECT> 546 547Represents an ASN1 OBJECT IDENTIFIER. 548 549=item B<DHparams> 550 551Represents a PKCS#3 DH parameters structure. 552 553=item B<DHxparams> 554 555Represents an ANSI X9.42 DH parameters structure. 556 557=item B<ECDSA_SIG> 558 559Represents an ECDSA signature. 560 561=item B<X509_ALGOR> 562 563Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and 564elsewhere. 565 566=item B<X509_NAME> 567 568Represents a B<Name> type as used for subject and issuer names in 569IETF RFC 6960 and elsewhere. 570 571=item B<X509_REQ> 572 573Represents a PKCS#10 certificate request. 574 575=item B<X509_SIG> 576 577Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7. 578 579=back 580 581=head1 RETURN VALUES 582 583B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid 584B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has 585been used with a valid structure being passed in via I<a>, then the object is 586freed in the event of error and I<*a> is set to NULL. 587 588B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative 589value if an error occurs. 590 591B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>(), 592as well as i2d_ASN1_bio_stream(), 593return 1 for success and 0 if an error occurs. 594 595=head1 EXAMPLES 596 597Allocate and encode the DER encoding of an X509 structure: 598 599 int len; 600 unsigned char *buf; 601 602 buf = NULL; 603 len = i2d_X509(x, &buf); 604 if (len < 0) 605 /* error */ 606 607Attempt to decode a buffer: 608 609 X509 *x; 610 unsigned char *buf; 611 const unsigned char *p; 612 int len; 613 614 /* Set up buf and len to point to the input buffer. */ 615 p = buf; 616 x = d2i_X509(NULL, &p, len); 617 if (x == NULL) 618 /* error */ 619 620Alternative technique: 621 622 X509 *x; 623 unsigned char *buf; 624 const unsigned char *p; 625 int len; 626 627 /* Set up buf and len to point to the input buffer. */ 628 p = buf; 629 x = NULL; 630 631 if (d2i_X509(&x, &p, len) == NULL) 632 /* error */ 633 634Setting up a library context and property query: 635 636 X509 *x; 637 unsigned char *buf; 638 const unsigned char *p; 639 int len; 640 OSSL_LIB_CTX *libctx = ....; 641 const char *propq = ....; 642 643 /* Set up buf and len to point to the input buffer. */ 644 p = buf; 645 x = X509_new_ex(libctx, propq); 646 647 if (d2i_X509(&x, &p, len) == NULL) 648 /* error, x was freed and NULL assigned to it (see RETURN VALUES) */ 649 650=head1 WARNINGS 651 652Using a temporary variable is mandatory. A common 653mistake is to attempt to use a buffer directly as follows: 654 655 int len; 656 unsigned char *buf; 657 658 len = i2d_X509(x, NULL); 659 buf = OPENSSL_malloc(len); 660 ... 661 i2d_X509(x, &buf); 662 ... 663 OPENSSL_free(buf); 664 665This code will result in I<buf> apparently containing garbage because 666it was incremented after the call to point after the data just written. 667Also I<buf> will no longer contain the pointer allocated by OPENSSL_malloc() 668and the subsequent call to OPENSSL_free() is likely to crash. 669 670Another trap to avoid is misuse of the I<a> argument to B<d2i_I<TYPE>>(): 671 672 X509 *x; 673 674 if (d2i_X509(&x, &p, len) == NULL) 675 /* error */ 676 677This will probably crash somewhere in d2i_X509(). The reason for this 678is that the variable I<x> is uninitialized and an attempt will be made to 679interpret its (invalid) value as an B<X509> structure, typically causing 680a segmentation violation. If I<x> is set to NULL first then this will not 681happen. 682 683=head1 BUGS 684 685In some versions of OpenSSL the "reuse" behaviour of B<d2i_I<TYPE>>() when 686I<*a> is valid is broken and some parts of the reused structure may 687persist if they are not present in the new one. Additionally, in versions of 688OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs 689the behaviour is inconsistent. Some functions behaved as described here, while 690some did not free I<*a> on error and did not set I<*a> to NULL. 691 692As a result of the above issues the "reuse" behaviour is strongly discouraged. 693 694B<i2d_I<TYPE>>() will not return an error in many versions of OpenSSL, 695if mandatory fields are not initialized due to a programming error 696then the encoded structure may contain invalid data or omit the 697fields entirely and will not be parsed by B<d2i_I<TYPE>>(). This may be 698fixed in future so code should not assume that B<i2d_I<TYPE>>() will 699always succeed. 700 701Any function which encodes a structure (B<i2d_I<TYPE>>(), 702B<i2d_I<TYPE>_bio>() or B<i2d_I<TYPE>_fp>()) may return a stale encoding if the 703structure has been modified after deserialization or previous 704serialization. This is because some objects cache the encoding for 705efficiency reasons. 706 707=head1 HISTORY 708 709d2i_OSSL_ATTRIBUTES_SYNTAX(), d2i_OSSL_BASIC_ATTR_CONSTRAINTS(), 710d2i_OSSL_CMP_ATAVS(), d2i_OSSL_IETF_ATTR_SYNTAX(), 711d2i_OSSL_TARGET(), d2i_OSSL_TARGETING_INFORMATION(), 712d2i_OSSL_TARGETS(), d2i_OSSL_USER_NOTICE_SYNTAX(), 713d2i_PBMAC1PARAM(), d2i_X509_ACERT(), d2i_X509_ACERT_bio(), 714d2i_X509_ACERT_fp(), i2d_OSSL_ATTRIBUTES_SYNTAX(), 715i2d_OSSL_BASIC_ATTR_CONSTRAINTS(), i2d_OSSL_CMP_ATAVS(), 716i2d_OSSL_IETF_ATTR_SYNTAX(), i2d_OSSL_TARGET(), 717i2d_OSSL_TARGETING_INFORMATION(), i2d_OSSL_TARGETS(), 718i2d_OSSL_USER_NOTICE_SYNTAX(), i2d_PBMAC1PARAM(), i2d_X509_ACERT(), 719i2d_X509_ACERT_bio(), i2d_X509_ACERT_fp() 720were added in OpenSSL 3.4. 721 722d2i_OSSL_AA_DIST_POINT(), 723d2i_OSSL_ALLOWED_ATTRIBUTES_CHOICE(), d2i_OSSL_ALLOWED_ATTRIBUTES_ITEM(), 724d2i_OSSL_ALLOWED_ATTRIBUTES_SYNTAX(), 725d2i_OSSL_ATAV(), d2i_OSSL_ATTRIBUTE_DESCRIPTOR(), d2i_OSSL_ATTRIBUTE_MAPPING(), 726d2i_OSSL_ATTRIBUTE_MAPPINGS(), d2i_OSSL_ATTRIBUTE_TYPE_MAPPING(), 727d2i_OSSL_ATTRIBUTE_VALUE_MAPPING(), d2i_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX(), 728d2i_OSSL_HASH(), d2i_OSSL_INFO_SYNTAX(), 729d2i_OSSL_INFO_SYNTAX_POINTER(), d2i_OSSL_PRIVILEGE_POLICY_ID(), 730d2i_OSSL_ROLE_SPEC_CERT_ID(), d2i_OSSL_ROLE_SPEC_CERT_ID_SYNTAX(), 731i2d_OSSL_AA_DIST_POINT(), 732i2d_OSSL_ALLOWED_ATTRIBUTES_CHOICE(), i2d_OSSL_ALLOWED_ATTRIBUTES_ITEM(), 733i2d_OSSL_ALLOWED_ATTRIBUTES_SYNTAX(), 734i2d_OSSL_ATAV(), i2d_OSSL_ATTRIBUTE_DESCRIPTOR(), i2d_OSSL_ATTRIBUTE_MAPPING(), 735i2d_OSSL_ATTRIBUTE_MAPPINGS(), i2d_OSSL_ATTRIBUTE_TYPE_MAPPING(), 736i2d_OSSL_ATTRIBUTE_VALUE_MAPPING(), i2d_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX(), 737i2d_OSSL_HASH(), i2d_OSSL_INFO_SYNTAX(), 738i2d_OSSL_INFO_SYNTAX_POINTER(), i2d_OSSL_PRIVILEGE_POLICY_ID(), 739i2d_OSSL_ROLE_SPEC_CERT_ID(), i2d_OSSL_ROLE_SPEC_CERT_ID_SYNTAX(), 740d2i_OSSL_CRMF_ENCRYPTEDKEY(), i2d_OSSL_CRMF_ENCRYPTEDKEY(), 741d2i_OSSL_DAY_TIME(), d2i_OSSL_DAY_TIME_BAND(), d2i_OSSL_NAMED_DAY(), 742d2i_OSSL_TIME_PERIOD(), d2i_OSSL_TIME_SPEC(), 743d2i_OSSL_TIME_SPEC_ABSOLUTE(), d2i_OSSL_TIME_SPEC_DAY(), 744d2i_OSSL_TIME_SPEC_MONTH(), d2i_OSSL_TIME_SPEC_TIME(), 745d2i_OSSL_TIME_SPEC_WEEKS(), d2i_OSSL_TIME_SPEC_X_DAY_OF(), 746i2d_OSSL_DAY_TIME(), i2d_OSSL_DAY_TIME_BAND(), 747i2d_OSSL_NAMED_DAY(), i2d_OSSL_TIME_PERIOD(), 748i2d_OSSL_TIME_SPEC(), i2d_OSSL_TIME_SPEC_ABSOLUTE(), 749i2d_OSSL_TIME_SPEC_DAY(), i2d_OSSL_TIME_SPEC_MONTH(), 750i2d_OSSL_TIME_SPEC_TIME(), i2d_OSSL_TIME_SPEC_WEEKS(), 751i2d_OSSL_TIME_SPEC_X_DAY_OF() 752were added in OpenSSL 3.5. 753 754=head1 COPYRIGHT 755 756Copyright 1998-2025 The OpenSSL Project Authors. All Rights Reserved. 757 758Licensed under the Apache License 2.0 (the "License"). You may not use 759this file except in compliance with the License. You can obtain a copy 760in the file LICENSE in the source distribution or at 761L<https://www.openssl.org/source/license.html>. 762 763=cut 764