Debian Codegraph @

upstream/debian-unstable/man3/ASN1_item_d2i_bio.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ASN1_ITEM_D2I_BIO 3SSL"
58 .TH ASN1_ITEM_D2I_BIO 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ASN1_item_d2i_ex, ASN1_item_d2i, ASN1_item_d2i_bio_ex, ASN1_item_d2i_bio,
65 ASN1_item_d2i_fp_ex, ASN1_item_d2i_fp, ASN1_item_i2d_mem_bio,
66 ASN1_item_pack, ASN1_item_unpack_ex, ASN1_item_unpack
67 \&\- decode and encode DER\-encoded ASN.1 structures
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/asn1.h>
72 \&
73 \& ASN1_VALUE *ASN1_item_d2i_ex(ASN1_VALUE **pval, const unsigned char **in,
74 \& long len, const ASN1_ITEM *it,
75 \& OSSL_LIB_CTX *libctx, const char *propq);
76 \& ASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **pval, const unsigned char **in,
77 \& long len, const ASN1_ITEM *it);
78 \&
79 \& void *ASN1_item_d2i_bio_ex(const ASN1_ITEM *it, BIO *in, void *x,
80 \& OSSL_LIB_CTX *libctx, const char *propq);
81 \& void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *x);
82 \&
83 \& void *ASN1_item_d2i_fp_ex(const ASN1_ITEM *it, FILE *in, void *x,
84 \& OSSL_LIB_CTX *libctx, const char *propq);
85 \& void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *x);
86 \&
87 \& BIO *ASN1_item_i2d_mem_bio(const ASN1_ITEM *it, const ASN1_VALUE *val);
88 \&
89 \& ASN1_STRING *ASN1_item_pack(void *obj, const ASN1_ITEM *it, ASN1_STRING **oct);
90 \&
91 \& void *ASN1_item_unpack(const ASN1_STRING *oct, const ASN1_ITEM *it);
92 \&
93 \& void *ASN1_item_unpack_ex(const ASN1_STRING *oct, const ASN1_ITEM *it,
94 \& OSSL_LIB_CTX *libctx, const char *propq);
95 .Ve
96 .SH DESCRIPTION
97 .IX Header "DESCRIPTION"
98 \&\fBASN1_item_d2i_ex()\fR decodes the contents of the data stored in \fI*in\fR of length
99 \&\fIlen\fR which must be a DER-encoded ASN.1 structure, using the ASN.1 template
100 \&\fIit\fR. It places the result in \fI*pval\fR unless \fIpval\fR is NULL. If \fI*pval\fR is
101 non-NULL on entry then the \fBASN1_VALUE\fR present there will be reused. Otherwise
102 a new \fBASN1_VALUE\fR will be allocated. If any algorithm fetches are required
103 during the process then they will use the \fBOSSL_LIB_CTX\fRprovided in the
104 \&\fIlibctx\fR parameter and the property query string in \fIpropq\fR. See
105 "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for more information about algorithm fetching.
106 On exit \fI*in\fR will be updated to point to the next byte in the buffer after the
107 decoded structure.
108 .PP
109 \&\fBASN1_item_d2i()\fR is the same as \fBASN1_item_d2i_ex()\fR except that the default
110 OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.
111 .PP
112 \&\fBASN1_item_d2i_bio_ex()\fR decodes the contents of its input BIO \fIin\fR,
113 which must be a DER-encoded ASN.1 structure, using the ASN.1 template \fIit\fR
114 and places the result in \fI*pval\fR unless \fIpval\fR is NULL.
115 If \fIin\fR is NULL it returns NULL, else a pointer to the parsed structure. If any
116 algorithm fetches are required during the process then they will use the
117 \&\fBOSSL_LIB_CTX\fR provided in the \fIlibctx\fR parameter and the property query
118 string in \fIpropq\fR. See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for more information
119 about algorithm fetching.
120 .PP
121 \&\fBASN1_item_d2i_bio()\fR is the same as \fBASN1_item_d2i_bio_ex()\fR except that the
122 default \fBOSSL_LIB_CTX\fR is used (i.e. NULL) and with a NULL property query
123 string.
124 .PP
125 \&\fBASN1_item_d2i_fp_ex()\fR is the same as \fBASN1_item_d2i_bio_ex()\fR except that a FILE
126 pointer is provided instead of a BIO.
127 .PP
128 \&\fBASN1_item_d2i_fp()\fR is the same as \fBASN1_item_d2i_fp_ex()\fR except that the
129 default \fBOSSL_LIB_CTX\fR is used (i.e. NULL) and with a NULL property query
130 string.
131 .PP
132 \&\fBASN1_item_i2d_mem_bio()\fR encodes the given ASN.1 value \fIval\fR
133 using the ASN.1 template \fIit\fR and returns the result in a memory BIO.
134 .PP
135 \&\fBASN1_item_pack()\fR encodes the given ASN.1 value in \fIobj\fR using the
136 ASN.1 template \fIit\fR and returns an \fBASN1_STRING\fR object. If the passed in
137 \&\fI*oct\fR is not NULL then this is used to store the returned result, otherwise
138 a new \fBASN1_STRING\fR object is created. If \fIoct\fR is not NULL and \fI*oct\fR is NULL
139 then the returned return is also set into \fI*oct\fR. If there is an error the optional
140 passed in \fBASN1_STRING\fR will not be freed, but the previous value may be cleared when
141 ASN1_STRING_set0(*oct, NULL, 0) is called internally.
142 .PP
143 \&\fBASN1_item_unpack()\fR uses \fBASN1_item_d2i()\fR to decode the DER-encoded \fBASN1_STRING\fR
144 \&\fIoct\fR using the ASN.1 template \fIit\fR.
145 .PP
146 \&\fBASN1_item_unpack_ex()\fR is similar to \fBASN1_item_unpack()\fR, but uses \fBASN1_item_d2i_ex()\fR so
147 that the \fIlibctx\fR and \fIpropq\fR can be used when doing algorithm fetching.
148 .SH "RETURN VALUES"
149 .IX Header "RETURN VALUES"
150 \&\fBASN1_item_d2i_bio()\fR, \fBASN1_item_unpack_ex()\fR and \fBASN1_item_unpack()\fR return a pointer to
151 an \fBASN1_VALUE\fR or NULL on error.
152 .PP
153 \&\fBASN1_item_i2d_mem_bio()\fR returns a pointer to a memory BIO or NULL on error.
154 .PP
155 \&\fBASN1_item_pack()\fR returns a pointer to an \fBASN1_STRING\fR or NULL on error.
156 .SH HISTORY
157 .IX Header "HISTORY"
158 The functions \fBASN1_item_d2i_ex()\fR, \fBASN1_item_d2i_bio_ex()\fR, \fBASN1_item_d2i_fp_ex()\fR
159 and \fBASN1_item_i2d_mem_bio()\fR were added in OpenSSL 3.0.
160 .PP
161 The function \fBASN1_item_unpack_ex()\fR was added in OpenSSL 3.2.
162 .SH COPYRIGHT
163 .IX Header "COPYRIGHT"
164 Copyright 2021\-2023 The OpenSSL Project Authors. All Rights Reserved.
165 .PP
166 Licensed under the Apache License 2.0 (the "License"). You may not use
167 this file except in compliance with the License. You can obtain a copy
168 in the file LICENSE in the source distribution or at
169 <https://www.openssl.org/source/license.html>.