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,
66 d2i_ESS_ISSUER_SERIAL,
68 d2i_EXTENDED_KEY_USAGE,
75 d2i_ISSUING_DIST_POINT,
77 d2i_NETSCAPE_CERT_SEQUENCE,
97 d2i_OSSL_CMP_PKIHEADER,
99 d2i_OSSL_CRMF_CERTTEMPLATE,
100 d2i_OSSL_CRMF_ENCRYPTEDVALUE,
103 d2i_OSSL_CRMF_PBMPARAMETER,
104 d2i_OSSL_CRMF_PKIPUBLICATIONINFO,
105 d2i_OSSL_CRMF_SINGLEPUBINFO,
119 d2i_PKCS7_ENC_CONTENT,
121 d2i_PKCS7_ISSUER_AND_SERIAL,
122 d2i_PKCS7_RECIP_INFO,
124 d2i_PKCS7_SIGNER_INFO,
125 d2i_PKCS7_SIGN_ENVELOPE,
128 d2i_PKCS8_PRIV_KEY_INFO,
129 d2i_PKCS8_PRIV_KEY_INFO_bio,
130 d2i_PKCS8_PRIV_KEY_INFO_fp,
133 d2i_PKEY_USAGE_PERIOD,
137 d2i_PROXY_CERT_INFO_EXTENSION,
140 d2i_RSAPrivateKey_bio,
141 d2i_RSAPrivateKey_fp,
143 d2i_RSAPublicKey_bio,
156 d2i_TS_MSG_IMPRINT_bio,
157 d2i_TS_MSG_IMPRINT_fp,
191 i2d_ACCESS_DESCRIPTION,
193 i2d_ADMISSION_SYNTAX,
195 i2d_ASIdentifierChoice,
200 i2d_ASN1_GENERALIZEDTIME,
201 i2d_ASN1_GENERALSTRING,
206 i2d_ASN1_OCTET_STRING,
208 i2d_ASN1_PRINTABLESTRING,
209 i2d_ASN1_SEQUENCE_ANY,
214 i2d_ASN1_UNIVERSALSTRING,
217 i2d_ASN1_VISIBLESTRING,
220 i2d_AUTHORITY_INFO_ACCESS,
222 i2d_BASIC_CONSTRAINTS,
223 i2d_CERTIFICATEPOLICIES,
225 i2d_CMS_ReceiptRequest,
234 i2d_DSAPrivateKey_bio,
235 i2d_DSAPrivateKey_fp,
245 i2d_ECPrivateKey_bio,
252 i2d_ESS_ISSUER_SERIAL,
253 i2d_ESS_SIGNING_CERT,
254 i2d_EXTENDED_KEY_USAGE,
259 i2d_IPAddressOrRange,
261 i2d_ISSUING_DIST_POINT,
262 i2d_NAMING_AUTHORITY,
263 i2d_NETSCAPE_CERT_SEQUENCE,
278 i2d_OCSP_REVOKEDINFO,
283 i2d_OSSL_CMP_PKIHEADER,
284 i2d_OSSL_CRMF_CERTID,
285 i2d_OSSL_CRMF_CERTTEMPLATE,
286 i2d_OSSL_CRMF_ENCRYPTEDVALUE,
289 i2d_OSSL_CRMF_PBMPARAMETER,
290 i2d_OSSL_CRMF_PKIPUBLICATIONINFO,
291 i2d_OSSL_CRMF_SINGLEPUBINFO,
305 i2d_PKCS7_ENC_CONTENT,
307 i2d_PKCS7_ISSUER_AND_SERIAL,
309 i2d_PKCS7_RECIP_INFO,
311 i2d_PKCS7_SIGNER_INFO,
312 i2d_PKCS7_SIGN_ENVELOPE,
315 i2d_PKCS8PrivateKeyInfo_bio,
316 i2d_PKCS8PrivateKeyInfo_fp,
317 i2d_PKCS8_PRIV_KEY_INFO,
318 i2d_PKCS8_PRIV_KEY_INFO_bio,
319 i2d_PKCS8_PRIV_KEY_INFO_fp,
322 i2d_PKEY_USAGE_PERIOD,
326 i2d_PROXY_CERT_INFO_EXTENSION,
329 i2d_RSAPrivateKey_bio,
330 i2d_RSAPrivateKey_fp,
332 i2d_RSAPublicKey_bio,
345 i2d_TS_MSG_IMPRINT_bio,
346 i2d_TS_MSG_IMPRINT_fp,
380 - convert objects from/to ASN.1/DER representation
386 TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length);
387 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
388 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
390 int i2d_TYPE(const TYPE *a, unsigned char **ppout);
391 int i2d_TYPE(TYPE *a, unsigned char **ppout);
392 int i2d_TYPE_fp(FILE *fp, const TYPE *a);
393 int i2d_TYPE_fp(FILE *fp, TYPE *a);
394 int i2d_TYPE_bio(BIO *bp, const TYPE *a);
395 int i2d_TYPE_bio(BIO *bp, TYPE *a);
399 In the description here, I<TYPE> is used a placeholder
400 for any of the OpenSSL datatypes, such as I<X509_CRL>.
401 The function parameters I<ppin> and I<ppout> are generally
402 either both named I<pp> in the headers, or I<in> and I<out>.
404 These functions convert OpenSSL objects to and from their ASN.1/DER
405 encoding. Unlike the C structures which can have pointers to sub-objects
406 within, the DER is a serialized encoding, suitable for sending over the
407 network, writing to a file, and so on.
409 d2i_TYPE() attempts to decode B<len> bytes at B<*ppin>. If successful a
410 pointer to the B<TYPE> structure is returned and B<*ppin> is incremented to
411 the byte following the parsed data. If B<a> is not B<NULL> then a pointer
412 to the returned structure is also written to B<*a>. If an error occurred
413 then B<NULL> is returned.
415 On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a>
416 contains a valid B<TYPE> structure and an attempt is made to reuse it. This
417 "reuse" capability is present for historical compatibility but its use is
418 B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
421 d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts
422 to parse data from BIO B<bp>.
424 d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts
425 to parse data from FILE pointer B<fp>.
427 i2d_TYPE() encodes the structure pointed to by B<a> into DER format.
428 If B<ppout> is not B<NULL>, it writes the DER encoded data to the buffer
429 at B<*ppout>, and increments it to point after the data just written.
430 If the return value is negative an error occurred, otherwise it
431 returns the length of the encoded data.
433 If B<*ppout> is B<NULL> memory will be allocated for a buffer and the encoded
434 data written to it. In this case B<*ppout> is not incremented and it points
435 to the start of the data just written.
437 i2d_TYPE_bio() is similar to i2d_TYPE() except it writes
438 the encoding of the structure B<a> to BIO B<bp> and it
439 returns 1 for success and 0 for failure.
441 i2d_TYPE_fp() is similar to i2d_TYPE() except it writes
442 the encoding of the structure B<a> to BIO B<bp> and it
443 returns 1 for success and 0 for failure.
445 These routines do not encrypt private keys and therefore offer no
446 security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
450 The letters B<i> and B<d> in B<i2d_TYPE> stand for
451 "internal" (that is, an internal C structure) and "DER" respectively.
452 So B<i2d_TYPE> converts from internal to DER.
454 The functions can also understand B<BER> forms.
456 The actual TYPE structure passed to i2d_TYPE() must be a valid
457 populated B<TYPE> structure -- it B<cannot> simply be fed with an
458 empty structure such as that returned by TYPE_new().
460 The encoded data is in binary form and may contain embedded zeroes.
461 Therefore any FILE pointers or BIOs should be opened in binary mode.
462 Functions such as strlen() will B<not> return the correct length
463 of the encoded structure.
465 The ways that B<*ppin> and B<*ppout> are incremented after the operation
466 can trap the unwary. See the B<WARNINGS> section for some common
468 The reason for this-auto increment behaviour is to reflect a typical
469 usage of ASN1 functions: after one structure is encoded or decoded
470 another will be processed after it.
472 The following points about the data types might be useful:
478 Represents an ASN1 OBJECT IDENTIFIER.
482 Represents a PKCS#3 DH parameters structure.
486 Represents an ANSI X9.42 DH parameters structure.
490 Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
492 =item B<DSAPublicKey, DSAPrivateKey>
494 Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
495 B<PEM_write_PrivateKey(3)>, or similar instead.
497 =item B<RSAPublicKey>
499 Represents a PKCS#1 RSA public key structure.
503 Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and
508 Represents a B<Name> type as used for subject and issuer names in
509 IETF RFC 6960 and elsewhere.
513 Represents a PKCS#10 certificate request.
517 Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
523 d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
524 or B<NULL> if an error occurs. If the "reuse" capability has been used with
525 a valid structure being passed in via B<a>, then the object is freed in
526 the event of error and B<*a> is set to NULL.
528 i2d_TYPE() returns the number of bytes successfully encoded or a negative
529 value if an error occurs.
531 i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
536 Allocate and encode the DER encoding of an X509 structure:
542 len = i2d_X509(x, &buf);
546 Attempt to decode a buffer:
549 unsigned char *buf, *p;
552 /* Set up buf and len to point to the input buffer. */
554 x = d2i_X509(NULL, &p, len);
558 Alternative technique:
561 unsigned char *buf, *p;
564 /* Set up buf and len to point to the input buffer. */
568 if (d2i_X509(&x, &p, len) == NULL)
573 Using a temporary variable is mandatory. A common
574 mistake is to attempt to use a buffer directly as follows:
579 len = i2d_X509(x, NULL);
580 buf = OPENSSL_malloc(len);
586 This code will result in B<buf> apparently containing garbage because
587 it was incremented after the call to point after the data just written.
588 Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
589 and the subsequent call to OPENSSL_free() is likely to crash.
591 Another trap to avoid is misuse of the B<a> argument to d2i_TYPE():
595 if (d2i_X509(&x, &p, len) == NULL)
598 This will probably crash somewhere in d2i_X509(). The reason for this
599 is that the variable B<x> is uninitialized and an attempt will be made to
600 interpret its (invalid) value as an B<X509> structure, typically causing
601 a segmentation violation. If B<x> is set to NULL first then this will not
606 In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when
607 B<*a> is valid is broken and some parts of the reused structure may
608 persist if they are not present in the new one. Additionally, in versions of
609 OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs
610 the behaviour is inconsistent. Some functions behaved as described here, while
611 some did not free B<*a> on error and did not set B<*a> to NULL.
613 As a result of the above issues the "reuse" behaviour is strongly discouraged.
615 i2d_TYPE() will not return an error in many versions of OpenSSL,
616 if mandatory fields are not initialized due to a programming error
617 then the encoded structure may contain invalid data or omit the
618 fields entirely and will not be parsed by d2i_TYPE(). This may be
619 fixed in future so code should not assume that i2d_TYPE() will
622 Any function which encodes a structure (i2d_TYPE(),
623 i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the
624 structure has been modified after deserialization or previous
625 serialization. This is because some objects cache the encoding for
630 Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved.
632 Licensed under the Apache License 2.0 (the "License"). You may not use
633 this file except in compliance with the License. You can obtain a copy
634 in the file LICENSE in the source distribution or at
635 L<https://www.openssl.org/source/license.html>.