Debian Codegraph @

upstream/debian-unstable/man3/ASN1_EXTERN_FUNCS.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_EXTERN_FUNCS 3SSL"
58 .TH ASN1_EXTERN_FUNCS 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_EXTERN_FUNCS, ASN1_ex_d2i, ASN1_ex_d2i_ex, ASN1_ex_i2d, ASN1_ex_new_func,
65 ASN1_ex_new_ex_func, ASN1_ex_free_func, ASN1_ex_print_func,
66 IMPLEMENT_EXTERN_ASN1
67 \&\- ASN.1 external function support
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/asn1t.h>
72 \&
73 \& typedef int ASN1_ex_d2i(ASN1_VALUE **pval, const unsigned char **in, long len,
74 \& const ASN1_ITEM *it, int tag, int aclass, char opt,
75 \& ASN1_TLC *ctx);
76 \& typedef int ASN1_ex_d2i_ex(ASN1_VALUE **pval, const unsigned char **in, long len,
77 \& const ASN1_ITEM *it, int tag, int aclass, char opt,
78 \& ASN1_TLC *ctx, OSSL_LIB_CTX *libctx,
79 \& const char *propq);
80 \& typedef int ASN1_ex_i2d(const ASN1_VALUE **pval, unsigned char **out,
81 \& const ASN1_ITEM *it, int tag, int aclass);
82 \& typedef int ASN1_ex_new_func(ASN1_VALUE **pval, const ASN1_ITEM *it);
83 \& typedef int ASN1_ex_new_ex_func(ASN1_VALUE **pval, const ASN1_ITEM *it,
84 \& OSSL_LIB_CTX *libctx, const char *propq);
85 \& typedef void ASN1_ex_free_func(ASN1_VALUE **pval, const ASN1_ITEM *it);
86 \& typedef int ASN1_ex_print_func(BIO *out, const ASN1_VALUE **pval,
87 \& int indent, const char *fname,
88 \& const ASN1_PCTX *pctx);
89 \&
90 \& struct ASN1_EXTERN_FUNCS_st {
91 \& void *app_data;
92 \& ASN1_ex_new_func *asn1_ex_new;
93 \& ASN1_ex_free_func *asn1_ex_free;
94 \& ASN1_ex_free_func *asn1_ex_clear;
95 \& ASN1_ex_d2i *asn1_ex_d2i;
96 \& ASN1_ex_i2d *asn1_ex_i2d;
97 \& ASN1_ex_print_func *asn1_ex_print;
98 \& ASN1_ex_new_ex_func *asn1_ex_new_ex;
99 \& ASN1_ex_d2i_ex *asn1_ex_d2i_ex;
100 \& };
101 \& typedef struct ASN1_EXTERN_FUNCS_st ASN1_EXTERN_FUNCS;
102 \&
103 \& #define IMPLEMENT_EXTERN_ASN1(sname, tag, fptrs)
104 .Ve
105 .SH DESCRIPTION
106 .IX Header "DESCRIPTION"
107 ASN.1 data structures templates are typically defined in OpenSSL using a series
108 of macros such as \fBASN1_SEQUENCE()\fR, \fBASN1_SEQUENCE_END()\fR and so on. Instead
109 templates can also be defined based entirely on external functions. These
110 external functions are called to perform operations such as creating a new
111 \&\fBASN1_VALUE\fR or converting an \fBASN1_VALUE\fR to or from DER encoding.
112 .PP
113 The macro \fBIMPLEMENT_EXTERN_ASN1()\fR can be used to create such an externally
114 defined structure. The name of the structure should be supplied in the \fIsname\fR
115 parameter. The tag for the structure (e.g. typically \fBV_ASN1_SEQUENCE\fR) should
116 be supplied in the \fItag\fR parameter. Finally a pointer to an
117 \&\fBASN1_EXTERN_FUNCS\fR structure should be supplied in the \fIfptrs\fR parameter.
118 .PP
119 The \fBASN1_EXTERN_FUNCS\fR structure has the following entries.
120 .IP \fIapp_data\fR 4
121 .IX Item "app_data"
122 A pointer to arbitrary application specific data.
123 .IP \fIasn1_ex_new\fR 4
124 .IX Item "asn1_ex_new"
125 A "new" function responsible for constructing a new \fBASN1_VALUE\fR object. The
126 newly constructed value should be stored in \fI*pval\fR. The \fIit\fR parameter is a
127 pointer to the \fBASN1_ITEM\fR template object created via the
128 \&\fBIMPLEMENT_EXTERN_ASN1()\fR macro.
129 .Sp
130 Returns a positive value on success or 0 on error.
131 .IP \fIasn1_ex_free\fR 4
132 .IX Item "asn1_ex_free"
133 A "free" function responsible for freeing the \fBASN1_VALUE\fR passed in \fI*pval\fR
134 that was previously allocated via a "new" function. The \fIit\fR parameter is a
135 pointer to the \fBASN1_ITEM\fR template object created via the
136 \&\fBIMPLEMENT_EXTERN_ASN1()\fR macro.
137 .IP \fIasn1_ex_clear\fR 4
138 .IX Item "asn1_ex_clear"
139 A "clear" function responsible for clearing any data in the \fBASN1_VALUE\fR passed
140 in \fI*pval\fR and making it suitable for reuse. The \fIit\fR parameter is a pointer
141 to the \fBASN1_ITEM\fR template object created via the \fBIMPLEMENT_EXTERN_ASN1()\fR
142 macro.
143 .IP \fIasn1_ex_d2i\fR 4
144 .IX Item "asn1_ex_d2i"
145 A "d2i" function responsible for converting DER data with the tag \fItag\fR and
146 class \fIclass\fR into an \fBASN1_VALUE\fR. If \fI*pval\fR is non-NULL then the
147 \&\fBASN_VALUE\fR it points to should be reused. Otherwise a new \fBASN1_VALUE\fR
148 should be allocated and stored in \fI*pval\fR. \fI*in\fR points to the DER data to be
149 decoded and \fIlen\fR is the length of that data. After decoding \fI*in\fR should be
150 updated to point at the next byte after the decoded data. If the \fBASN1_VALUE\fR
151 is considered optional in this context then \fIopt\fR will be nonzero. Otherwise
152 it will be zero. The \fIit\fR parameter is a pointer to the \fBASN1_ITEM\fR template
153 object created via the \fBIMPLEMENT_EXTERN_ASN1()\fR macro. A pointer to the current
154 \&\fBASN1_TLC\fR context (which may be required for other ASN1 function calls) is
155 passed in the \fIctx\fR parameter.
156 .Sp
157 The \fIasn1_ex_d2i\fR entry may be NULL if \fIasn1_ex_d2i_ex\fR has been specified
158 instead.
159 .Sp
160 Returns <= 0 on error or a positive value on success.
161 .IP \fIasn1_ex_i2d\fR 4
162 .IX Item "asn1_ex_i2d"
163 An "i2d" function responsible for converting an \fBASN1_VALUE\fR into DER encoding.
164 On entry \fI*pval\fR will contain the \fBASN1_VALUE\fR to be encoded. If default
165 tagging is to be used then \fItag\fR will be \-1 on entry. Otherwise if implicit
166 tagging should be used then \fItag\fR and \fIaclass\fR will be the tag and associated
167 class.
168 .Sp
169 If \fIout\fR is not NULL then this function should write the DER encoded data to
170 the buffer in \fI*out\fR, and then increment \fI*out\fR to point to immediately after
171 the data just written.
172 .Sp
173 If \fIout\fR is NULL then no data should be written but the length calculated and
174 returned as if it were.
175 .Sp
176 The \fIasn1_ex_i2d\fR entry may be NULL if \fIasn1_ex_i2d_ex\fR has been specified
177 instead.
178 .Sp
179 The return value should be negative if a fatal error occurred, or 0 if a
180 non-fatal error occurred. Otherwise it should return the length of the encoded
181 data.
182 .IP \fIasn1_ex_print\fR 4
183 .IX Item "asn1_ex_print"
184 A "print" function. \fIout\fR is the BIO to print the output to. \fI*pval\fR is the
185 \&\fBASN1_VALUE\fR to be printed. \fIindent\fR is the number of spaces of indenting to
186 be printed before any data is printed. \fIfname\fR is currently unused and is
187 always "". \fIpctx\fR is a pointer to the \fBASN1_PCTX\fR for the print operation.
188 .Sp
189 Returns 0 on error or a positive value on success. If the return value is 2 then
190 an additional newline will be printed after the data printed by this function.
191 .IP \fIasn1_ex_new_ex\fR 4
192 .IX Item "asn1_ex_new_ex"
193 This is the same as \fIasn1_ex_new\fR except that it is additionally passed the
194 OSSL_LIB_CTX to be used in \fIlibctx\fR and any property query string to be used
195 for algorithm fetching in the \fIpropq\fR parameter. See
196 "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further details. If \fIasn1_ex_new_ex\fR is
197 non NULL, then it will always be called in preference to \fIasn1_ex_new\fR.
198 .IP \fIasn1_ex_d2i_ex\fR 4
199 .IX Item "asn1_ex_d2i_ex"
200 This is the same as \fIasn1_ex_d2i\fR except that it is additionally passed the
201 OSSL_LIB_CTX to be used in \fIlibctx\fR and any property query string to be used
202 for algorithm fetching in the \fIpropq\fR parameter. See
203 "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further details. If \fIasn1_ex_d2i_ex\fR is
204 non NULL, then it will always be called in preference to \fIasn1_ex_d2i\fR.
205 .SH "RETURN VALUES"
206 .IX Header "RETURN VALUES"
207 Return values for the various callbacks are as described above.
208 .SH "SEE ALSO"
209 .IX Header "SEE ALSO"
210 \&\fBASN1_item_new_ex\fR\|(3)
211 .SH HISTORY
212 .IX Header "HISTORY"
213 The \fIasn1_ex_new_ex\fR and \fIasn1_ex_d2i_ex\fR callbacks were added in OpenSSL 3.0.
214 .SH COPYRIGHT
215 .IX Header "COPYRIGHT"
216 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
217 .PP
218 Licensed under the Apache License 2.0 (the "License"). You may not use
219 this file except in compliance with the License. You can obtain a copy
220 in the file LICENSE in the source distribution or at
221 <https://www.openssl.org/source/license.html>.