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,
79 d2i_ISSUING_DIST_POINT,
81 d2i_NETSCAPE_CERT_SEQUENCE,
101 d2i_OSSL_CMP_PKIHEADER,
103 d2i_OSSL_CRMF_CERTID,
104 d2i_OSSL_CRMF_CERTTEMPLATE,
105 d2i_OSSL_CRMF_ENCRYPTEDVALUE,
108 d2i_OSSL_CRMF_PBMPARAMETER,
109 d2i_OSSL_CRMF_PKIPUBLICATIONINFO,
110 d2i_OSSL_CRMF_SINGLEPUBINFO,
124 d2i_PKCS7_ENC_CONTENT,
126 d2i_PKCS7_ISSUER_AND_SERIAL,
127 d2i_PKCS7_RECIP_INFO,
129 d2i_PKCS7_SIGNER_INFO,
130 d2i_PKCS7_SIGN_ENVELOPE,
133 d2i_PKCS8_PRIV_KEY_INFO,
134 d2i_PKCS8_PRIV_KEY_INFO_bio,
135 d2i_PKCS8_PRIV_KEY_INFO_fp,
138 d2i_PKEY_USAGE_PERIOD,
142 d2i_PROXY_CERT_INFO_EXTENSION,
145 d2i_RSAPrivateKey_bio,
146 d2i_RSAPrivateKey_fp,
148 d2i_RSAPublicKey_bio,
161 d2i_TS_MSG_IMPRINT_bio,
162 d2i_TS_MSG_IMPRINT_fp,
198 i2d_ACCESS_DESCRIPTION,
200 i2d_ADMISSION_SYNTAX,
202 i2d_ASIdentifierChoice,
207 i2d_ASN1_GENERALIZEDTIME,
208 i2d_ASN1_GENERALSTRING,
213 i2d_ASN1_OCTET_STRING,
215 i2d_ASN1_PRINTABLESTRING,
216 i2d_ASN1_SEQUENCE_ANY,
221 i2d_ASN1_UNIVERSALSTRING,
224 i2d_ASN1_VISIBLESTRING,
227 i2d_AUTHORITY_INFO_ACCESS,
229 i2d_BASIC_CONSTRAINTS,
230 i2d_CERTIFICATEPOLICIES,
232 i2d_CMS_ReceiptRequest,
241 i2d_DSAPrivateKey_bio,
242 i2d_DSAPrivateKey_fp,
253 i2d_ECPrivateKey_bio,
261 i2d_ESS_ISSUER_SERIAL,
262 i2d_ESS_SIGNING_CERT,
263 i2d_ESS_SIGNING_CERT_V2,
264 i2d_EXTENDED_KEY_USAGE,
269 i2d_IPAddressOrRange,
271 i2d_ISSUER_SIGN_TOOL,
272 i2d_ISSUING_DIST_POINT,
273 i2d_NAMING_AUTHORITY,
274 i2d_NETSCAPE_CERT_SEQUENCE,
289 i2d_OCSP_REVOKEDINFO,
294 i2d_OSSL_CMP_PKIHEADER,
296 i2d_OSSL_CRMF_CERTID,
297 i2d_OSSL_CRMF_CERTTEMPLATE,
298 i2d_OSSL_CRMF_ENCRYPTEDVALUE,
301 i2d_OSSL_CRMF_PBMPARAMETER,
302 i2d_OSSL_CRMF_PKIPUBLICATIONINFO,
303 i2d_OSSL_CRMF_SINGLEPUBINFO,
317 i2d_PKCS7_ENC_CONTENT,
319 i2d_PKCS7_ISSUER_AND_SERIAL,
321 i2d_PKCS7_RECIP_INFO,
323 i2d_PKCS7_SIGNER_INFO,
324 i2d_PKCS7_SIGN_ENVELOPE,
327 i2d_PKCS8PrivateKeyInfo_bio,
328 i2d_PKCS8PrivateKeyInfo_fp,
329 i2d_PKCS8_PRIV_KEY_INFO,
330 i2d_PKCS8_PRIV_KEY_INFO_bio,
331 i2d_PKCS8_PRIV_KEY_INFO_fp,
334 i2d_PKEY_USAGE_PERIOD,
338 i2d_PROXY_CERT_INFO_EXTENSION,
341 i2d_RSAPrivateKey_bio,
342 i2d_RSAPrivateKey_fp,
344 i2d_RSAPublicKey_bio,
357 i2d_TS_MSG_IMPRINT_bio,
358 i2d_TS_MSG_IMPRINT_fp,
394 - convert objects from/to ASN.1/DER representation
400 TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length);
401 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
402 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
404 int i2d_TYPE(const TYPE *a, unsigned char **ppout);
405 int i2d_TYPE(TYPE *a, unsigned char **ppout);
406 int i2d_TYPE_fp(FILE *fp, const TYPE *a);
407 int i2d_TYPE_fp(FILE *fp, TYPE *a);
408 int i2d_TYPE_bio(BIO *bp, const TYPE *a);
409 int i2d_TYPE_bio(BIO *bp, TYPE *a);
413 In the description here, B<I<TYPE>> is used a placeholder
414 for any of the OpenSSL datatypes, such as I<X509_CRL>.
415 The function parameters I<ppin> and I<ppout> are generally
416 either both named I<pp> in the headers, or I<in> and I<out>.
418 These functions convert OpenSSL objects to and from their ASN.1/DER
419 encoding. Unlike the C structures which can have pointers to sub-objects
420 within, the DER is a serialized encoding, suitable for sending over the
421 network, writing to a file, and so on.
423 B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a
424 pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to
425 the byte following the parsed data. If I<a> is not NULL then a pointer
426 to the returned structure is also written to I<*a>. If an error occurred
427 then NULL is returned.
429 On a successful return, if I<*a> is not NULL then it is assumed that I<*a>
430 contains a valid B<I<TYPE>> structure and an attempt is made to reuse it. This
431 "reuse" capability is present for historical compatibility but its use is
432 B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
435 B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts
436 to parse data from BIO I<bp>.
438 B<d2i_I<TYPE>_fp>() is similar to B<d2i_I<TYPE>>() except it attempts
439 to parse data from FILE pointer I<fp>.
441 B<i2d_I<TYPE>>() encodes the structure pointed to by I<a> into DER format.
442 If I<ppout> is not NULL, it writes the DER encoded data to the buffer
443 at I<*ppout>, and increments it to point after the data just written.
444 If the return value is negative an error occurred, otherwise it
445 returns the length of the encoded data.
447 If I<*ppout> is NULL memory will be allocated for a buffer and the encoded
448 data written to it. In this case I<*ppout> is not incremented and it points
449 to the start of the data just written.
451 B<i2d_I<TYPE>_bio>() is similar to B<i2d_I<TYPE>>() except it writes
452 the encoding of the structure I<a> to BIO I<bp> and it
453 returns 1 for success and 0 for failure.
455 B<i2d_I<TYPE>_fp>() is similar to B<i2d_I<TYPE>>() except it writes
456 the encoding of the structure I<a> to BIO I<bp> and it
457 returns 1 for success and 0 for failure.
459 These routines do not encrypt private keys and therefore offer no
460 security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
464 The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
465 "internal" (that is, an internal C structure) and "DER" respectively.
466 So B<i2d_I<TYPE>>() converts from internal to DER.
468 The functions can also understand B<BER> forms.
470 The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
471 populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
472 empty structure such as that returned by TYPE_new().
474 The encoded data is in binary form and may contain embedded zeros.
475 Therefore any FILE pointers or BIOs should be opened in binary mode.
476 Functions such as strlen() will B<not> return the correct length
477 of the encoded structure.
479 The ways that I<*ppin> and I<*ppout> are incremented after the operation
480 can trap the unwary. See the B<WARNINGS> section for some common
482 The reason for this-auto increment behaviour is to reflect a typical
483 usage of ASN1 functions: after one structure is encoded or decoded
484 another will be processed after it.
486 The following points about the data types might be useful:
492 Represents an ASN1 OBJECT IDENTIFIER.
496 Represents a PKCS#3 DH parameters structure.
500 Represents an ANSI X9.42 DH parameters structure.
504 Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
506 =item B<DSAPublicKey>, B<DSAPrivateKey>
508 Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
509 L<PEM_write_PrivateKey(3)>, or similar instead.
513 Represents an ECDSA signature.
515 =item B<RSAPublicKey>
517 Represents a PKCS#1 RSA public key structure.
521 Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and
526 Represents a B<Name> type as used for subject and issuer names in
527 IETF RFC 6960 and elsewhere.
531 Represents a PKCS#10 certificate request.
535 Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
541 B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
542 B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has
543 been used with a valid structure being passed in via I<a>, then the object is
544 freed in the event of error and I<*a> is set to NULL.
546 B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
547 value if an error occurs.
549 B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
554 Allocate and encode the DER encoding of an X509 structure:
560 len = i2d_X509(x, &buf);
564 Attempt to decode a buffer:
567 unsigned char *buf, *p;
570 /* Set up buf and len to point to the input buffer. */
572 x = d2i_X509(NULL, &p, len);
576 Alternative technique:
579 unsigned char *buf, *p;
582 /* Set up buf and len to point to the input buffer. */
586 if (d2i_X509(&x, &p, len) == NULL)
591 Using a temporary variable is mandatory. A common
592 mistake is to attempt to use a buffer directly as follows:
597 len = i2d_X509(x, NULL);
598 buf = OPENSSL_malloc(len);
604 This code will result in I<buf> apparently containing garbage because
605 it was incremented after the call to point after the data just written.
606 Also I<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
607 and the subsequent call to OPENSSL_free() is likely to crash.
609 Another trap to avoid is misuse of the I<a> argument to B<d2i_I<TYPE>>():
613 if (d2i_X509(&x, &p, len) == NULL)
616 This will probably crash somewhere in d2i_X509(). The reason for this
617 is that the variable I<x> is uninitialized and an attempt will be made to
618 interpret its (invalid) value as an B<X509> structure, typically causing
619 a segmentation violation. If I<x> is set to NULL first then this will not
624 In some versions of OpenSSL the "reuse" behaviour of B<d2i_I<TYPE>>() when
625 I<*a> is valid is broken and some parts of the reused structure may
626 persist if they are not present in the new one. Additionally, in versions of
627 OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs
628 the behaviour is inconsistent. Some functions behaved as described here, while
629 some did not free I<*a> on error and did not set I<*a> to NULL.
631 As a result of the above issues the "reuse" behaviour is strongly discouraged.
633 B<i2d_I<TYPE>>() will not return an error in many versions of OpenSSL,
634 if mandatory fields are not initialized due to a programming error
635 then the encoded structure may contain invalid data or omit the
636 fields entirely and will not be parsed by B<d2i_I<TYPE>>(). This may be
637 fixed in future so code should not assume that B<i2d_I<TYPE>>() will
640 Any function which encodes a structure (B<i2d_I<TYPE>>(),
641 B<i2d_I<TYPE>>() or B<i2d_I<TYPE>>()) may return a stale encoding if the
642 structure has been modified after deserialization or previous
643 serialization. This is because some objects cache the encoding for
648 Copyright 1998-2020 The OpenSSL Project Authors. All Rights Reserved.
650 Licensed under the Apache License 2.0 (the "License"). You may not use
651 this file except in compliance with the License. You can obtain a copy
652 in the file LICENSE in the source distribution or at
653 L<https://www.openssl.org/source/license.html>.