xref: /openbsd/lib/libcrypto/man/ASN1_item_d2i.3 (revision 4cfece93) 
1.\"     $OpenBSD: ASN1_item_d2i.3,v 1.8 2018/03/27 17:35:50 schwarze Exp $
2.\"     OpenSSL doc/man3/d2i_X509.pod b97fdb57 Nov 11 09:33:09 2016 +0100
3.\"
4.\" This file is a derived work.
5.\" The changes are covered by the following Copyright and license:
6.\"
7.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
8.\"
9.\" Permission to use, copy, modify, and distribute this software for any
10.\" purpose with or without fee is hereby granted, provided that the above
11.\" copyright notice and this permission notice appear in all copies.
12.\"
13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20.\"
21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
22.\" Copyright (c) 2002, 2003, 2015 The OpenSSL Project.  All rights reserved.
23.\"
24.\" Redistribution and use in source and binary forms, with or without
25.\" modification, are permitted provided that the following conditions
26.\" are met:
27.\"
28.\" 1. Redistributions of source code must retain the above copyright
29.\"    notice, this list of conditions and the following disclaimer.
30.\"
31.\" 2. Redistributions in binary form must reproduce the above copyright
32.\"    notice, this list of conditions and the following disclaimer in
33.\"    the documentation and/or other materials provided with the
34.\"    distribution.
35.\"
36.\" 3. All advertising materials mentioning features or use of this
37.\"    software must display the following acknowledgment:
38.\"    "This product includes software developed by the OpenSSL Project
39.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
40.\"
41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
42.\"    endorse or promote products derived from this software without
43.\"    prior written permission. For written permission, please contact
44.\"    openssl-core@openssl.org.
45.\"
46.\" 5. Products derived from this software may not be called "OpenSSL"
47.\"    nor may "OpenSSL" appear in their names without prior written
48.\"    permission of the OpenSSL Project.
49.\"
50.\" 6. Redistributions of any form whatsoever must retain the following
51.\"    acknowledgment:
52.\"    "This product includes software developed by the OpenSSL Project
53.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
54.\"
55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
58.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
66.\" OF THE POSSIBILITY OF SUCH DAMAGE.
67.\"
68.Dd $Mdocdate: March 27 2018 $
69.Dt ASN1_ITEM_D2I 3
70.Os
71.Sh NAME
72.Nm ASN1_item_d2i ,
73.Nm ASN1_item_d2i_bio ,
74.Nm ASN1_item_d2i_fp ,
75.Nm d2i_ASN1_TYPE ,
76.Nm ASN1_item_i2d ,
77.Nm ASN1_item_i2d_bio ,
78.Nm ASN1_item_i2d_fp ,
79.Nm i2d_ASN1_TYPE ,
80.Nm ASN1_item_dup ,
81.Nm ASN1_item_print
82.Nd decode and encode ASN.1 objects
83.Sh SYNOPSIS
84.In openssl/asn1.h
85.Ft ASN1_VALUE *
86.Fo ASN1_item_d2i
87.Fa "ASN1_VALUE **val_out"
88.Fa "const unsigned char **der_in"
89.Fa "long length"
90.Fa "const ASN1_ITEM *it"
91.Fc
92.Ft void *
93.Fo ASN1_item_d2i_bio
94.Fa "const ASN1_ITEM *it"
95.Fa "BIO *in_bio"
96.Fa "void *val_out"
97.Fc
98.Ft void *
99.Fo ASN1_item_d2i_fp
100.Fa "const ASN1_ITEM *it"
101.Fa "FILE *in_fp"
102.Fa "void *val_out"
103.Fc
104.Ft ASN1_TYPE *
105.Fo d2i_ASN1_TYPE
106.Fa "ASN1_TYPE **val_out"
107.Fa "const unsigned char **der_in"
108.Fa "long length"
109.Fc
110.Ft int
111.Fo ASN1_item_i2d
112.Fa "ASN1_VALUE *val_in"
113.Fa "unsigned char **der_out"
114.Fa "const ASN1_ITEM *it"
115.Fc
116.Ft int
117.Fo ASN1_item_i2d_bio
118.Fa "const ASN1_ITEM *it"
119.Fa "BIO *out_bio"
120.Fa "void *val_in"
121.Fc
122.Ft int
123.Fo ASN1_item_i2d_fp
124.Fa "const ASN1_ITEM *it"
125.Fa "FILE *out_fp"
126.Fa "void *val_in"
127.Fc
128.Ft int
129.Fo i2d_ASN1_TYPE
130.Fa "ASN1_TYPE *val_in"
131.Fa "unsigned char **der_out"
132.Fc
133.Ft void *
134.Fo ASN1_item_dup
135.Fa "const ASN1_ITEM *it"
136.Fa "void *val_in"
137.Fc
138.Ft int
139.Fo ASN1_item_print
140.Fa "BIO *out_bio"
141.Fa "ASN1_VALUE *val_in"
142.Fa "int indent"
143.Fa "const ASN1_ITEM *it"
144.Fa "const ASN1_PCTX *pctx"
145.Fc
146.Sh DESCRIPTION
147These functions convert ASN.1 values from their BER encoding to
148internal C structures
149.Pq Dq d2i
150and vice versa
151.Pq Dq i2d .
152Unlike the C structures which contain pointers to sub-objects, BER
153is a serialized encoding, suitable for transfer over the network
154and for storage in a file.
155.Pp
156.Fn ASN1_item_d2i
157interpretes
158.Pf * Fa der_in
159as a DER- or BER-encoded byte array and decodes one value of type
160.Fa it
161represented by up to
162.Fa length
163bytes.
164If successful,
165.Pf * Fa der_in
166is advanced to the byte following the parsed data.
167.Pp
168If decoding succeeds and
169.Fa val_out
170or
171.Pf * Fa val_out
172is
173.Dv NULL ,
174a new object is allocated.
175.Pp
176If decoding succeeds and
177.Pf * Fa val_out
178is not
179.Dv NULL ,
180it is assumed to point to a valid populated object and an attempt
181is made to reuse it.
182It must not be an empty structure such as one returned by
183.Xr ASN1_item_new 3
184or by one of the various type-specific
185.Fn *_new
186functions.
187This
188.Dq reuse
189capability is present for backward compatibility, but its use is
190strongly discouraged; see the
191.Sx BUGS
192section below.
193.Pp
194.Fn ASN1_item_d2i_bio
195and
196.Fn ASN1_item_d2i_fp
197are similar to
198.Fn ASN1_item_d2i
199except that they read from a
200.Vt BIO
201or
202.Vt FILE ,
203respectively.
204.Pp
205.Fn d2i_ASN1_TYPE
206is similar to
207.Fn ASN1_item_d2i
208except that it does not require a desired type to be specified by
209the user, but instead returns an
210.Vt ASN1_TYPE
211wrapper object containing both the type and the value found in the input.
212.Pp
213.Fn ASN1_item_i2d
214encodes the object pointed to by
215.Fa val_in
216into DER format.
217.Pp
218If
219.Pf * Fa der_out
220is not
221.Dv NULL ,
222it writes the DER-encoded data to the buffer at
223.Pf * Fa der_out
224and increments it to point after the data just written.
225In this case, it is the responsibility of the user to make sure
226that the buffer pointed to by
227.Pf * Fa der_out
228is long enough, such that no buffer owerflow can occur.
229.Pp
230If
231.Pf * Fa der_out
232is
233.Dv NULL ,
234memory is allocated for a buffer, and
235.Pf * Fa der_out
236is not incremented, but points to the start of the data just written.
237.Pp
238If
239.Fa der_out
240is
241.Dv NULL ,
242the encoded bytes are not written anywhere but discarded.
243For
244.Fa val_in
245objects of variable encoding size, this is sometimes used to first
246find the number of bytes that will be written.
247Then, a sufficient amount of memory is allocated before calling
248.Fn ASN1_item_i2d
249again.
250This explicit double-call technique is often not needed because the
251auto-allocation technique described in the previous paragraph can
252be used.
253.Pp
254.Fn ASN1_item_i2d_bio
255and
256.Fn ASN1_item_i2d_fp
257are similar to
258.Fn ASN1_item_i2d
259except that they write to a
260.Vt BIO
261or
262.Vt FILE ,
263respectively.
264.Pp
265.Fn i2d_ASN1_TYPE
266is similar to
267.Fn ASN1_item_i2d
268except that the type and the value are not provided separately,
269but in the form of a single
270.Vt ASN1_TYPE
271object.
272.Pp
273.Fn ASN1_item_dup
274creates a deep copy of
275.Fa val_in
276by calling
277.Fn ASN1_item_i2d
278and
279.Fn ASN1_item_d2i .
280.Sh RETURN VALUES
281If successful,
282.Fn ASN1_item_d2i ,
283.Fn ASN1_item_d2i_bio ,
284.Fn ASN1_item_d2i_fp ,
285and
286.Fn d2i_ASN1_TYPE
287return a pointer to the decoded ASN.1 value.
288In addition, if
289.Fa val_out
290is not
291.Dv NULL ,
292the pointer is also written to
293.Pf * Fa val_out .
294If an error occurs,
295.Dv NULL
296is returned.
297.Pp
298.Fn ASN1_item_i2d
299and
300.Fn i2d_ASN1_TYPE
301return the number of bytes written
302or a negative value if an error occurs.
303.Pp
304.Fn ASN1_item_i2d_bio
305and
306.Fn ASN1_item_i2d_fp
307return 1 for success or 0 for failure.
308.Pp
309.Fn ASN1_item_dup
310returns the new
311.Vt ASN1_VALUE
312object or
313.Dv NULL
314if an error occurs.
315.Sh EXAMPLES
316Many type-specific wrapper functions exist.
317Using those wrappers is recommended in application code
318because it restores part of the type safety that the low-level
319interfaces using
320.Vt ASN1_VALUE
321lack.
322.Pp
323For example, to allocate a buffer and write the DER encoding of an
324.Vt X509
325object into it:
326.Bd -literal -offset indent
327X509		*x;
328unsigned char	*buf;
329int		 len;
330
331buf = NULL;
332len = i2d_X509(x, &buf);
333if (len < 0)
334	/* error */
335.Ed
336.Pp
337Attempt to decode a buffer:
338.Bd -literal -offset indent
339X509		*x;
340unsigned char	*buf, *p;
341int		 len;
342
343/* Set up buf and len to point to the input buffer. */
344p = buf;
345x = d2i_X509(NULL, &p, len);
346if (x == NULL)
347	/* error */
348.Ed
349.Pp
350Equivalent technique:
351.Bd -literal -offset indent
352X509		*x;
353unsigned char	*buf, *p;
354int		 len;
355
356/* Set up buf and len to point to the input buffer. */
357p = buf;
358x = NULL;
359
360if (d2i_X509(&x, &p, len) == NULL)
361	/* error */
362.Ed
363.Sh SEE ALSO
364.Xr ASN1_item_new 3 ,
365.Xr ASN1_TYPE_new 3
366.Sh HISTORY
367.Fn d2i_ASN1_TYPE
368and
369.Fn i2d_ASN1_TYPE
370first appeared in SSLeay 0.5.1 and have been available since
371.Ox 2.4 .
372.Pp
373.Fn ASN1_item_d2i ,
374.Fn ASN1_item_d2i_bio ,
375.Fn ASN1_item_d2i_fp ,
376.Fn ASN1_item_i2d ,
377.Fn ASN1_item_i2d_bio ,
378.Fn ASN1_item_i2d_fp ,
379and
380.Fn ASN1_item_dup
381first appeared in OpenSSL 0.9.7 and have been available since
382.Ox 3.2 .
383.Pp
384.Fn ASN1_item_print
385first appeared in OpenSSL 1.0.0 and has been available since
386.Ox 4.9 .
387.Sh CAVEATS
388If the type described by
389.Fa it
390fails to match the true type of
391.Fa val_in
392or
393.Pf * Fa val_out ,
394buffer overflows and segmentation faults are likely to occur.
395For more details about why the type
396.Vt ASN1_VALUE
397constitutes dangerous user interface design, see
398.Xr ASN1_item_new 3 .
399.Pp
400The encoded data is in binary form and may contain embedded NUL bytes.
401Functions such as
402.Xr strlen 3
403will not return the correct length of the encoded data.
404.Pp
405While the way that
406.Pf * Fa der_in
407and
408.Pf * Fa der_out
409are incremented after the operation supports the typical usage
410patterns of reading or writing one object after another, this
411behaviour can trap the unwary.
412.Pp
413Using a temporary pointer into the buffer is mandatory.
414A common mistake is to attempt to use a buffer directly as follows:
415.Bd -literal -offset indent
416X509		*x;
417unsigned char	*buf;
418int		 len;
419
420len = i2d_X509(x, NULL);
421buf = malloc(len);
422i2d_X509(x, &buf);
423/* do something with buf[] */
424free(buf);
425.Ed
426.Pp
427This code will result in
428.Va buf
429apparently containing garbage because it was incremented during
430.Fn i2d_X509
431to point after the data just written.
432Also
433.Va buf
434will no longer contain the pointer allocated by
435.Xr malloc 3
436and the subsequent call to
437.Xr free 3
438is likely to crash.
439.Pp
440Another trap to avoid is misuse of the
441.Fa val_out
442argument:
443.Bd -literal -offset indent
444X509		*x;
445
446if (d2i_X509(&x, &p, len) == NULL)
447	/* error */
448.Ed
449.Pp
450This will probably crash somewhere in
451.Fn d2i_X509
452because
453.Va x
454is uninitialized and an attempt will be made to interpret its invalid
455content as an
456.Vt X509
457object, typically causing a segmentation violation.
458If
459.Va x
460is set to
461.Dv NULL
462first, then this will not happen.
463.Sh BUGS
464If the
465.Dq reuse
466capability is used, a valid object is passed in via
467.Pf * Fa val_out ,
468and an error occurs, then the object is not freed and may be left
469in an invalid or inconsistent state.
470.Pp
471In some versions of OpenSSL, the
472.Dq reuse
473behaviour is broken such that some parts of the reused object may
474persist if they are not present in the new one.
475.Pp
476In many versions of OpenSSL,
477.Fn ASN1_item_i2d
478will not return an error if mandatory fields are not initialized
479due to a programming error.
480In that case, the encoded structure may contain invalid data and
481some fields may be missing entirely, such that trying to parse it
482with
483.Fn ASN1_item_d2i
484may fail.
485.Pp
486Any function which encodes an object may return a stale encoding
487if the object has been modified after deserialization or previous
488serialization.
489This is because some objects cache the encoding for efficiency reasons.
490