5 d2i_ACCESS_DESCRIPTION,
7 d2i_ASIdentifierChoice,
12 d2i_ASN1_GENERALIZEDTIME,
13 d2i_ASN1_GENERALSTRING,
18 d2i_ASN1_OCTET_STRING,
20 d2i_ASN1_PRINTABLESTRING,
21 d2i_ASN1_SEQUENCE_ANY,
27 d2i_ASN1_UNIVERSALSTRING,
30 d2i_ASN1_VISIBLESTRING,
32 d2i_AUTHORITY_INFO_ACCESS,
34 d2i_BASIC_CONSTRAINTS,
35 d2i_CERTIFICATEPOLICIES,
37 d2i_CMS_ReceiptRequest,
46 d2i_DSAPrivateKey_bio,
63 d2i_ESS_ISSUER_SERIAL,
65 d2i_EXTENDED_KEY_USAGE,
72 d2i_ISSUING_DIST_POINT,
73 d2i_NETSCAPE_CERT_SEQUENCE,
105 d2i_PKCS7_ENC_CONTENT,
107 d2i_PKCS7_ISSUER_AND_SERIAL,
108 d2i_PKCS7_RECIP_INFO,
110 d2i_PKCS7_SIGNER_INFO,
111 d2i_PKCS7_SIGN_ENVELOPE,
114 d2i_PKCS8_PRIV_KEY_INFO,
115 d2i_PKCS8_PRIV_KEY_INFO_bio,
116 d2i_PKCS8_PRIV_KEY_INFO_fp,
119 d2i_PKEY_USAGE_PERIOD,
122 d2i_PROXY_CERT_INFO_EXTENSION,
126 d2i_RSAPrivateKey_bio,
127 d2i_RSAPrivateKey_fp,
129 d2i_RSAPublicKey_bio,
141 d2i_TS_MSG_IMPRINT_bio,
142 d2i_TS_MSG_IMPRINT_fp,
176 i2d_ACCESS_DESCRIPTION,
178 i2d_ASIdentifierChoice,
183 i2d_ASN1_GENERALIZEDTIME,
184 i2d_ASN1_GENERALSTRING,
189 i2d_ASN1_OCTET_STRING,
191 i2d_ASN1_PRINTABLESTRING,
192 i2d_ASN1_SEQUENCE_ANY,
197 i2d_ASN1_UNIVERSALSTRING,
200 i2d_ASN1_VISIBLESTRING,
203 i2d_AUTHORITY_INFO_ACCESS,
205 i2d_BASIC_CONSTRAINTS,
206 i2d_CERTIFICATEPOLICIES,
208 i2d_CMS_ReceiptRequest,
217 i2d_DSAPrivateKey_bio,
218 i2d_DSAPrivateKey_fp,
227 i2d_ECPrivateKey_bio,
234 i2d_ESS_ISSUER_SERIAL,
235 i2d_ESS_SIGNING_CERT,
236 i2d_EXTENDED_KEY_USAGE,
241 i2d_IPAddressOrRange,
243 i2d_ISSUING_DIST_POINT,
244 i2d_NETSCAPE_CERT_SEQUENCE,
259 i2d_OCSP_REVOKEDINFO,
276 i2d_PKCS7_ENC_CONTENT,
278 i2d_PKCS7_ISSUER_AND_SERIAL,
280 i2d_PKCS7_RECIP_INFO,
282 i2d_PKCS7_SIGNER_INFO,
283 i2d_PKCS7_SIGN_ENVELOPE,
286 i2d_PKCS8PrivateKeyInfo_bio,
287 i2d_PKCS8PrivateKeyInfo_fp,
288 i2d_PKCS8_PRIV_KEY_INFO,
289 i2d_PKCS8_PRIV_KEY_INFO_bio,
290 i2d_PKCS8_PRIV_KEY_INFO_fp,
293 i2d_PKEY_USAGE_PERIOD,
296 i2d_PROXY_CERT_INFO_EXTENSION,
300 i2d_RSAPrivateKey_bio,
301 i2d_RSAPrivateKey_fp,
303 i2d_RSAPublicKey_bio,
315 i2d_TS_MSG_IMPRINT_bio,
316 i2d_TS_MSG_IMPRINT_fp,
350 - convert objects from/to ASN.1/DER representation
356 TYPE *d2i_TYPE(TYPE **a, unsigned char **pp, long length);
357 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
358 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
360 int i2d_TYPE(TYPE *a, unsigned char **pp);
361 int i2d_TYPE_fp(FILE *fp, TYPE *a);
362 int i2d_TYPE_bio(BIO *bp, TYPE *a);
366 In the description here, I<TYPE> is used a placeholder
367 for any of the OpenSSL datatypes, such as I<X509_CRL>.
369 These functions convert OpenSSL objects to and from their ASN.1/DER
370 encoding. Unlike the C structures which can have pointers to sub-objects
371 within, the DER is a serialized encoding, suitable for sending over the
372 network, writing to a file, and so on.
374 d2i_TYPE() attempts to decode B<len> bytes at B<*in>. If successful a
375 pointer to the B<TYPE> structure is returned and B<*in> is incremented to
376 the byte following the parsed data. If B<a> is not B<NULL> then a pointer
377 to the returned structure is also written to B<*a>. If an error occurred
378 then B<NULL> is returned.
380 On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a>
381 contains a valid B<TYPE> structure and an attempt is made to reuse it. This
382 "reuse" capability is present for historical compatibility but its use is
383 B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
386 d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts
387 to parse data from BIO B<bp>.
389 d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts
390 to parse data from FILE pointer B<fp>.
392 i2d_TYPE() encodes the structure pointed to by B<a> into DER format.
393 If B<out> is not B<NULL>, it writes the DER encoded data to the buffer
394 at B<*out>, and increments it to point after the data just written.
395 If the return value is negative an error occurred, otherwise it
396 returns the length of the encoded data.
398 If B<*out> is B<NULL> memory will be allocated for a buffer and the encoded
399 data written to it. In this case B<*out> is not incremented and it points
400 to the start of the data just written.
402 i2d_TYPE_bio() is similar to i2d_TYPE() except it writes
403 the encoding of the structure B<a> to BIO B<bp> and it
404 returns 1 for success and 0 for failure.
406 i2d_TYPE_fp() is similar to i2d_TYPE() except it writes
407 the encoding of the structure B<a> to BIO B<bp> and it
408 returns 1 for success and 0 for failure.
410 These routines do not encrypt private keys and therefore offer no
411 security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
415 The letters B<i> and B<d> in B<i2d_TYPE> stand for
416 "internal" (that is, an internal C structure) and "DER" respectively.
417 So B<i2d_TYPE> converts from internal to DER.
419 The functions can also understand B<BER> forms.
421 The actual TYPE structure passed to i2d_TYPE() must be a valid
422 populated B<TYPE> structure -- it B<cannot> simply be fed with an
423 empty structure such as that returned by TYPE_new().
425 The encoded data is in binary form and may contain embedded zeroes.
426 Therefore any FILE pointers or BIOs should be opened in binary mode.
427 Functions such as strlen() will B<not> return the correct length
428 of the encoded structure.
430 The ways that B<*in> and B<*out> are incremented after the operation
431 can trap the unwary. See the B<WARNINGS> section for some common
433 The reason for this-auto increment behaviour is to reflect a typical
434 usage of ASN1 functions: after one structure is encoded or decoded
435 another will be processed after it.
437 The following points about the data types might be useful:
443 Represents an ASN1 OBJECT IDENTIFIER.
447 Represents a PKCS#3 DH parameters structure.
451 Represents a ANSI X9.42 DH parameters structure.
455 Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
457 =item B<DSAPublicKey, DSAPrivateKey>
459 Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
460 B<PEM_write_PrivateKey(3)>, or similar instead.
462 =item B<RSAPublicKey>
464 Represents a PKCS#1 RSA public key structure.
468 Represents an B<AlogrithmIdentifier> structure as used in IETF RFC 6960 and
473 Represents a B<Name> type as used for subject and issuer names in
474 IETF RFC 6960 and elsewhere.
478 Represents a PKCS#10 certificate request.
482 Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
488 Allocate and encode the DER encoding of an X509 structure:
494 len = i2d_X509(x, &buf);
498 Attempt to decode a buffer:
501 unsigned char *buf, *p;
504 /* Set up buf and len to point to the input buffer. */
506 x = d2i_X509(NULL, &p, len);
510 Alternative technique:
513 unsigned char *buf, *p;
516 /* Set up buf and len to point to the input buffer. */
520 if (d2i_X509(&x, &p, len) == NULL)
525 Using a temporary variable is mandatory. A common
526 mistake is to attempt to use a buffer directly as follows:
531 len = i2d_X509(x, NULL);
532 buf = OPENSSL_malloc(len);
538 This code will result in B<buf> apparently containing garbage because
539 it was incremented after the call to point after the data just written.
540 Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
541 and the subsequent call to OPENSSL_free() is likely to crash.
543 Another trap to avoid is misuse of the B<a> argument to d2i_TYPE():
547 if (d2i_X509(&x, &p, len) == NULL)
550 This will probably crash somewhere in d2i_X509(). The reason for this
551 is that the variable B<x> is uninitialized and an attempt will be made to
552 interpret its (invalid) value as an B<X509> structure, typically causing
553 a segmentation violation. If B<x> is set to NULL first then this will not
558 In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when
559 B<*px> is valid is broken and some parts of the reused structure may
560 persist if they are not present in the new one. As a result the use
561 of this "reuse" behaviour is strongly discouraged.
563 i2d_TYPE() will not return an error in many versions of OpenSSL,
564 if mandatory fields are not initialized due to a programming error
565 then the encoded structure may contain invalid data or omit the
566 fields entirely and will not be parsed by d2i_TYPE(). This may be
567 fixed in future so code should not assume that i2d_TYPE() will
570 Any function which encodes a structure (i2d_TYPE(),
571 i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the
572 structure has been modified after deserialization or previous
573 serialization. This is because some objects cache the encoding for
578 d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
579 or B<NULL> if an error occurs. If the "reuse" capability has been used with
580 a valid structure being passed in via B<a>, then the object is not freed in
581 the event of error but may be in a potentially invalid or inconsistent state.
583 i2d_TYPE() returns the number of bytes successfully encoded or a negative
584 value if an error occurs.
586 i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
591 Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved.
593 Licensed under the OpenSSL license (the "License"). You may not use
594 this file except in compliance with the License. You can obtain a copy
595 in the file LICENSE in the source distribution or at
596 L<https://www.openssl.org/source/license.html>.