1=pod
2
3=begin comment
4
5Any keypair function here that gets deprecated should be moved to
6d2i_RSAPrivateKey.pod.
7
8=end comment
9
10=head1 NAME
11
12d2i_ACCESS_DESCRIPTION,
13d2i_ADMISSIONS,
14d2i_ADMISSION_SYNTAX,
15d2i_ASIdOrRange,
16d2i_ASIdentifierChoice,
17d2i_ASIdentifiers,
18d2i_ASN1_BIT_STRING,
19d2i_ASN1_BMPSTRING,
20d2i_ASN1_ENUMERATED,
21d2i_ASN1_GENERALIZEDTIME,
22d2i_ASN1_GENERALSTRING,
23d2i_ASN1_IA5STRING,
24d2i_ASN1_INTEGER,
25d2i_ASN1_NULL,
26d2i_ASN1_OBJECT,
27d2i_ASN1_OCTET_STRING,
28d2i_ASN1_PRINTABLE,
29d2i_ASN1_PRINTABLESTRING,
30d2i_ASN1_SEQUENCE_ANY,
31d2i_ASN1_SET_ANY,
32d2i_ASN1_T61STRING,
33d2i_ASN1_TIME,
34d2i_ASN1_TYPE,
35d2i_ASN1_UINTEGER,
36d2i_ASN1_UNIVERSALSTRING,
37d2i_ASN1_UTCTIME,
38d2i_ASN1_UTF8STRING,
39d2i_ASN1_VISIBLESTRING,
40d2i_ASRange,
41d2i_AUTHORITY_INFO_ACCESS,
42d2i_AUTHORITY_KEYID,
43d2i_BASIC_CONSTRAINTS,
44d2i_CERTIFICATEPOLICIES,
45d2i_CMS_ContentInfo,
46d2i_CMS_ReceiptRequest,
47d2i_CMS_bio,
48d2i_CRL_DIST_POINTS,
49d2i_DHxparams,
50d2i_DIRECTORYSTRING,
51d2i_DISPLAYTEXT,
52d2i_DIST_POINT,
53d2i_DIST_POINT_NAME,
54d2i_DSA_SIG,
55d2i_ECDSA_SIG,
56d2i_EDIPARTYNAME,
57d2i_ESS_CERT_ID,
58d2i_ESS_CERT_ID_V2,
59d2i_ESS_ISSUER_SERIAL,
60d2i_ESS_SIGNING_CERT,
61d2i_ESS_SIGNING_CERT_V2,
62d2i_EXTENDED_KEY_USAGE,
63d2i_GENERAL_NAME,
64d2i_GENERAL_NAMES,
65d2i_IPAddressChoice,
66d2i_IPAddressFamily,
67d2i_IPAddressOrRange,
68d2i_IPAddressRange,
69d2i_ISSUER_SIGN_TOOL,
70d2i_ISSUING_DIST_POINT,
71d2i_NAMING_AUTHORITY,
72d2i_NETSCAPE_CERT_SEQUENCE,
73d2i_NETSCAPE_SPKAC,
74d2i_NETSCAPE_SPKI,
75d2i_NOTICEREF,
76d2i_OCSP_BASICRESP,
77d2i_OCSP_CERTID,
78d2i_OCSP_CERTSTATUS,
79d2i_OCSP_CRLID,
80d2i_OCSP_ONEREQ,
81d2i_OCSP_REQINFO,
82d2i_OCSP_REQUEST,
83d2i_OCSP_RESPBYTES,
84d2i_OCSP_RESPDATA,
85d2i_OCSP_RESPID,
86d2i_OCSP_RESPONSE,
87d2i_OCSP_REVOKEDINFO,
88d2i_OCSP_SERVICELOC,
89d2i_OCSP_SIGNATURE,
90d2i_OCSP_SINGLERESP,
91d2i_OSSL_CMP_MSG,
92d2i_OSSL_CMP_PKIHEADER,
93d2i_OSSL_CMP_PKISI,
94d2i_OSSL_CRMF_CERTID,
95d2i_OSSL_CRMF_CERTTEMPLATE,
96d2i_OSSL_CRMF_ENCRYPTEDVALUE,
97d2i_OSSL_CRMF_MSG,
98d2i_OSSL_CRMF_MSGS,
99d2i_OSSL_CRMF_PBMPARAMETER,
100d2i_OSSL_CRMF_PKIPUBLICATIONINFO,
101d2i_OSSL_CRMF_SINGLEPUBINFO,
102d2i_OTHERNAME,
103d2i_PBE2PARAM,
104d2i_PBEPARAM,
105d2i_PBKDF2PARAM,
106d2i_PKCS12,
107d2i_PKCS12_BAGS,
108d2i_PKCS12_MAC_DATA,
109d2i_PKCS12_SAFEBAG,
110d2i_PKCS12_bio,
111d2i_PKCS12_fp,
112d2i_PKCS7,
113d2i_PKCS7_DIGEST,
114d2i_PKCS7_ENCRYPT,
115d2i_PKCS7_ENC_CONTENT,
116d2i_PKCS7_ENVELOPE,
117d2i_PKCS7_ISSUER_AND_SERIAL,
118d2i_PKCS7_RECIP_INFO,
119d2i_PKCS7_SIGNED,
120d2i_PKCS7_SIGNER_INFO,
121d2i_PKCS7_SIGN_ENVELOPE,
122d2i_PKCS7_bio,
123d2i_PKCS7_fp,
124d2i_PKCS8_PRIV_KEY_INFO,
125d2i_PKCS8_PRIV_KEY_INFO_bio,
126d2i_PKCS8_PRIV_KEY_INFO_fp,
127d2i_PKCS8_bio,
128d2i_PKCS8_fp,
129d2i_PKEY_USAGE_PERIOD,
130d2i_POLICYINFO,
131d2i_POLICYQUALINFO,
132d2i_PROFESSION_INFO,
133d2i_PROXY_CERT_INFO_EXTENSION,
134d2i_PROXY_POLICY,
135d2i_RSA_OAEP_PARAMS,
136d2i_RSA_PSS_PARAMS,
137d2i_SCRYPT_PARAMS,
138d2i_SCT_LIST,
139d2i_SXNET,
140d2i_SXNETID,
141d2i_TS_ACCURACY,
142d2i_TS_MSG_IMPRINT,
143d2i_TS_MSG_IMPRINT_bio,
144d2i_TS_MSG_IMPRINT_fp,
145d2i_TS_REQ,
146d2i_TS_REQ_bio,
147d2i_TS_REQ_fp,
148d2i_TS_RESP,
149d2i_TS_RESP_bio,
150d2i_TS_RESP_fp,
151d2i_TS_STATUS_INFO,
152d2i_TS_TST_INFO,
153d2i_TS_TST_INFO_bio,
154d2i_TS_TST_INFO_fp,
155d2i_USERNOTICE,
156d2i_X509,
157d2i_X509_ALGOR,
158d2i_X509_ALGORS,
159d2i_X509_ATTRIBUTE,
160d2i_X509_CERT_AUX,
161d2i_X509_CINF,
162d2i_X509_CRL,
163d2i_X509_CRL_INFO,
164d2i_X509_CRL_bio,
165d2i_X509_CRL_fp,
166d2i_X509_EXTENSION,
167d2i_X509_EXTENSIONS,
168d2i_X509_NAME,
169d2i_X509_NAME_ENTRY,
170d2i_X509_PUBKEY,
171d2i_X509_PUBKEY_bio,
172d2i_X509_PUBKEY_fp,
173d2i_X509_REQ,
174d2i_X509_REQ_INFO,
175d2i_X509_REQ_bio,
176d2i_X509_REQ_fp,
177d2i_X509_REVOKED,
178d2i_X509_SIG,
179d2i_X509_VAL,
180i2d_ACCESS_DESCRIPTION,
181i2d_ADMISSIONS,
182i2d_ADMISSION_SYNTAX,
183i2d_ASIdOrRange,
184i2d_ASIdentifierChoice,
185i2d_ASIdentifiers,
186i2d_ASN1_BIT_STRING,
187i2d_ASN1_BMPSTRING,
188i2d_ASN1_ENUMERATED,
189i2d_ASN1_GENERALIZEDTIME,
190i2d_ASN1_GENERALSTRING,
191i2d_ASN1_IA5STRING,
192i2d_ASN1_INTEGER,
193i2d_ASN1_NULL,
194i2d_ASN1_OBJECT,
195i2d_ASN1_OCTET_STRING,
196i2d_ASN1_PRINTABLE,
197i2d_ASN1_PRINTABLESTRING,
198i2d_ASN1_SEQUENCE_ANY,
199i2d_ASN1_SET_ANY,
200i2d_ASN1_T61STRING,
201i2d_ASN1_TIME,
202i2d_ASN1_TYPE,
203i2d_ASN1_UNIVERSALSTRING,
204i2d_ASN1_UTCTIME,
205i2d_ASN1_UTF8STRING,
206i2d_ASN1_VISIBLESTRING,
207i2d_ASN1_bio_stream,
208i2d_ASRange,
209i2d_AUTHORITY_INFO_ACCESS,
210i2d_AUTHORITY_KEYID,
211i2d_BASIC_CONSTRAINTS,
212i2d_CERTIFICATEPOLICIES,
213i2d_CMS_ContentInfo,
214i2d_CMS_ReceiptRequest,
215i2d_CMS_bio,
216i2d_CRL_DIST_POINTS,
217i2d_DHxparams,
218i2d_DIRECTORYSTRING,
219i2d_DISPLAYTEXT,
220i2d_DIST_POINT,
221i2d_DIST_POINT_NAME,
222i2d_DSA_SIG,
223i2d_ECDSA_SIG,
224i2d_EDIPARTYNAME,
225i2d_ESS_CERT_ID,
226i2d_ESS_CERT_ID_V2,
227i2d_ESS_ISSUER_SERIAL,
228i2d_ESS_SIGNING_CERT,
229i2d_ESS_SIGNING_CERT_V2,
230i2d_EXTENDED_KEY_USAGE,
231i2d_GENERAL_NAME,
232i2d_GENERAL_NAMES,
233i2d_IPAddressChoice,
234i2d_IPAddressFamily,
235i2d_IPAddressOrRange,
236i2d_IPAddressRange,
237i2d_ISSUER_SIGN_TOOL,
238i2d_ISSUING_DIST_POINT,
239i2d_NAMING_AUTHORITY,
240i2d_NETSCAPE_CERT_SEQUENCE,
241i2d_NETSCAPE_SPKAC,
242i2d_NETSCAPE_SPKI,
243i2d_NOTICEREF,
244i2d_OCSP_BASICRESP,
245i2d_OCSP_CERTID,
246i2d_OCSP_CERTSTATUS,
247i2d_OCSP_CRLID,
248i2d_OCSP_ONEREQ,
249i2d_OCSP_REQINFO,
250i2d_OCSP_REQUEST,
251i2d_OCSP_RESPBYTES,
252i2d_OCSP_RESPDATA,
253i2d_OCSP_RESPID,
254i2d_OCSP_RESPONSE,
255i2d_OCSP_REVOKEDINFO,
256i2d_OCSP_SERVICELOC,
257i2d_OCSP_SIGNATURE,
258i2d_OCSP_SINGLERESP,
259i2d_OSSL_CMP_MSG,
260i2d_OSSL_CMP_PKIHEADER,
261i2d_OSSL_CMP_PKISI,
262i2d_OSSL_CRMF_CERTID,
263i2d_OSSL_CRMF_CERTTEMPLATE,
264i2d_OSSL_CRMF_ENCRYPTEDVALUE,
265i2d_OSSL_CRMF_MSG,
266i2d_OSSL_CRMF_MSGS,
267i2d_OSSL_CRMF_PBMPARAMETER,
268i2d_OSSL_CRMF_PKIPUBLICATIONINFO,
269i2d_OSSL_CRMF_SINGLEPUBINFO,
270i2d_OTHERNAME,
271i2d_PBE2PARAM,
272i2d_PBEPARAM,
273i2d_PBKDF2PARAM,
274i2d_PKCS12,
275i2d_PKCS12_BAGS,
276i2d_PKCS12_MAC_DATA,
277i2d_PKCS12_SAFEBAG,
278i2d_PKCS12_bio,
279i2d_PKCS12_fp,
280i2d_PKCS7,
281i2d_PKCS7_DIGEST,
282i2d_PKCS7_ENCRYPT,
283i2d_PKCS7_ENC_CONTENT,
284i2d_PKCS7_ENVELOPE,
285i2d_PKCS7_ISSUER_AND_SERIAL,
286i2d_PKCS7_NDEF,
287i2d_PKCS7_RECIP_INFO,
288i2d_PKCS7_SIGNED,
289i2d_PKCS7_SIGNER_INFO,
290i2d_PKCS7_SIGN_ENVELOPE,
291i2d_PKCS7_bio,
292i2d_PKCS7_fp,
293i2d_PKCS8PrivateKeyInfo_bio,
294i2d_PKCS8PrivateKeyInfo_fp,
295i2d_PKCS8_PRIV_KEY_INFO,
296i2d_PKCS8_PRIV_KEY_INFO_bio,
297i2d_PKCS8_PRIV_KEY_INFO_fp,
298i2d_PKCS8_bio,
299i2d_PKCS8_fp,
300i2d_PKEY_USAGE_PERIOD,
301i2d_POLICYINFO,
302i2d_POLICYQUALINFO,
303i2d_PROFESSION_INFO,
304i2d_PROXY_CERT_INFO_EXTENSION,
305i2d_PROXY_POLICY,
306i2d_RSA_OAEP_PARAMS,
307i2d_RSA_PSS_PARAMS,
308i2d_SCRYPT_PARAMS,
309i2d_SCT_LIST,
310i2d_SXNET,
311i2d_SXNETID,
312i2d_TS_ACCURACY,
313i2d_TS_MSG_IMPRINT,
314i2d_TS_MSG_IMPRINT_bio,
315i2d_TS_MSG_IMPRINT_fp,
316i2d_TS_REQ,
317i2d_TS_REQ_bio,
318i2d_TS_REQ_fp,
319i2d_TS_RESP,
320i2d_TS_RESP_bio,
321i2d_TS_RESP_fp,
322i2d_TS_STATUS_INFO,
323i2d_TS_TST_INFO,
324i2d_TS_TST_INFO_bio,
325i2d_TS_TST_INFO_fp,
326i2d_USERNOTICE,
327i2d_X509,
328i2d_X509_ALGOR,
329i2d_X509_ALGORS,
330i2d_X509_ATTRIBUTE,
331i2d_X509_CERT_AUX,
332i2d_X509_CINF,
333i2d_X509_CRL,
334i2d_X509_CRL_INFO,
335i2d_X509_CRL_bio,
336i2d_X509_CRL_fp,
337i2d_X509_EXTENSION,
338i2d_X509_EXTENSIONS,
339i2d_X509_NAME,
340i2d_X509_NAME_ENTRY,
341i2d_X509_PUBKEY,
342i2d_X509_PUBKEY_bio,
343i2d_X509_PUBKEY_fp,
344i2d_X509_REQ,
345i2d_X509_REQ_INFO,
346i2d_X509_REQ_bio,
347i2d_X509_REQ_fp,
348i2d_X509_REVOKED,
349i2d_X509_SIG,
350i2d_X509_VAL,
351- convert objects from/to ASN.1/DER representation
352
353=head1 SYNOPSIS
354
355=for openssl generic
356
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);
360
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);
367
368=head1 DESCRIPTION
369
370In the description here, B<I<TYPE>> is used a placeholder
371for any of the OpenSSL datatypes, such as B<X509_CRL>.
372The function parameters I<ppin> and I<ppout> are generally
373either both named I<pp> in the headers, or I<in> and I<out>.
374
375These functions convert OpenSSL objects to and from their ASN.1/DER
376encoding.  Unlike the C structures which can have pointers to sub-objects
377within, the DER is a serialized encoding, suitable for sending over the
378network, writing to a file, and so on.
379
380B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a
381pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to
382the byte following the parsed data.  If I<a> is not NULL then a pointer
383to the returned structure is also written to I<*a>.  If an error occurred
384then NULL is returned.
385
386On a successful return, if I<*a> is not NULL then it is assumed that I<*a>
387contains 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
389B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
390VALUES section).
391
392B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts
393to parse data from BIO I<bp>.
394
395B<d2i_I<TYPE>_fp>() is similar to B<d2i_I<TYPE>>() except it attempts
396to parse data from FILE pointer I<fp>.
397
398B<i2d_I<TYPE>>() encodes the structure pointed to by I<a> into DER format.
399If I<ppout> is not NULL, it writes the DER encoded data to the buffer
400at I<*ppout>, and increments it to point after the data just written.
401If the return value is negative an error occurred, otherwise it
402returns the length of the encoded data.
403
404If I<*ppout> is NULL memory will be allocated for a buffer and the encoded
405data written to it. In this case I<*ppout> is not incremented and it points
406to the start of the data just written.
407
408B<i2d_I<TYPE>_bio>() is similar to B<i2d_I<TYPE>>() except it writes
409the encoding of the structure I<a> to BIO I<bp> and it
410returns 1 for success and 0 for failure.
411
412B<i2d_I<TYPE>_fp>() is similar to B<i2d_I<TYPE>>() except it writes
413the encoding of the structure I<a> to FILE pointer I<fp> and it
414returns 1 for success and 0 for failure.
415
416These routines do not encrypt private keys and therefore offer no
417security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
418
419=head1 NOTES
420
421The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
422"internal" (that is, an internal C structure) and "DER" respectively.
423So B<i2d_I<TYPE>>() converts from internal to DER.
424
425The functions can also understand B<BER> forms.
426
427The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
428populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
429empty structure such as that returned by TYPE_new().
430
431The encoded data is in binary form and may contain embedded zeros.
432Therefore, any FILE pointers or BIOs should be opened in binary mode.
433Functions such as strlen() will B<not> return the correct length
434of the encoded structure.
435
436The ways that I<*ppin> and I<*ppout> are incremented after the operation
437can trap the unwary. See the B<WARNINGS> section for some common
438errors.
439The reason for this-auto increment behaviour is to reflect a typical
440usage of ASN1 functions: after one structure is encoded or decoded
441another will be processed after it.
442
443The following points about the data types might be useful:
444
445=over 4
446
447=item B<ASN1_OBJECT>
448
449Represents an ASN1 OBJECT IDENTIFIER.
450
451=item B<DHparams>
452
453Represents a PKCS#3 DH parameters structure.
454
455=item B<DHxparams>
456
457Represents an ANSI X9.42 DH parameters structure.
458
459=item B<ECDSA_SIG>
460
461Represents an ECDSA signature.
462
463=item B<X509_ALGOR>
464
465Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and
466elsewhere.
467
468=item B<X509_Name>
469
470Represents a B<Name> type as used for subject and issuer names in
471IETF RFC 6960 and elsewhere.
472
473=item B<X509_REQ>
474
475Represents a PKCS#10 certificate request.
476
477=item B<X509_SIG>
478
479Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
480
481=back
482
483=head1 RETURN VALUES
484
485B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
486B<I<TYPE>> structure or NULL if an error occurs.  If the "reuse" capability has
487been used with a valid structure being passed in via I<a>, then the object is
488freed in the event of error and I<*a> is set to NULL.
489
490B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
491value if an error occurs.
492
493B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
494error occurs.
495
496=head1 EXAMPLES
497
498Allocate and encode the DER encoding of an X509 structure:
499
500 int len;
501 unsigned char *buf;
502
503 buf = NULL;
504 len = i2d_X509(x, &buf);
505 if (len < 0)
506     /* error */
507
508Attempt to decode a buffer:
509
510 X509 *x;
511 unsigned char *buf;
512 const unsigned char *p;
513 int len;
514
515 /* Set up buf and len to point to the input buffer. */
516 p = buf;
517 x = d2i_X509(NULL, &p, len);
518 if (x == NULL)
519     /* error */
520
521Alternative technique:
522
523 X509 *x;
524 unsigned char *buf;
525 const unsigned char *p;
526 int len;
527
528 /* Set up buf and len to point to the input buffer. */
529 p = buf;
530 x = NULL;
531
532 if (d2i_X509(&x, &p, len) == NULL)
533     /* error */
534
535=head1 WARNINGS
536
537Using a temporary variable is mandatory. A common
538mistake is to attempt to use a buffer directly as follows:
539
540 int len;
541 unsigned char *buf;
542
543 len = i2d_X509(x, NULL);
544 buf = OPENSSL_malloc(len);
545 ...
546 i2d_X509(x, &buf);
547 ...
548 OPENSSL_free(buf);
549
550This code will result in I<buf> apparently containing garbage because
551it was incremented after the call to point after the data just written.
552Also I<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
553and the subsequent call to OPENSSL_free() is likely to crash.
554
555Another trap to avoid is misuse of the I<a> argument to B<d2i_I<TYPE>>():
556
557 X509 *x;
558
559 if (d2i_X509(&x, &p, len) == NULL)
560     /* error */
561
562This will probably crash somewhere in d2i_X509(). The reason for this
563is that the variable I<x> is uninitialized and an attempt will be made to
564interpret its (invalid) value as an B<X509> structure, typically causing
565a segmentation violation. If I<x> is set to NULL first then this will not
566happen.
567
568=head1 BUGS
569
570In some versions of OpenSSL the "reuse" behaviour of B<d2i_I<TYPE>>() when
571I<*a> is valid is broken and some parts of the reused structure may
572persist if they are not present in the new one. Additionally, in versions of
573OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs
574the behaviour is inconsistent. Some functions behaved as described here, while
575some did not free I<*a> on error and did not set I<*a> to NULL.
576
577As a result of the above issues the "reuse" behaviour is strongly discouraged.
578
579B<i2d_I<TYPE>>() will not return an error in many versions of OpenSSL,
580if mandatory fields are not initialized due to a programming error
581then the encoded structure may contain invalid data or omit the
582fields entirely and will not be parsed by B<d2i_I<TYPE>>(). This may be
583fixed in future so code should not assume that B<i2d_I<TYPE>>() will
584always succeed.
585
586Any function which encodes a structure (B<i2d_I<TYPE>>(),
587B<i2d_I<TYPE>>() or B<i2d_I<TYPE>>()) may return a stale encoding if the
588structure has been modified after deserialization or previous
589serialization. This is because some objects cache the encoding for
590efficiency reasons.
591
592=head1 COPYRIGHT
593
594Copyright 1998-2021 The OpenSSL Project Authors. All Rights Reserved.
595
596Licensed under the Apache License 2.0 (the "License").  You may not use
597this file except in compliance with the License.  You can obtain a copy
598in the file LICENSE in the source distribution or at
599L<https://www.openssl.org/source/license.html>.
600
601=cut
602