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,
101 d2i_OSSL_CRMF_CERTID,
102 d2i_OSSL_CRMF_CERTTEMPLATE,
103 d2i_OSSL_CRMF_ENCRYPTEDVALUE,
106 d2i_OSSL_CRMF_PBMPARAMETER,
107 d2i_OSSL_CRMF_PKIPUBLICATIONINFO,
108 d2i_OSSL_CRMF_SINGLEPUBINFO,
122 d2i_PKCS7_ENC_CONTENT,
124 d2i_PKCS7_ISSUER_AND_SERIAL,
125 d2i_PKCS7_RECIP_INFO,
127 d2i_PKCS7_SIGNER_INFO,
128 d2i_PKCS7_SIGN_ENVELOPE,
131 d2i_PKCS8_PRIV_KEY_INFO,
132 d2i_PKCS8_PRIV_KEY_INFO_bio,
133 d2i_PKCS8_PRIV_KEY_INFO_fp,
136 d2i_PKEY_USAGE_PERIOD,
140 d2i_PROXY_CERT_INFO_EXTENSION,
143 d2i_RSAPrivateKey_bio,
144 d2i_RSAPrivateKey_fp,
146 d2i_RSAPublicKey_bio,
159 d2i_TS_MSG_IMPRINT_bio,
160 d2i_TS_MSG_IMPRINT_fp,
194 i2d_ACCESS_DESCRIPTION,
196 i2d_ADMISSION_SYNTAX,
198 i2d_ASIdentifierChoice,
203 i2d_ASN1_GENERALIZEDTIME,
204 i2d_ASN1_GENERALSTRING,
209 i2d_ASN1_OCTET_STRING,
211 i2d_ASN1_PRINTABLESTRING,
212 i2d_ASN1_SEQUENCE_ANY,
217 i2d_ASN1_UNIVERSALSTRING,
220 i2d_ASN1_VISIBLESTRING,
223 i2d_AUTHORITY_INFO_ACCESS,
225 i2d_BASIC_CONSTRAINTS,
226 i2d_CERTIFICATEPOLICIES,
228 i2d_CMS_ReceiptRequest,
237 i2d_DSAPrivateKey_bio,
238 i2d_DSAPrivateKey_fp,
249 i2d_ECPrivateKey_bio,
257 i2d_ESS_ISSUER_SERIAL,
258 i2d_ESS_SIGNING_CERT,
259 i2d_ESS_SIGNING_CERT_V2,
260 i2d_EXTENDED_KEY_USAGE,
265 i2d_IPAddressOrRange,
267 i2d_ISSUING_DIST_POINT,
268 i2d_NAMING_AUTHORITY,
269 i2d_NETSCAPE_CERT_SEQUENCE,
284 i2d_OCSP_REVOKEDINFO,
289 i2d_OSSL_CMP_PKIHEADER,
290 i2d_OSSL_CRMF_CERTID,
291 i2d_OSSL_CRMF_CERTTEMPLATE,
292 i2d_OSSL_CRMF_ENCRYPTEDVALUE,
295 i2d_OSSL_CRMF_PBMPARAMETER,
296 i2d_OSSL_CRMF_PKIPUBLICATIONINFO,
297 i2d_OSSL_CRMF_SINGLEPUBINFO,
311 i2d_PKCS7_ENC_CONTENT,
313 i2d_PKCS7_ISSUER_AND_SERIAL,
315 i2d_PKCS7_RECIP_INFO,
317 i2d_PKCS7_SIGNER_INFO,
318 i2d_PKCS7_SIGN_ENVELOPE,
321 i2d_PKCS8PrivateKeyInfo_bio,
322 i2d_PKCS8PrivateKeyInfo_fp,
323 i2d_PKCS8_PRIV_KEY_INFO,
324 i2d_PKCS8_PRIV_KEY_INFO_bio,
325 i2d_PKCS8_PRIV_KEY_INFO_fp,
328 i2d_PKEY_USAGE_PERIOD,
332 i2d_PROXY_CERT_INFO_EXTENSION,
335 i2d_RSAPrivateKey_bio,
336 i2d_RSAPrivateKey_fp,
338 i2d_RSAPublicKey_bio,
351 i2d_TS_MSG_IMPRINT_bio,
352 i2d_TS_MSG_IMPRINT_fp,
386 - convert objects from/to ASN.1/DER representation
392 TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length);
393 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
394 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
396 int i2d_TYPE(const TYPE *a, unsigned char **ppout);
397 int i2d_TYPE(TYPE *a, unsigned char **ppout);
398 int i2d_TYPE_fp(FILE *fp, const TYPE *a);
399 int i2d_TYPE_fp(FILE *fp, TYPE *a);
400 int i2d_TYPE_bio(BIO *bp, const TYPE *a);
401 int i2d_TYPE_bio(BIO *bp, TYPE *a);
405 In the description here, I<TYPE> is used a placeholder
406 for any of the OpenSSL datatypes, such as I<X509_CRL>.
407 The function parameters I<ppin> and I<ppout> are generally
408 either both named I<pp> in the headers, or I<in> and I<out>.
410 These functions convert OpenSSL objects to and from their ASN.1/DER
411 encoding. Unlike the C structures which can have pointers to sub-objects
412 within, the DER is a serialized encoding, suitable for sending over the
413 network, writing to a file, and so on.
415 d2i_TYPE() attempts to decode B<len> bytes at B<*ppin>. If successful a
416 pointer to the B<TYPE> structure is returned and B<*ppin> is incremented to
417 the byte following the parsed data. If B<a> is not B<NULL> then a pointer
418 to the returned structure is also written to B<*a>. If an error occurred
419 then B<NULL> is returned.
421 On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a>
422 contains a valid B<TYPE> structure and an attempt is made to reuse it. This
423 "reuse" capability is present for historical compatibility but its use is
424 B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
427 d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts
428 to parse data from BIO B<bp>.
430 d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts
431 to parse data from FILE pointer B<fp>.
433 i2d_TYPE() encodes the structure pointed to by B<a> into DER format.
434 If B<ppout> is not B<NULL>, it writes the DER encoded data to the buffer
435 at B<*ppout>, and increments it to point after the data just written.
436 If the return value is negative an error occurred, otherwise it
437 returns the length of the encoded data.
439 If B<*ppout> is B<NULL> memory will be allocated for a buffer and the encoded
440 data written to it. In this case B<*ppout> is not incremented and it points
441 to the start of the data just written.
443 i2d_TYPE_bio() is similar to i2d_TYPE() except it writes
444 the encoding of the structure B<a> to BIO B<bp> and it
445 returns 1 for success and 0 for failure.
447 i2d_TYPE_fp() is similar to i2d_TYPE() except it writes
448 the encoding of the structure B<a> to BIO B<bp> and it
449 returns 1 for success and 0 for failure.
451 These routines do not encrypt private keys and therefore offer no
452 security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
456 The letters B<i> and B<d> in B<i2d_TYPE> stand for
457 "internal" (that is, an internal C structure) and "DER" respectively.
458 So B<i2d_TYPE> converts from internal to DER.
460 The functions can also understand B<BER> forms.
462 The actual TYPE structure passed to i2d_TYPE() must be a valid
463 populated B<TYPE> structure -- it B<cannot> simply be fed with an
464 empty structure such as that returned by TYPE_new().
466 The encoded data is in binary form and may contain embedded zeroes.
467 Therefore any FILE pointers or BIOs should be opened in binary mode.
468 Functions such as strlen() will B<not> return the correct length
469 of the encoded structure.
471 The ways that B<*ppin> and B<*ppout> are incremented after the operation
472 can trap the unwary. See the B<WARNINGS> section for some common
474 The reason for this-auto increment behaviour is to reflect a typical
475 usage of ASN1 functions: after one structure is encoded or decoded
476 another will be processed after it.
478 The following points about the data types might be useful:
484 Represents an ASN1 OBJECT IDENTIFIER.
488 Represents a PKCS#3 DH parameters structure.
492 Represents an ANSI X9.42 DH parameters structure.
496 Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
498 =item B<DSAPublicKey, DSAPrivateKey>
500 Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
501 B<PEM_write_PrivateKey(3)>, or similar instead.
505 Represents an ECDSA signature.
507 =item B<RSAPublicKey>
509 Represents a PKCS#1 RSA public key structure.
513 Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and
518 Represents a B<Name> type as used for subject and issuer names in
519 IETF RFC 6960 and elsewhere.
523 Represents a PKCS#10 certificate request.
527 Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
533 d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
534 or B<NULL> if an error occurs. If the "reuse" capability has been used with
535 a valid structure being passed in via B<a>, then the object is freed in
536 the event of error and B<*a> is set to NULL.
538 i2d_TYPE() returns the number of bytes successfully encoded or a negative
539 value if an error occurs.
541 i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
546 Allocate and encode the DER encoding of an X509 structure:
552 len = i2d_X509(x, &buf);
556 Attempt to decode a buffer:
559 unsigned char *buf, *p;
562 /* Set up buf and len to point to the input buffer. */
564 x = d2i_X509(NULL, &p, len);
568 Alternative technique:
571 unsigned char *buf, *p;
574 /* Set up buf and len to point to the input buffer. */
578 if (d2i_X509(&x, &p, len) == NULL)
583 Using a temporary variable is mandatory. A common
584 mistake is to attempt to use a buffer directly as follows:
589 len = i2d_X509(x, NULL);
590 buf = OPENSSL_malloc(len);
596 This code will result in B<buf> apparently containing garbage because
597 it was incremented after the call to point after the data just written.
598 Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
599 and the subsequent call to OPENSSL_free() is likely to crash.
601 Another trap to avoid is misuse of the B<a> argument to d2i_TYPE():
605 if (d2i_X509(&x, &p, len) == NULL)
608 This will probably crash somewhere in d2i_X509(). The reason for this
609 is that the variable B<x> is uninitialized and an attempt will be made to
610 interpret its (invalid) value as an B<X509> structure, typically causing
611 a segmentation violation. If B<x> is set to NULL first then this will not
616 In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when
617 B<*a> is valid is broken and some parts of the reused structure may
618 persist if they are not present in the new one. Additionally, in versions of
619 OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs
620 the behaviour is inconsistent. Some functions behaved as described here, while
621 some did not free B<*a> on error and did not set B<*a> to NULL.
623 As a result of the above issues the "reuse" behaviour is strongly discouraged.
625 i2d_TYPE() will not return an error in many versions of OpenSSL,
626 if mandatory fields are not initialized due to a programming error
627 then the encoded structure may contain invalid data or omit the
628 fields entirely and will not be parsed by d2i_TYPE(). This may be
629 fixed in future so code should not assume that i2d_TYPE() will
632 Any function which encodes a structure (i2d_TYPE(),
633 i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the
634 structure has been modified after deserialization or previous
635 serialization. This is because some objects cache the encoding for
640 Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved.
642 Licensed under the Apache License 2.0 (the "License"). You may not use
643 this file except in compliance with the License. You can obtain a copy
644 in the file LICENSE in the source distribution or at
645 L<https://www.openssl.org/source/license.html>.