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