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