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,
330 i2d_RSAPrivateKey_bio,
331 i2d_RSAPrivateKey_fp,
333 i2d_RSAPublicKey_bio,
346 i2d_TS_MSG_IMPRINT_bio,
347 i2d_TS_MSG_IMPRINT_fp,
381 - convert objects from/to ASN.1/DER representation
387 TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length);
388 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
389 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
391 int i2d_TYPE(const TYPE *a, unsigned char **ppout);
392 int i2d_TYPE(TYPE *a, unsigned char **ppout);
393 int i2d_TYPE_fp(FILE *fp, const TYPE *a);
394 int i2d_TYPE_fp(FILE *fp, TYPE *a);
395 int i2d_TYPE_bio(BIO *bp, const TYPE *a);
396 int i2d_TYPE_bio(BIO *bp, TYPE *a);
400 In the description here, I<TYPE> is used a placeholder
401 for any of the OpenSSL datatypes, such as I<X509_CRL>.
402 The function parameters I<ppin> and I<ppout> are generally
403 either both named I<pp> in the headers, or I<in> and I<out>.
405 These functions convert OpenSSL objects to and from their ASN.1/DER
406 encoding. Unlike the C structures which can have pointers to sub-objects
407 within, the DER is a serialized encoding, suitable for sending over the
408 network, writing to a file, and so on.
410 d2i_TYPE() attempts to decode B<len> bytes at B<*ppin>. If successful a
411 pointer to the B<TYPE> structure is returned and B<*ppin> is incremented to
412 the byte following the parsed data. If B<a> is not B<NULL> then a pointer
413 to the returned structure is also written to B<*a>. If an error occurred
414 then B<NULL> is returned.
416 On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a>
417 contains a valid B<TYPE> structure and an attempt is made to reuse it. This
418 "reuse" capability is present for historical compatibility but its use is
419 B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
422 d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts
423 to parse data from BIO B<bp>.
425 d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts
426 to parse data from FILE pointer B<fp>.
428 i2d_TYPE() encodes the structure pointed to by B<a> into DER format.
429 If B<ppout> is not B<NULL>, it writes the DER encoded data to the buffer
430 at B<*ppout>, and increments it to point after the data just written.
431 If the return value is negative an error occurred, otherwise it
432 returns the length of the encoded data.
434 If B<*ppout> is B<NULL> memory will be allocated for a buffer and the encoded
435 data written to it. In this case B<*ppout> is not incremented and it points
436 to the start of the data just written.
438 i2d_TYPE_bio() is similar to i2d_TYPE() except it writes
439 the encoding of the structure B<a> to BIO B<bp> and it
440 returns 1 for success and 0 for failure.
442 i2d_TYPE_fp() is similar to i2d_TYPE() except it writes
443 the encoding of the structure B<a> to BIO B<bp> and it
444 returns 1 for success and 0 for failure.
446 These routines do not encrypt private keys and therefore offer no
447 security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
451 The letters B<i> and B<d> in B<i2d_TYPE> stand for
452 "internal" (that is, an internal C structure) and "DER" respectively.
453 So B<i2d_TYPE> converts from internal to DER.
455 The functions can also understand B<BER> forms.
457 The actual TYPE structure passed to i2d_TYPE() must be a valid
458 populated B<TYPE> structure -- it B<cannot> simply be fed with an
459 empty structure such as that returned by TYPE_new().
461 The encoded data is in binary form and may contain embedded zeroes.
462 Therefore any FILE pointers or BIOs should be opened in binary mode.
463 Functions such as strlen() will B<not> return the correct length
464 of the encoded structure.
466 The ways that B<*ppin> and B<*ppout> are incremented after the operation
467 can trap the unwary. See the B<WARNINGS> section for some common
469 The reason for this-auto increment behaviour is to reflect a typical
470 usage of ASN1 functions: after one structure is encoded or decoded
471 another will be processed after it.
473 The following points about the data types might be useful:
479 Represents an ASN1 OBJECT IDENTIFIER.
483 Represents a PKCS#3 DH parameters structure.
487 Represents an ANSI X9.42 DH parameters structure.
491 Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
493 =item B<DSAPublicKey, DSAPrivateKey>
495 Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
496 B<PEM_write_PrivateKey(3)>, or similar instead.
498 =item B<RSAPublicKey>
500 Represents a PKCS#1 RSA public key structure.
504 Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and
509 Represents a B<Name> type as used for subject and issuer names in
510 IETF RFC 6960 and elsewhere.
514 Represents a PKCS#10 certificate request.
518 Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
524 d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
525 or B<NULL> if an error occurs. If the "reuse" capability has been used with
526 a valid structure being passed in via B<a>, then the object is not freed in
527 the event of error but may be in a potentially invalid or inconsistent state.
529 i2d_TYPE() returns the number of bytes successfully encoded or a negative
530 value if an error occurs.
532 i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
537 Allocate and encode the DER encoding of an X509 structure:
543 len = i2d_X509(x, &buf);
547 Attempt to decode a buffer:
550 unsigned char *buf, *p;
553 /* Set up buf and len to point to the input buffer. */
555 x = d2i_X509(NULL, &p, len);
559 Alternative technique:
562 unsigned char *buf, *p;
565 /* Set up buf and len to point to the input buffer. */
569 if (d2i_X509(&x, &p, len) == NULL)
574 Using a temporary variable is mandatory. A common
575 mistake is to attempt to use a buffer directly as follows:
580 len = i2d_X509(x, NULL);
581 buf = OPENSSL_malloc(len);
587 This code will result in B<buf> apparently containing garbage because
588 it was incremented after the call to point after the data just written.
589 Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
590 and the subsequent call to OPENSSL_free() is likely to crash.
592 Another trap to avoid is misuse of the B<a> argument to d2i_TYPE():
596 if (d2i_X509(&x, &p, len) == NULL)
599 This will probably crash somewhere in d2i_X509(). The reason for this
600 is that the variable B<x> is uninitialized and an attempt will be made to
601 interpret its (invalid) value as an B<X509> structure, typically causing
602 a segmentation violation. If B<x> is set to NULL first then this will not
607 In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when
608 B<*px> is valid is broken and some parts of the reused structure may
609 persist if they are not present in the new one. As a result the use
610 of this "reuse" behaviour is strongly discouraged.
612 i2d_TYPE() will not return an error in many versions of OpenSSL,
613 if mandatory fields are not initialized due to a programming error
614 then the encoded structure may contain invalid data or omit the
615 fields entirely and will not be parsed by d2i_TYPE(). This may be
616 fixed in future so code should not assume that i2d_TYPE() will
619 Any function which encodes a structure (i2d_TYPE(),
620 i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the
621 structure has been modified after deserialization or previous
622 serialization. This is because some objects cache the encoding for
627 Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved.
629 Licensed under the Apache License 2.0 (the "License"). You may not use
630 this file except in compliance with the License. You can obtain a copy
631 in the file LICENSE in the source distribution or at
632 L<https://www.openssl.org/source/license.html>.