5 Any keypair function here that gets deprecated should be moved to
12 d2i_ACCESS_DESCRIPTION,
16 d2i_ASIdentifierChoice,
21 d2i_ASN1_GENERALIZEDTIME,
22 d2i_ASN1_GENERALSTRING,
27 d2i_ASN1_OCTET_STRING,
29 d2i_ASN1_PRINTABLESTRING,
30 d2i_ASN1_SEQUENCE_ANY,
36 d2i_ASN1_UNIVERSALSTRING,
39 d2i_ASN1_VISIBLESTRING,
41 d2i_AUTHORITY_INFO_ACCESS,
43 d2i_BASIC_CONSTRAINTS,
44 d2i_CERTIFICATEPOLICIES,
46 d2i_CMS_ReceiptRequest,
59 d2i_ESS_ISSUER_SERIAL,
61 d2i_ESS_SIGNING_CERT_V2,
62 d2i_EXTENDED_KEY_USAGE,
70 d2i_ISSUING_DIST_POINT,
72 d2i_NETSCAPE_CERT_SEQUENCE,
92 d2i_OSSL_CMP_PKIHEADER,
95 d2i_OSSL_CRMF_CERTTEMPLATE,
96 d2i_OSSL_CRMF_ENCRYPTEDVALUE,
99 d2i_OSSL_CRMF_PBMPARAMETER,
100 d2i_OSSL_CRMF_PKIPUBLICATIONINFO,
101 d2i_OSSL_CRMF_SINGLEPUBINFO,
115 d2i_PKCS7_ENC_CONTENT,
117 d2i_PKCS7_ISSUER_AND_SERIAL,
118 d2i_PKCS7_RECIP_INFO,
120 d2i_PKCS7_SIGNER_INFO,
121 d2i_PKCS7_SIGN_ENVELOPE,
124 d2i_PKCS8_PRIV_KEY_INFO,
125 d2i_PKCS8_PRIV_KEY_INFO_bio,
126 d2i_PKCS8_PRIV_KEY_INFO_fp,
129 d2i_PKEY_USAGE_PERIOD,
133 d2i_PROXY_CERT_INFO_EXTENSION,
143 d2i_TS_MSG_IMPRINT_bio,
144 d2i_TS_MSG_IMPRINT_fp,
180 i2d_ACCESS_DESCRIPTION,
182 i2d_ADMISSION_SYNTAX,
184 i2d_ASIdentifierChoice,
189 i2d_ASN1_GENERALIZEDTIME,
190 i2d_ASN1_GENERALSTRING,
195 i2d_ASN1_OCTET_STRING,
197 i2d_ASN1_PRINTABLESTRING,
198 i2d_ASN1_SEQUENCE_ANY,
203 i2d_ASN1_UNIVERSALSTRING,
206 i2d_ASN1_VISIBLESTRING,
209 i2d_AUTHORITY_INFO_ACCESS,
211 i2d_BASIC_CONSTRAINTS,
212 i2d_CERTIFICATEPOLICIES,
214 i2d_CMS_ReceiptRequest,
227 i2d_ESS_ISSUER_SERIAL,
228 i2d_ESS_SIGNING_CERT,
229 i2d_ESS_SIGNING_CERT_V2,
230 i2d_EXTENDED_KEY_USAGE,
235 i2d_IPAddressOrRange,
237 i2d_ISSUER_SIGN_TOOL,
238 i2d_ISSUING_DIST_POINT,
239 i2d_NAMING_AUTHORITY,
240 i2d_NETSCAPE_CERT_SEQUENCE,
255 i2d_OCSP_REVOKEDINFO,
260 i2d_OSSL_CMP_PKIHEADER,
262 i2d_OSSL_CRMF_CERTID,
263 i2d_OSSL_CRMF_CERTTEMPLATE,
264 i2d_OSSL_CRMF_ENCRYPTEDVALUE,
267 i2d_OSSL_CRMF_PBMPARAMETER,
268 i2d_OSSL_CRMF_PKIPUBLICATIONINFO,
269 i2d_OSSL_CRMF_SINGLEPUBINFO,
283 i2d_PKCS7_ENC_CONTENT,
285 i2d_PKCS7_ISSUER_AND_SERIAL,
287 i2d_PKCS7_RECIP_INFO,
289 i2d_PKCS7_SIGNER_INFO,
290 i2d_PKCS7_SIGN_ENVELOPE,
293 i2d_PKCS8PrivateKeyInfo_bio,
294 i2d_PKCS8PrivateKeyInfo_fp,
295 i2d_PKCS8_PRIV_KEY_INFO,
296 i2d_PKCS8_PRIV_KEY_INFO_bio,
297 i2d_PKCS8_PRIV_KEY_INFO_fp,
300 i2d_PKEY_USAGE_PERIOD,
304 i2d_PROXY_CERT_INFO_EXTENSION,
314 i2d_TS_MSG_IMPRINT_bio,
315 i2d_TS_MSG_IMPRINT_fp,
351 - convert objects from/to ASN.1/DER representation
357 TYPE *d2i_TYPE(TYPE **a, const unsigned char **ppin, long length);
358 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
359 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
361 int i2d_TYPE(const TYPE *a, unsigned char **ppout);
362 int i2d_TYPE(TYPE *a, unsigned char **ppout);
363 int i2d_TYPE_fp(FILE *fp, const TYPE *a);
364 int i2d_TYPE_fp(FILE *fp, TYPE *a);
365 int i2d_TYPE_bio(BIO *bp, const TYPE *a);
366 int i2d_TYPE_bio(BIO *bp, TYPE *a);
370 In the description here, B<I<TYPE>> is used a placeholder
371 for any of the OpenSSL datatypes, such as B<X509_CRL>.
372 The function parameters I<ppin> and I<ppout> are generally
373 either both named I<pp> in the headers, or I<in> and I<out>.
375 These functions convert OpenSSL objects to and from their ASN.1/DER
376 encoding. Unlike the C structures which can have pointers to sub-objects
377 within, the DER is a serialized encoding, suitable for sending over the
378 network, writing to a file, and so on.
380 B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a
381 pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to
382 the byte following the parsed data. If I<a> is not NULL then a pointer
383 to the returned structure is also written to I<*a>. If an error occurred
384 then NULL is returned.
386 On a successful return, if I<*a> is not NULL then it is assumed that I<*a>
387 contains a valid B<I<TYPE>> structure and an attempt is made to reuse it. This
388 "reuse" capability is present for historical compatibility but its use is
389 B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
392 B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts
393 to parse data from BIO I<bp>.
395 B<d2i_I<TYPE>_fp>() is similar to B<d2i_I<TYPE>>() except it attempts
396 to parse data from FILE pointer I<fp>.
398 B<i2d_I<TYPE>>() encodes the structure pointed to by I<a> into DER format.
399 If I<ppout> is not NULL, it writes the DER encoded data to the buffer
400 at I<*ppout>, and increments it to point after the data just written.
401 If the return value is negative an error occurred, otherwise it
402 returns the length of the encoded data.
404 If I<*ppout> is NULL memory will be allocated for a buffer and the encoded
405 data written to it. In this case I<*ppout> is not incremented and it points
406 to the start of the data just written.
408 B<i2d_I<TYPE>_bio>() is similar to B<i2d_I<TYPE>>() except it writes
409 the encoding of the structure I<a> to BIO I<bp> and it
410 returns 1 for success and 0 for failure.
412 B<i2d_I<TYPE>_fp>() is similar to B<i2d_I<TYPE>>() except it writes
413 the encoding of the structure I<a> to FILE pointer I<fp> and it
414 returns 1 for success and 0 for failure.
416 These routines do not encrypt private keys and therefore offer no
417 security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
421 The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
422 "internal" (that is, an internal C structure) and "DER" respectively.
423 So B<i2d_I<TYPE>>() converts from internal to DER.
425 The functions can also understand B<BER> forms.
427 The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
428 populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
429 empty structure such as that returned by TYPE_new().
431 The encoded data is in binary form and may contain embedded zeros.
432 Therefore, any FILE pointers or BIOs should be opened in binary mode.
433 Functions such as strlen() will B<not> return the correct length
434 of the encoded structure.
436 The ways that I<*ppin> and I<*ppout> are incremented after the operation
437 can trap the unwary. See the B<WARNINGS> section for some common
439 The reason for this-auto increment behaviour is to reflect a typical
440 usage of ASN1 functions: after one structure is encoded or decoded
441 another will be processed after it.
443 The following points about the data types might be useful:
449 Represents an ASN1 OBJECT IDENTIFIER.
453 Represents a PKCS#3 DH parameters structure.
457 Represents an ANSI X9.42 DH parameters structure.
461 Represents an ECDSA signature.
465 Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and
470 Represents a B<Name> type as used for subject and issuer names in
471 IETF RFC 6960 and elsewhere.
475 Represents a PKCS#10 certificate request.
479 Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
485 B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
486 B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has
487 been used with a valid structure being passed in via I<a>, then the object is
488 freed in the event of error and I<*a> is set to NULL.
490 B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
491 value if an error occurs.
493 B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
498 Allocate and encode the DER encoding of an X509 structure:
504 len = i2d_X509(x, &buf);
508 Attempt to decode a buffer:
512 const unsigned char *p;
515 /* Set up buf and len to point to the input buffer. */
517 x = d2i_X509(NULL, &p, len);
521 Alternative technique:
525 const unsigned char *p;
528 /* Set up buf and len to point to the input buffer. */
532 if (d2i_X509(&x, &p, len) == NULL)
537 Using a temporary variable is mandatory. A common
538 mistake is to attempt to use a buffer directly as follows:
543 len = i2d_X509(x, NULL);
544 buf = OPENSSL_malloc(len);
550 This code will result in I<buf> apparently containing garbage because
551 it was incremented after the call to point after the data just written.
552 Also I<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
553 and the subsequent call to OPENSSL_free() is likely to crash.
555 Another trap to avoid is misuse of the I<a> argument to B<d2i_I<TYPE>>():
559 if (d2i_X509(&x, &p, len) == NULL)
562 This will probably crash somewhere in d2i_X509(). The reason for this
563 is that the variable I<x> is uninitialized and an attempt will be made to
564 interpret its (invalid) value as an B<X509> structure, typically causing
565 a segmentation violation. If I<x> is set to NULL first then this will not
570 In some versions of OpenSSL the "reuse" behaviour of B<d2i_I<TYPE>>() when
571 I<*a> is valid is broken and some parts of the reused structure may
572 persist if they are not present in the new one. Additionally, in versions of
573 OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs
574 the behaviour is inconsistent. Some functions behaved as described here, while
575 some did not free I<*a> on error and did not set I<*a> to NULL.
577 As a result of the above issues the "reuse" behaviour is strongly discouraged.
579 B<i2d_I<TYPE>>() will not return an error in many versions of OpenSSL,
580 if mandatory fields are not initialized due to a programming error
581 then the encoded structure may contain invalid data or omit the
582 fields entirely and will not be parsed by B<d2i_I<TYPE>>(). This may be
583 fixed in future so code should not assume that B<i2d_I<TYPE>>() will
586 Any function which encodes a structure (B<i2d_I<TYPE>>(),
587 B<i2d_I<TYPE>>() or B<i2d_I<TYPE>>()) may return a stale encoding if the
588 structure has been modified after deserialization or previous
589 serialization. This is because some objects cache the encoding for
594 Copyright 1998-2021 The OpenSSL Project Authors. All Rights Reserved.
596 Licensed under the Apache License 2.0 (the "License"). You may not use
597 this file except in compliance with the License. You can obtain a copy
598 in the file LICENSE in the source distribution or at
599 L<https://www.openssl.org/source/license.html>.