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,
196 i2d_ACCESS_DESCRIPTION,
198 i2d_ADMISSION_SYNTAX,
200 i2d_ASIdentifierChoice,
205 i2d_ASN1_GENERALIZEDTIME,
206 i2d_ASN1_GENERALSTRING,
211 i2d_ASN1_OCTET_STRING,
213 i2d_ASN1_PRINTABLESTRING,
214 i2d_ASN1_SEQUENCE_ANY,
219 i2d_ASN1_UNIVERSALSTRING,
222 i2d_ASN1_VISIBLESTRING,
225 i2d_AUTHORITY_INFO_ACCESS,
227 i2d_BASIC_CONSTRAINTS,
228 i2d_CERTIFICATEPOLICIES,
230 i2d_CMS_ReceiptRequest,
239 i2d_DSAPrivateKey_bio,
240 i2d_DSAPrivateKey_fp,
251 i2d_ECPrivateKey_bio,
259 i2d_ESS_ISSUER_SERIAL,
260 i2d_ESS_SIGNING_CERT,
261 i2d_ESS_SIGNING_CERT_V2,
262 i2d_EXTENDED_KEY_USAGE,
267 i2d_IPAddressOrRange,
269 i2d_ISSUING_DIST_POINT,
270 i2d_NAMING_AUTHORITY,
271 i2d_NETSCAPE_CERT_SEQUENCE,
286 i2d_OCSP_REVOKEDINFO,
291 i2d_OSSL_CMP_PKIHEADER,
292 i2d_OSSL_CRMF_CERTID,
293 i2d_OSSL_CRMF_CERTTEMPLATE,
294 i2d_OSSL_CRMF_ENCRYPTEDVALUE,
297 i2d_OSSL_CRMF_PBMPARAMETER,
298 i2d_OSSL_CRMF_PKIPUBLICATIONINFO,
299 i2d_OSSL_CRMF_SINGLEPUBINFO,
313 i2d_PKCS7_ENC_CONTENT,
315 i2d_PKCS7_ISSUER_AND_SERIAL,
317 i2d_PKCS7_RECIP_INFO,
319 i2d_PKCS7_SIGNER_INFO,
320 i2d_PKCS7_SIGN_ENVELOPE,
323 i2d_PKCS8PrivateKeyInfo_bio,
324 i2d_PKCS8PrivateKeyInfo_fp,
325 i2d_PKCS8_PRIV_KEY_INFO,
326 i2d_PKCS8_PRIV_KEY_INFO_bio,
327 i2d_PKCS8_PRIV_KEY_INFO_fp,
330 i2d_PKEY_USAGE_PERIOD,
334 i2d_PROXY_CERT_INFO_EXTENSION,
337 i2d_RSAPrivateKey_bio,
338 i2d_RSAPrivateKey_fp,
340 i2d_RSAPublicKey_bio,
353 i2d_TS_MSG_IMPRINT_bio,
354 i2d_TS_MSG_IMPRINT_fp,
390 - convert objects from/to ASN.1/DER representation
396 TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length);
397 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
398 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
400 int i2d_TYPE(const TYPE *a, unsigned char **ppout);
401 int i2d_TYPE(TYPE *a, unsigned char **ppout);
402 int i2d_TYPE_fp(FILE *fp, const TYPE *a);
403 int i2d_TYPE_fp(FILE *fp, TYPE *a);
404 int i2d_TYPE_bio(BIO *bp, const TYPE *a);
405 int i2d_TYPE_bio(BIO *bp, TYPE *a);
409 In the description here, B<I<TYPE>> is used a placeholder
410 for any of the OpenSSL datatypes, such as I<X509_CRL>.
411 The function parameters I<ppin> and I<ppout> are generally
412 either both named I<pp> in the headers, or I<in> and I<out>.
414 These functions convert OpenSSL objects to and from their ASN.1/DER
415 encoding. Unlike the C structures which can have pointers to sub-objects
416 within, the DER is a serialized encoding, suitable for sending over the
417 network, writing to a file, and so on.
419 B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a
420 pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to
421 the byte following the parsed data. If I<a> is not NULL then a pointer
422 to the returned structure is also written to I<*a>. If an error occurred
423 then NULL is returned.
425 On a successful return, if I<*a> is not NULL then it is assumed that I<*a>
426 contains a valid B<I<TYPE>> structure and an attempt is made to reuse it. This
427 "reuse" capability is present for historical compatibility but its use is
428 B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
431 B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts
432 to parse data from BIO I<bp>.
434 B<d2i_I<TYPE>_fp>() is similar to B<d2i_I<TYPE>>() except it attempts
435 to parse data from FILE pointer I<fp>.
437 B<i2d_I<TYPE>>() encodes the structure pointed to by I<a> into DER format.
438 If I<ppout> is not NULL, it writes the DER encoded data to the buffer
439 at I<*ppout>, and increments it to point after the data just written.
440 If the return value is negative an error occurred, otherwise it
441 returns the length of the encoded data.
443 If I<*ppout> is NULL memory will be allocated for a buffer and the encoded
444 data written to it. In this case I<*ppout> is not incremented and it points
445 to the start of the data just written.
447 B<i2d_I<TYPE>_bio>() is similar to B<i2d_I<TYPE>>() except it writes
448 the encoding of the structure I<a> to BIO I<bp> and it
449 returns 1 for success and 0 for failure.
451 B<i2d_I<TYPE>_fp>() 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 These routines do not encrypt private keys and therefore offer no
456 security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
460 The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
461 "internal" (that is, an internal C structure) and "DER" respectively.
462 So B<i2d_I<TYPE>>() converts from internal to DER.
464 The functions can also understand B<BER> forms.
466 The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
467 populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
468 empty structure such as that returned by TYPE_new().
470 The encoded data is in binary form and may contain embedded zeros.
471 Therefore any FILE pointers or BIOs should be opened in binary mode.
472 Functions such as strlen() will B<not> return the correct length
473 of the encoded structure.
475 The ways that I<*ppin> and I<*ppout> are incremented after the operation
476 can trap the unwary. See the B<WARNINGS> section for some common
478 The reason for this-auto increment behaviour is to reflect a typical
479 usage of ASN1 functions: after one structure is encoded or decoded
480 another will be processed after it.
482 The following points about the data types might be useful:
488 Represents an ASN1 OBJECT IDENTIFIER.
492 Represents a PKCS#3 DH parameters structure.
496 Represents an ANSI X9.42 DH parameters structure.
500 Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
502 =item B<DSAPublicKey>, B<DSAPrivateKey>
504 Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
505 L<PEM_write_PrivateKey(3)>, or similar instead.
509 Represents an ECDSA signature.
511 =item B<RSAPublicKey>
513 Represents a PKCS#1 RSA public key structure.
517 Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and
522 Represents a B<Name> type as used for subject and issuer names in
523 IETF RFC 6960 and elsewhere.
527 Represents a PKCS#10 certificate request.
531 Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
537 B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
538 B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has
539 been used with a valid structure being passed in via I<a>, then the object is
540 freed in the event of error and I<*a> is set to NULL.
542 B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
543 value if an error occurs.
545 B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
550 Allocate and encode the DER encoding of an X509 structure:
556 len = i2d_X509(x, &buf);
560 Attempt to decode a buffer:
563 unsigned char *buf, *p;
566 /* Set up buf and len to point to the input buffer. */
568 x = d2i_X509(NULL, &p, len);
572 Alternative technique:
575 unsigned char *buf, *p;
578 /* Set up buf and len to point to the input buffer. */
582 if (d2i_X509(&x, &p, len) == NULL)
587 Using a temporary variable is mandatory. A common
588 mistake is to attempt to use a buffer directly as follows:
593 len = i2d_X509(x, NULL);
594 buf = OPENSSL_malloc(len);
600 This code will result in I<buf> apparently containing garbage because
601 it was incremented after the call to point after the data just written.
602 Also I<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
603 and the subsequent call to OPENSSL_free() is likely to crash.
605 Another trap to avoid is misuse of the I<a> argument to B<d2i_I<TYPE>>():
609 if (d2i_X509(&x, &p, len) == NULL)
612 This will probably crash somewhere in d2i_X509(). The reason for this
613 is that the variable I<x> is uninitialized and an attempt will be made to
614 interpret its (invalid) value as an B<X509> structure, typically causing
615 a segmentation violation. If I<x> is set to NULL first then this will not
620 In some versions of OpenSSL the "reuse" behaviour of B<d2i_I<TYPE>>() when
621 I<*a> is valid is broken and some parts of the reused structure may
622 persist if they are not present in the new one. Additionally, in versions of
623 OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs
624 the behaviour is inconsistent. Some functions behaved as described here, while
625 some did not free I<*a> on error and did not set I<*a> to NULL.
627 As a result of the above issues the "reuse" behaviour is strongly discouraged.
629 B<i2d_I<TYPE>>() will not return an error in many versions of OpenSSL,
630 if mandatory fields are not initialized due to a programming error
631 then the encoded structure may contain invalid data or omit the
632 fields entirely and will not be parsed by B<d2i_I<TYPE>>(). This may be
633 fixed in future so code should not assume that B<i2d_I<TYPE>>() will
636 Any function which encodes a structure (B<i2d_I<TYPE>>(),
637 B<i2d_I<TYPE>>() or B<i2d_I<TYPE>>()) may return a stale encoding if the
638 structure has been modified after deserialization or previous
639 serialization. This is because some objects cache the encoding for
644 Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved.
646 Licensed under the Apache License 2.0 (the "License"). You may not use
647 this file except in compliance with the License. You can obtain a copy
648 in the file LICENSE in the source distribution or at
649 L<https://www.openssl.org/source/license.html>.