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>() return 1 for success and 0 if an 592error occurs. 593 594=head1 EXAMPLES 595 596Allocate and encode the DER encoding of an X509 structure: 597 598 int len; 599 unsigned char *buf; 600 601 buf = NULL; 602 len = i2d_X509(x, &buf); 603 if (len < 0) 604 /* error */ 605 606Attempt to decode a buffer: 607 608 X509 *x; 609 unsigned char *buf; 610 const unsigned char *p; 611 int len; 612 613 /* Set up buf and len to point to the input buffer. */ 614 p = buf; 615 x = d2i_X509(NULL, &p, len); 616 if (x == NULL) 617 /* error */ 618 619Alternative technique: 620 621 X509 *x; 622 unsigned char *buf; 623 const unsigned char *p; 624 int len; 625 626 /* Set up buf and len to point to the input buffer. */ 627 p = buf; 628 x = NULL; 629 630 if (d2i_X509(&x, &p, len) == NULL) 631 /* error */ 632 633Setting up a library context and property query: 634 635 X509 *x; 636 unsigned char *buf; 637 const unsigned char *p; 638 int len; 639 OSSL_LIB_CTX *libctx = ....; 640 const char *propq = ....; 641 642 /* Set up buf and len to point to the input buffer. */ 643 p = buf; 644 x = X509_new_ex(libctx, propq); 645 646 if (d2i_X509(&x, &p, len) == NULL) 647 /* error, x was freed and NULL assigned to it (see RETURN VALUES) */ 648 649=head1 WARNINGS 650 651Using a temporary variable is mandatory. A common 652mistake is to attempt to use a buffer directly as follows: 653 654 int len; 655 unsigned char *buf; 656 657 len = i2d_X509(x, NULL); 658 buf = OPENSSL_malloc(len); 659 ... 660 i2d_X509(x, &buf); 661 ... 662 OPENSSL_free(buf); 663 664This code will result in I<buf> apparently containing garbage because 665it was incremented after the call to point after the data just written. 666Also I<buf> will no longer contain the pointer allocated by OPENSSL_malloc() 667and the subsequent call to OPENSSL_free() is likely to crash. 668 669Another trap to avoid is misuse of the I<a> argument to B<d2i_I<TYPE>>(): 670 671 X509 *x; 672 673 if (d2i_X509(&x, &p, len) == NULL) 674 /* error */ 675 676This will probably crash somewhere in d2i_X509(). The reason for this 677is that the variable I<x> is uninitialized and an attempt will be made to 678interpret its (invalid) value as an B<X509> structure, typically causing 679a segmentation violation. If I<x> is set to NULL first then this will not 680happen. 681 682=head1 BUGS 683 684In some versions of OpenSSL the "reuse" behaviour of B<d2i_I<TYPE>>() when 685I<*a> is valid is broken and some parts of the reused structure may 686persist if they are not present in the new one. Additionally, in versions of 687OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs 688the behaviour is inconsistent. Some functions behaved as described here, while 689some did not free I<*a> on error and did not set I<*a> to NULL. 690 691As a result of the above issues the "reuse" behaviour is strongly discouraged. 692 693B<i2d_I<TYPE>>() will not return an error in many versions of OpenSSL, 694if mandatory fields are not initialized due to a programming error 695then the encoded structure may contain invalid data or omit the 696fields entirely and will not be parsed by B<d2i_I<TYPE>>(). This may be 697fixed in future so code should not assume that B<i2d_I<TYPE>>() will 698always succeed. 699 700Any function which encodes a structure (B<i2d_I<TYPE>>(), 701B<i2d_I<TYPE>_bio>() or B<i2d_I<TYPE>_fp>()) may return a stale encoding if the 702structure has been modified after deserialization or previous 703serialization. This is because some objects cache the encoding for 704efficiency reasons. 705 706=head1 HISTORY 707 708d2i_OSSL_ATTRIBUTES_SYNTAX(), d2i_OSSL_BASIC_ATTR_CONSTRAINTS(), 709d2i_OSSL_CMP_ATAVS(), d2i_OSSL_IETF_ATTR_SYNTAX(), 710d2i_OSSL_TARGET(), d2i_OSSL_TARGETING_INFORMATION(), 711d2i_OSSL_TARGETS(), d2i_OSSL_USER_NOTICE_SYNTAX(), 712d2i_PBMAC1PARAM(), d2i_X509_ACERT(), d2i_X509_ACERT_bio(), 713d2i_X509_ACERT_fp(), i2d_OSSL_ATTRIBUTES_SYNTAX(), 714i2d_OSSL_BASIC_ATTR_CONSTRAINTS(), i2d_OSSL_CMP_ATAVS(), 715i2d_OSSL_IETF_ATTR_SYNTAX(), i2d_OSSL_TARGET(), 716i2d_OSSL_TARGETING_INFORMATION(), i2d_OSSL_TARGETS(), 717i2d_OSSL_USER_NOTICE_SYNTAX(), i2d_PBMAC1PARAM(), i2d_X509_ACERT(), 718i2d_X509_ACERT_bio(), i2d_X509_ACERT_fp() 719were added in OpenSSL 3.4. 720 721d2i_OSSL_AA_DIST_POINT(), 722d2i_OSSL_ALLOWED_ATTRIBUTES_CHOICE(), d2i_OSSL_ALLOWED_ATTRIBUTES_ITEM(), 723d2i_OSSL_ALLOWED_ATTRIBUTES_SYNTAX(), 724d2i_OSSL_ATAV(), d2i_OSSL_ATTRIBUTE_DESCRIPTOR(), d2i_OSSL_ATTRIBUTE_MAPPING(), 725d2i_OSSL_ATTRIBUTE_MAPPINGS(), d2i_OSSL_ATTRIBUTE_TYPE_MAPPING(), 726d2i_OSSL_ATTRIBUTE_VALUE_MAPPING(), d2i_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX(), 727d2i_OSSL_HASH(), d2i_OSSL_INFO_SYNTAX(), 728d2i_OSSL_INFO_SYNTAX_POINTER(), d2i_OSSL_PRIVILEGE_POLICY_ID(), 729d2i_OSSL_ROLE_SPEC_CERT_ID(), d2i_OSSL_ROLE_SPEC_CERT_ID_SYNTAX(), 730i2d_OSSL_AA_DIST_POINT(), 731i2d_OSSL_ALLOWED_ATTRIBUTES_CHOICE(), i2d_OSSL_ALLOWED_ATTRIBUTES_ITEM(), 732i2d_OSSL_ALLOWED_ATTRIBUTES_SYNTAX(), 733i2d_OSSL_ATAV(), i2d_OSSL_ATTRIBUTE_DESCRIPTOR(), i2d_OSSL_ATTRIBUTE_MAPPING(), 734i2d_OSSL_ATTRIBUTE_MAPPINGS(), i2d_OSSL_ATTRIBUTE_TYPE_MAPPING(), 735i2d_OSSL_ATTRIBUTE_VALUE_MAPPING(), i2d_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX(), 736i2d_OSSL_HASH(), i2d_OSSL_INFO_SYNTAX(), 737i2d_OSSL_INFO_SYNTAX_POINTER(), i2d_OSSL_PRIVILEGE_POLICY_ID(), 738i2d_OSSL_ROLE_SPEC_CERT_ID(), i2d_OSSL_ROLE_SPEC_CERT_ID_SYNTAX(), 739d2i_OSSL_CRMF_ENCRYPTEDKEY(), i2d_OSSL_CRMF_ENCRYPTEDKEY(), 740d2i_OSSL_DAY_TIME(), d2i_OSSL_DAY_TIME_BAND(), d2i_OSSL_NAMED_DAY(), 741d2i_OSSL_TIME_PERIOD(), d2i_OSSL_TIME_SPEC(), 742d2i_OSSL_TIME_SPEC_ABSOLUTE(), d2i_OSSL_TIME_SPEC_DAY(), 743d2i_OSSL_TIME_SPEC_MONTH(), d2i_OSSL_TIME_SPEC_TIME(), 744d2i_OSSL_TIME_SPEC_WEEKS(), d2i_OSSL_TIME_SPEC_X_DAY_OF(), 745i2d_OSSL_DAY_TIME(), i2d_OSSL_DAY_TIME_BAND(), 746i2d_OSSL_NAMED_DAY(), i2d_OSSL_TIME_PERIOD(), 747i2d_OSSL_TIME_SPEC(), i2d_OSSL_TIME_SPEC_ABSOLUTE(), 748i2d_OSSL_TIME_SPEC_DAY(), i2d_OSSL_TIME_SPEC_MONTH(), 749i2d_OSSL_TIME_SPEC_TIME(), i2d_OSSL_TIME_SPEC_WEEKS(), 750i2d_OSSL_TIME_SPEC_X_DAY_OF() 751were added in OpenSSL 3.5. 752 753=head1 COPYRIGHT 754 755Copyright 1998-2025 The OpenSSL Project Authors. All Rights Reserved. 756 757Licensed under the Apache License 2.0 (the "License"). You may not use 758this file except in compliance with the License. You can obtain a copy 759in the file LICENSE in the source distribution or at 760L<https://www.openssl.org/source/license.html>. 761 762=cut 763