1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
|
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASN1_EXTERN_FUNCS 3ossl"
.TH ASN1_EXTERN_FUNCS 3ossl "2023-09-19" "3.0.11" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ASN1_EXTERN_FUNCS, ASN1_ex_d2i, ASN1_ex_d2i_ex, ASN1_ex_i2d, ASN1_ex_new_func,
ASN1_ex_new_ex_func, ASN1_ex_free_func, ASN1_ex_print_func,
IMPLEMENT_EXTERN_ASN1
\&\- ASN.1 external function support
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/asn1t.h>
\&
\& typedef int ASN1_ex_d2i(ASN1_VALUE **pval, const unsigned char **in, long len,
\& const ASN1_ITEM *it, int tag, int aclass, char opt,
\& ASN1_TLC *ctx);
\& typedef int ASN1_ex_d2i_ex(ASN1_VALUE **pval, const unsigned char **in, long len,
\& const ASN1_ITEM *it, int tag, int aclass, char opt,
\& ASN1_TLC *ctx, OSSL_LIB_CTX *libctx,
\& const char *propq);
\& typedef int ASN1_ex_i2d(const ASN1_VALUE **pval, unsigned char **out,
\& const ASN1_ITEM *it, int tag, int aclass);
\& typedef int ASN1_ex_new_func(ASN1_VALUE **pval, const ASN1_ITEM *it);
\& typedef int ASN1_ex_new_ex_func(ASN1_VALUE **pval, const ASN1_ITEM *it,
\& OSSL_LIB_CTX *libctx, const char *propq);
\& typedef void ASN1_ex_free_func(ASN1_VALUE **pval, const ASN1_ITEM *it);
\& typedef int ASN1_ex_print_func(BIO *out, const ASN1_VALUE **pval,
\& int indent, const char *fname,
\& const ASN1_PCTX *pctx);
\&
\& struct ASN1_EXTERN_FUNCS_st {
\& void *app_data;
\& ASN1_ex_new_func *asn1_ex_new;
\& ASN1_ex_free_func *asn1_ex_free;
\& ASN1_ex_free_func *asn1_ex_clear;
\& ASN1_ex_d2i *asn1_ex_d2i;
\& ASN1_ex_i2d *asn1_ex_i2d;
\& ASN1_ex_print_func *asn1_ex_print;
\& ASN1_ex_new_ex_func *asn1_ex_new_ex;
\& ASN1_ex_d2i_ex *asn1_ex_d2i_ex;
\& };
\& typedef struct ASN1_EXTERN_FUNCS_st ASN1_EXTERN_FUNCS;
\&
\& #define IMPLEMENT_EXTERN_ASN1(sname, tag, fptrs)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1ASN.1\s0 data structures templates are typically defined in OpenSSL using a series
of macros such as \s-1\fBASN1_SEQUENCE\s0()\fR, \s-1\fBASN1_SEQUENCE_END\s0()\fR and so on. Instead
templates can also be defined based entirely on external functions. These
external functions are called to perform operations such as creating a new
\&\fB\s-1ASN1_VALUE\s0\fR or converting an \fB\s-1ASN1_VALUE\s0\fR to or from \s-1DER\s0 encoding.
.PP
The macro \s-1\fBIMPLEMENT_EXTERN_ASN1\s0()\fR can be used to create such an externally
defined structure. The name of the structure should be supplied in the \fIsname\fR
parameter. The tag for the structure (e.g. typically \fBV_ASN1_SEQUENCE\fR) should
be supplied in the \fItag\fR parameter. Finally a pointer to an
\&\fB\s-1ASN1_EXTERN_FUNCS\s0\fR structure should be supplied in the \fIfptrs\fR parameter.
.PP
The \fB\s-1ASN1_EXTERN_FUNCS\s0\fR structure has the following entries.
.IP "\fIapp_data\fR" 4
.IX Item "app_data"
A pointer to arbitrary application specific data.
.IP "\fIasn1_ex_new\fR" 4
.IX Item "asn1_ex_new"
A \*(L"new\*(R" function responsible for constructing a new \fB\s-1ASN1_VALUE\s0\fR object. The
newly constructed value should be stored in \fI*pval\fR. The \fIit\fR parameter is a
pointer to the \fB\s-1ASN1_ITEM\s0\fR template object created via the
\&\s-1\fBIMPLEMENT_EXTERN_ASN1\s0()\fR macro.
.Sp
Returns a positive value on success or 0 on error.
.IP "\fIasn1_ex_free\fR" 4
.IX Item "asn1_ex_free"
A \*(L"free\*(R" function responsible for freeing the \fB\s-1ASN1_VALUE\s0\fR passed in \fI*pval\fR
that was previously allocated via a \*(L"new\*(R" function. The \fIit\fR parameter is a
pointer to the \fB\s-1ASN1_ITEM\s0\fR template object created via the
\&\s-1\fBIMPLEMENT_EXTERN_ASN1\s0()\fR macro.
.IP "\fIasn1_ex_clear\fR" 4
.IX Item "asn1_ex_clear"
A \*(L"clear\*(R" function responsible for clearing any data in the \fB\s-1ASN1_VALUE\s0\fR passed
in \fI*pval\fR and making it suitable for reuse. The \fIit\fR parameter is a pointer
to the \fB\s-1ASN1_ITEM\s0\fR template object created via the \s-1\fBIMPLEMENT_EXTERN_ASN1\s0()\fR
macro.
.IP "\fIasn1_ex_d2i\fR" 4
.IX Item "asn1_ex_d2i"
A \*(L"d2i\*(R" function responsible for converting \s-1DER\s0 data with the tag \fItag\fR and
class \fIclass\fR into an \fB\s-1ASN1_VALUE\s0\fR. If \fI*pval\fR is non-NULL then the
\&\fB\s-1ASN_VALUE\s0\fR it points to should be reused. Otherwise a new \fB\s-1ASN1_VALUE\s0\fR
should be allocated and stored in \fI*pval\fR. \fI*in\fR points to the \s-1DER\s0 data to be
decoded and \fIlen\fR is the length of that data. After decoding \fI*in\fR should be
updated to point at the next byte after the decoded data. If the \fB\s-1ASN1_VALUE\s0\fR
is considered optional in this context then \fIopt\fR will be nonzero. Otherwise
it will be zero. The \fIit\fR parameter is a pointer to the \fB\s-1ASN1_ITEM\s0\fR template
object created via the \s-1\fBIMPLEMENT_EXTERN_ASN1\s0()\fR macro. A pointer to the current
\&\fB\s-1ASN1_TLC\s0\fR context (which may be required for other \s-1ASN1\s0 function calls) is
passed in the \fIctx\fR parameter.
.Sp
The \fIasn1_ex_d2i\fR entry may be \s-1NULL\s0 if \fIasn1_ex_d2i_ex\fR has been specified
instead.
.Sp
Returns <= 0 on error or a positive value on success.
.IP "\fIasn1_ex_i2d\fR" 4
.IX Item "asn1_ex_i2d"
An \*(L"i2d\*(R" function responsible for converting an \fB\s-1ASN1_VALUE\s0\fR into \s-1DER\s0 encoding.
On entry \fI*pval\fR will contain the \fB\s-1ASN1_VALUE\s0\fR to be encoded. If default
tagging is to be used then \fItag\fR will be \-1 on entry. Otherwise if implicit
tagging should be used then \fItag\fR and \fIaclass\fR will be the tag and associated
class.
.Sp
If \fIout\fR is not \s-1NULL\s0 then this function should write the \s-1DER\s0 encoded data to
the buffer in \fI*out\fR, and then increment \fI*out\fR to point to immediately after
the data just written.
.Sp
If \fIout\fR is \s-1NULL\s0 then no data should be written but the length calculated and
returned as if it were.
.Sp
The \fIasn1_ex_i2d\fR entry may be \s-1NULL\s0 if \fIasn1_ex_i2d_ex\fR has been specified
instead.
.Sp
The return value should be negative if a fatal error occurred, or 0 if a
non-fatal error occurred. Otherwise it should return the length of the encoded
data.
.IP "\fIasn1_ex_print\fR" 4
.IX Item "asn1_ex_print"
A \*(L"print\*(R" function. \fIout\fR is the \s-1BIO\s0 to print the output to. \fI*pval\fR is the
\&\fB\s-1ASN1_VALUE\s0\fR to be printed. \fIindent\fR is the number of spaces of indenting to
be printed before any data is printed. \fIfname\fR is currently unused and is
always "". \fIpctx\fR is a pointer to the \fB\s-1ASN1_PCTX\s0\fR for the print operation.
.Sp
Returns 0 on error or a positive value on success. If the return value is 2 then
an additional newline will be printed after the data printed by this function.
.IP "\fIasn1_ex_new_ex\fR" 4
.IX Item "asn1_ex_new_ex"
This is the same as \fIasn1_ex_new\fR except that it is additionally passed the
\&\s-1OSSL_LIB_CTX\s0 to be used in \fIlibctx\fR and any property query string to be used
for algorithm fetching in the \fIpropq\fR parameter. See
\&\*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for further details. If \fIasn1_ex_new_ex\fR is
non \s-1NULL,\s0 then it will always be called in preference to \fIasn1_ex_new\fR.
.IP "\fIasn1_ex_d2i_ex\fR" 4
.IX Item "asn1_ex_d2i_ex"
This is the same as \fIasn1_ex_d2i\fR except that it is additionally passed the
\&\s-1OSSL_LIB_CTX\s0 to be used in \fIlibctx\fR and any property query string to be used
for algorithm fetching in the \fIpropq\fR parameter. See
\&\*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for further details. If \fIasn1_ex_d2i_ex\fR is
non \s-1NULL,\s0 then it will always be called in preference to \fIasn1_ex_d2i\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
Return values for the various callbacks are as described above.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBASN1_item_new_ex\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
The \fIasn1_ex_new_ex\fR and \fIasn1_ex_d2i_ex\fR callbacks were added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.
|
