5 d2i_ACCESS_DESCRIPTION,
9 d2i_ASIdentifierChoice,
14 d2i_ASN1_GENERALIZEDTIME,
15 d2i_ASN1_GENERALSTRING,
20 d2i_ASN1_OCTET_STRING,
22 d2i_ASN1_PRINTABLESTRING,
23 d2i_ASN1_SEQUENCE_ANY,
29 d2i_ASN1_UNIVERSALSTRING,
32 d2i_ASN1_VISIBLESTRING,
34 d2i_AUTHORITY_INFO_ACCESS,
36 d2i_BASIC_CONSTRAINTS,
37 d2i_CERTIFICATEPOLICIES,
39 d2i_CMS_ReceiptRequest,
48 d2i_DSAPrivateKey_bio,
68 d2i_ESS_ISSUER_SERIAL,
70 d2i_ESS_SIGNING_CERT_V2,
71 d2i_EXTENDED_KEY_USAGE,
78 d2i_ISSUING_DIST_POINT,
80 d2i_NETSCAPE_CERT_SEQUENCE,
100 d2i_OSSL_CMP_PKIHEADER,
102 d2i_OSSL_CRMF_CERTID,
103 d2i_OSSL_CRMF_CERTTEMPLATE,
104 d2i_OSSL_CRMF_ENCRYPTEDVALUE,
107 d2i_OSSL_CRMF_PBMPARAMETER,
108 d2i_OSSL_CRMF_PKIPUBLICATIONINFO,
109 d2i_OSSL_CRMF_SINGLEPUBINFO,
123 d2i_PKCS7_ENC_CONTENT,
125 d2i_PKCS7_ISSUER_AND_SERIAL,
126 d2i_PKCS7_RECIP_INFO,
128 d2i_PKCS7_SIGNER_INFO,
129 d2i_PKCS7_SIGN_ENVELOPE,
132 d2i_PKCS8_PRIV_KEY_INFO,
133 d2i_PKCS8_PRIV_KEY_INFO_bio,
134 d2i_PKCS8_PRIV_KEY_INFO_fp,
137 d2i_PKEY_USAGE_PERIOD,
141 d2i_PROXY_CERT_INFO_EXTENSION,
144 d2i_RSAPrivateKey_bio,
145 d2i_RSAPrivateKey_fp,
147 d2i_RSAPublicKey_bio,
160 d2i_TS_MSG_IMPRINT_bio,
161 d2i_TS_MSG_IMPRINT_fp,
197 i2d_ACCESS_DESCRIPTION,
199 i2d_ADMISSION_SYNTAX,
201 i2d_ASIdentifierChoice,
206 i2d_ASN1_GENERALIZEDTIME,
207 i2d_ASN1_GENERALSTRING,
212 i2d_ASN1_OCTET_STRING,
214 i2d_ASN1_PRINTABLESTRING,
215 i2d_ASN1_SEQUENCE_ANY,
220 i2d_ASN1_UNIVERSALSTRING,
223 i2d_ASN1_VISIBLESTRING,
226 i2d_AUTHORITY_INFO_ACCESS,
228 i2d_BASIC_CONSTRAINTS,
229 i2d_CERTIFICATEPOLICIES,
231 i2d_CMS_ReceiptRequest,
240 i2d_DSAPrivateKey_bio,
241 i2d_DSAPrivateKey_fp,
252 i2d_ECPrivateKey_bio,
260 i2d_ESS_ISSUER_SERIAL,
261 i2d_ESS_SIGNING_CERT,
262 i2d_ESS_SIGNING_CERT_V2,
263 i2d_EXTENDED_KEY_USAGE,
268 i2d_IPAddressOrRange,
270 i2d_ISSUING_DIST_POINT,
271 i2d_NAMING_AUTHORITY,
272 i2d_NETSCAPE_CERT_SEQUENCE,
287 i2d_OCSP_REVOKEDINFO,
292 i2d_OSSL_CMP_PKIHEADER,
294 i2d_OSSL_CRMF_CERTID,
295 i2d_OSSL_CRMF_CERTTEMPLATE,
296 i2d_OSSL_CRMF_ENCRYPTEDVALUE,
299 i2d_OSSL_CRMF_PBMPARAMETER,
300 i2d_OSSL_CRMF_PKIPUBLICATIONINFO,
301 i2d_OSSL_CRMF_SINGLEPUBINFO,
315 i2d_PKCS7_ENC_CONTENT,
317 i2d_PKCS7_ISSUER_AND_SERIAL,
319 i2d_PKCS7_RECIP_INFO,
321 i2d_PKCS7_SIGNER_INFO,
322 i2d_PKCS7_SIGN_ENVELOPE,
325 i2d_PKCS8PrivateKeyInfo_bio,
326 i2d_PKCS8PrivateKeyInfo_fp,
327 i2d_PKCS8_PRIV_KEY_INFO,
328 i2d_PKCS8_PRIV_KEY_INFO_bio,
329 i2d_PKCS8_PRIV_KEY_INFO_fp,
332 i2d_PKEY_USAGE_PERIOD,
336 i2d_PROXY_CERT_INFO_EXTENSION,
339 i2d_RSAPrivateKey_bio,
340 i2d_RSAPrivateKey_fp,
342 i2d_RSAPublicKey_bio,
355 i2d_TS_MSG_IMPRINT_bio,
356 i2d_TS_MSG_IMPRINT_fp,
392 - convert objects from/to ASN.1/DER representation
398 TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length);
399 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
400 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
402 int i2d_TYPE(const TYPE *a, unsigned char **ppout);
403 int i2d_TYPE(TYPE *a, unsigned char **ppout);
404 int i2d_TYPE_fp(FILE *fp, const TYPE *a);
405 int i2d_TYPE_fp(FILE *fp, TYPE *a);
406 int i2d_TYPE_bio(BIO *bp, const TYPE *a);
407 int i2d_TYPE_bio(BIO *bp, TYPE *a);
411 In the description here, B<I<TYPE>> is used a placeholder
412 for any of the OpenSSL datatypes, such as I<X509_CRL>.
413 The function parameters I<ppin> and I<ppout> are generally
414 either both named I<pp> in the headers, or I<in> and I<out>.
416 These functions convert OpenSSL objects to and from their ASN.1/DER
417 encoding. Unlike the C structures which can have pointers to sub-objects
418 within, the DER is a serialized encoding, suitable for sending over the
419 network, writing to a file, and so on.
421 B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a
422 pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to
423 the byte following the parsed data. If I<a> is not NULL then a pointer
424 to the returned structure is also written to I<*a>. If an error occurred
425 then NULL is returned.
427 On a successful return, if I<*a> is not NULL then it is assumed that I<*a>
428 contains a valid B<I<TYPE>> structure and an attempt is made to reuse it. This
429 "reuse" capability is present for historical compatibility but its use is
430 B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
433 B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts
434 to parse data from BIO I<bp>.
436 B<d2i_I<TYPE>_fp>() is similar to B<d2i_I<TYPE>>() except it attempts
437 to parse data from FILE pointer I<fp>.
439 B<i2d_I<TYPE>>() encodes the structure pointed to by I<a> into DER format.
440 If I<ppout> is not NULL, it writes the DER encoded data to the buffer
441 at I<*ppout>, and increments it to point after the data just written.
442 If the return value is negative an error occurred, otherwise it
443 returns the length of the encoded data.
445 If I<*ppout> is NULL memory will be allocated for a buffer and the encoded
446 data written to it. In this case I<*ppout> is not incremented and it points
447 to the start of the data just written.
449 B<i2d_I<TYPE>_bio>() is similar to B<i2d_I<TYPE>>() except it writes
450 the encoding of the structure I<a> to BIO I<bp> and it
451 returns 1 for success and 0 for failure.
453 B<i2d_I<TYPE>_fp>() is similar to B<i2d_I<TYPE>>() except it writes
454 the encoding of the structure I<a> to BIO I<bp> and it
455 returns 1 for success and 0 for failure.
457 These routines do not encrypt private keys and therefore offer no
458 security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
462 The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
463 "internal" (that is, an internal C structure) and "DER" respectively.
464 So B<i2d_I<TYPE>>() converts from internal to DER.
466 The functions can also understand B<BER> forms.
468 The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
469 populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
470 empty structure such as that returned by TYPE_new().
472 The encoded data is in binary form and may contain embedded zeros.
473 Therefore any FILE pointers or BIOs should be opened in binary mode.
474 Functions such as strlen() will B<not> return the correct length
475 of the encoded structure.
477 The ways that I<*ppin> and I<*ppout> are incremented after the operation
478 can trap the unwary. See the B<WARNINGS> section for some common
480 The reason for this-auto increment behaviour is to reflect a typical
481 usage of ASN1 functions: after one structure is encoded or decoded
482 another will be processed after it.
484 The following points about the data types might be useful:
490 Represents an ASN1 OBJECT IDENTIFIER.
494 Represents a PKCS#3 DH parameters structure.
498 Represents an ANSI X9.42 DH parameters structure.
502 Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
504 =item B<DSAPublicKey>, B<DSAPrivateKey>
506 Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
507 L<PEM_write_PrivateKey(3)>, or similar instead.
511 Represents an ECDSA signature.
513 =item B<RSAPublicKey>
515 Represents a PKCS#1 RSA public key structure.
519 Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and
524 Represents a B<Name> type as used for subject and issuer names in
525 IETF RFC 6960 and elsewhere.
529 Represents a PKCS#10 certificate request.
533 Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
539 B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
540 B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has
541 been used with a valid structure being passed in via I<a>, then the object is
542 freed in the event of error and I<*a> is set to NULL.
544 B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
545 value if an error occurs.
547 B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
552 Allocate and encode the DER encoding of an X509 structure:
558 len = i2d_X509(x, &buf);
562 Attempt to decode a buffer:
565 unsigned char *buf, *p;
568 /* Set up buf and len to point to the input buffer. */
570 x = d2i_X509(NULL, &p, len);
574 Alternative technique:
577 unsigned char *buf, *p;
580 /* Set up buf and len to point to the input buffer. */
584 if (d2i_X509(&x, &p, len) == NULL)
589 Using a temporary variable is mandatory. A common
590 mistake is to attempt to use a buffer directly as follows:
595 len = i2d_X509(x, NULL);
596 buf = OPENSSL_malloc(len);
602 This code will result in I<buf> apparently containing garbage because
603 it was incremented after the call to point after the data just written.
604 Also I<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
605 and the subsequent call to OPENSSL_free() is likely to crash.
607 Another trap to avoid is misuse of the I<a> argument to B<d2i_I<TYPE>>():
611 if (d2i_X509(&x, &p, len) == NULL)
614 This will probably crash somewhere in d2i_X509(). The reason for this
615 is that the variable I<x> is uninitialized and an attempt will be made to
616 interpret its (invalid) value as an B<X509> structure, typically causing
617 a segmentation violation. If I<x> is set to NULL first then this will not
622 In some versions of OpenSSL the "reuse" behaviour of B<d2i_I<TYPE>>() when
623 I<*a> is valid is broken and some parts of the reused structure may
624 persist if they are not present in the new one. Additionally, in versions of
625 OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs
626 the behaviour is inconsistent. Some functions behaved as described here, while
627 some did not free I<*a> on error and did not set I<*a> to NULL.
629 As a result of the above issues the "reuse" behaviour is strongly discouraged.
631 B<i2d_I<TYPE>>() will not return an error in many versions of OpenSSL,
632 if mandatory fields are not initialized due to a programming error
633 then the encoded structure may contain invalid data or omit the
634 fields entirely and will not be parsed by B<d2i_I<TYPE>>(). This may be
635 fixed in future so code should not assume that B<i2d_I<TYPE>>() will
638 Any function which encodes a structure (B<i2d_I<TYPE>>(),
639 B<i2d_I<TYPE>>() or B<i2d_I<TYPE>>()) may return a stale encoding if the
640 structure has been modified after deserialization or previous
641 serialization. This is because some objects cache the encoding for
646 Copyright 1998-2020 The OpenSSL Project Authors. All Rights Reserved.
648 Licensed under the Apache License 2.0 (the "License"). You may not use
649 this file except in compliance with the License. You can obtain a copy
650 in the file LICENSE in the source distribution or at
651 L<https://www.openssl.org/source/license.html>.