Debian Codegraph @

upstream/debian-unstable/man3/ASN1_aux_cb.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_AUX_CB 3SSL"
58 .TH ASN1_AUX_CB 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_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb
65 \&\- ASN.1 auxiliary data
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/asn1t.h>
70 \&
71 \& struct ASN1_AUX_st {
72 \& void *app_data;
73 \& int flags;
74 \& int ref_offset; /* Offset of reference value */
75 \& int ref_lock; /* Offset to an CRYPTO_RWLOCK */
76 \& ASN1_aux_cb *asn1_cb;
77 \& int enc_offset; /* Offset of ASN1_ENCODING structure */
78 \& ASN1_aux_const_cb *asn1_const_cb; /* for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */
79 \& };
80 \& typedef struct ASN1_AUX_st ASN1_AUX;
81 \&
82 \& struct ASN1_PRINT_ARG_st {
83 \& BIO *out;
84 \& int indent;
85 \& const ASN1_PCTX *pctx;
86 \& };
87 \& typedef struct ASN1_PRINT_ARG_st ASN1_PRINT_ARG;
88 \&
89 \& struct ASN1_STREAM_ARG_st {
90 \& BIO *out;
91 \& BIO *ndef_bio;
92 \& unsigned char **boundary;
93 \& };
94 \& typedef struct ASN1_STREAM_ARG_st ASN1_STREAM_ARG;
95 \&
96 \& typedef int ASN1_aux_cb(int operation, ASN1_VALUE **in, const ASN1_ITEM *it,
97 \& void *exarg);
98 \& typedef int ASN1_aux_const_cb(int operation, const ASN1_VALUE **in,
99 \& const ASN1_ITEM *it, void *exarg);
100 .Ve
101 .SH DESCRIPTION
102 .IX Header "DESCRIPTION"
103 ASN.1 data structures can be associated with an \fBASN1_AUX\fR object to supply
104 additional information about the ASN.1 structure. An \fBASN1_AUX\fR structure is
105 associated with the structure during the definition of the ASN.1 template. For
106 example an \fBASN1_AUX\fR structure will be associated by using one of the various
107 ASN.1 template definition macros that supply auxiliary information such as
108 \&\fBASN1_SEQUENCE_enc()\fR, \fBASN1_SEQUENCE_ref()\fR, \fBASN1_SEQUENCE_cb_const_cb()\fR,
109 \&\fBASN1_SEQUENCE_const_cb()\fR, \fBASN1_SEQUENCE_cb()\fR or \fBASN1_NDEF_SEQUENCE_cb()\fR.
110 .PP
111 An \fBASN1_AUX\fR structure contains the following information.
112 .IP \fIapp_data\fR 4
113 .IX Item "app_data"
114 Arbitrary application data
115 .IP \fIflags\fR 4
116 .IX Item "flags"
117 Flags which indicate the auxiliarly functionality supported.
118 .Sp
119 The \fBASN1_AFLG_REFCOUNT\fR flag indicates that objects support reference counting.
120 .Sp
121 The \fBASN1_AFLG_ENCODING\fR flag indicates that the original encoding of the
122 object will be saved.
123 .Sp
124 The \fBASN1_AFLG_BROKEN\fR flag is a work around for broken encoders where the
125 sequence length value may not be correct. This should generally not be used.
126 .Sp
127 The \fBASN1_AFLG_CONST_CB\fR flag indicates that the "const" form of the
128 \&\fBASN1_AUX\fR callback should be used in preference to the non-const form.
129 .IP \fIref_offset\fR 4
130 .IX Item "ref_offset"
131 If the \fBASN1_AFLG_REFCOUNT\fR flag is set then this value is assumed to be an
132 offset into the \fBASN1_VALUE\fR structure where a \fBCRYPTO_REF_COUNT\fR may be
133 found for the purposes of reference counting.
134 .IP \fIref_lock\fR 4
135 .IX Item "ref_lock"
136 If the \fBASN1_AFLG_REFCOUNT\fR flag is set then this value is assumed to be an
137 offset into the \fBASN1_VALUE\fR structure where a \fBCRYPTO_RWLOCK\fR may be
138 found for the purposes of reference counting.
139 .IP \fIasn1_cb\fR 4
140 .IX Item "asn1_cb"
141 A callback that will be invoked at various points during the processing of
142 the \fBASN1_VALUE\fR. See below for further details.
143 .IP \fIenc_offset\fR 4
144 .IX Item "enc_offset"
145 Offset into the \fBASN1_VALUE\fR object where the original encoding of the object
146 will be saved if the \fBASN1_AFLG_ENCODING\fR flag has been set.
147 .IP \fIasn1_const_cb\fR 4
148 .IX Item "asn1_const_cb"
149 A callback that will be invoked at various points during the processing of
150 the \fBASN1_VALUE\fR. This is used in preference to the \fIasn1_cb\fR callback if
151 the \fBASN1_AFLG_CONST_CB\fR flag is set. See below for further details.
152 .PP
153 During the processing of an \fBASN1_VALUE\fR object the callbacks set via
154 \&\fIasn1_cb\fR or \fIasn1_const_cb\fR will be invoked as a result of various events
155 indicated via the \fIoperation\fR parameter. The value of \fI*in\fR will be the
156 \&\fBASN1_VALUE\fR object being processed based on the template in \fIit\fR. An
157 additional operation specific parameter may be passed in \fIexarg\fR. The currently
158 supported operations are as follows. The callbacks should return a positive
159 value on success or zero on error, unless otherwise noted below.
160 .IP \fBASN1_OP_NEW_PRE\fR 4
161 .IX Item "ASN1_OP_NEW_PRE"
162 Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure
163 prior to an \fBASN1_VALUE\fR object being allocated. The callback may allocate the
164 \&\fBASN1_VALUE\fR itself and store it in \fI*pval\fR. If it does so it should return 2
165 from the callback. On error it should return 0.
166 .IP \fBASN1_OP_NEW_POST\fR 4
167 .IX Item "ASN1_OP_NEW_POST"
168 Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure
169 after an \fBASN1_VALUE\fR object has been allocated. The allocated object is in
170 \&\fI*pval\fR.
171 .IP \fBASN1_OP_FREE_PRE\fR 4
172 .IX Item "ASN1_OP_FREE_PRE"
173 Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure
174 immediately before an \fBASN1_VALUE\fR is freed. If the callback originally
175 constructed the \fBASN1_VALUE\fR via \fBASN1_OP_NEW_PRE\fR then it should free it at
176 this point and return 2 from the callback. Otherwise it should return 1 for
177 success or 0 on error.
178 .IP \fBASN1_OP_FREE_POST\fR 4
179 .IX Item "ASN1_OP_FREE_POST"
180 Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure
181 immediately after \fBASN1_VALUE\fR sub-structures are freed.
182 .IP \fBASN1_OP_D2I_PRE\fR 4
183 .IX Item "ASN1_OP_D2I_PRE"
184 Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure
185 immediately before a "d2i" operation for the \fBASN1_VALUE\fR.
186 .IP \fBASN1_OP_D2I_POST\fR 4
187 .IX Item "ASN1_OP_D2I_POST"
188 Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure
189 immediately after a "d2i" operation for the \fBASN1_VALUE\fR.
190 .IP \fBASN1_OP_I2D_PRE\fR 4
191 .IX Item "ASN1_OP_I2D_PRE"
192 Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure
193 immediately before a "i2d" operation for the \fBASN1_VALUE\fR.
194 .IP \fBASN1_OP_I2D_POST\fR 4
195 .IX Item "ASN1_OP_I2D_POST"
196 Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure
197 immediately after a "i2d" operation for the \fBASN1_VALUE\fR.
198 .IP \fBASN1_OP_PRINT_PRE\fR 4
199 .IX Item "ASN1_OP_PRINT_PRE"
200 Invoked when processing a \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure immediately
201 before printing the \fBASN1_VALUE\fR. The \fIexarg\fR argument will be a pointer to an
202 \&\fBASN1_PRINT_ARG\fR structure (see below).
203 .IP \fBASN1_OP_PRINT_POST\fR 4
204 .IX Item "ASN1_OP_PRINT_POST"
205 Invoked when processing a \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure immediately
206 after printing the \fBASN1_VALUE\fR. The \fIexarg\fR argument will be a pointer to an
207 \&\fBASN1_PRINT_ARG\fR structure (see below).
208 .IP \fBASN1_OP_STREAM_PRE\fR 4
209 .IX Item "ASN1_OP_STREAM_PRE"
210 Invoked immediately prior to streaming the \fBASN1_VALUE\fR data using indefinite
211 length encoding. The \fIexarg\fR argument will be a pointer to a \fBASN1_STREAM_ARG\fR
212 structure (see below).
213 .IP \fBASN1_OP_STREAM_POST\fR 4
214 .IX Item "ASN1_OP_STREAM_POST"
215 Invoked immediately after streaming the \fBASN1_VALUE\fR data using indefinite
216 length encoding. The \fIexarg\fR argument will be a pointer to a \fBASN1_STREAM_ARG\fR
217 structure (see below).
218 .IP \fBASN1_OP_DETACHED_PRE\fR 4
219 .IX Item "ASN1_OP_DETACHED_PRE"
220 Invoked immediately prior to processing the \fBASN1_VALUE\fR data as a "detached"
221 value (as used in CMS and PKCS7). The \fIexarg\fR argument will be a pointer to a
222 \&\fBASN1_STREAM_ARG\fR structure (see below).
223 .IP \fBASN1_OP_DETACHED_POST\fR 4
224 .IX Item "ASN1_OP_DETACHED_POST"
225 Invoked immediately after processing the \fBASN1_VALUE\fR data as a "detached"
226 value (as used in CMS and PKCS7). The \fIexarg\fR argument will be a pointer to a
227 \&\fBASN1_STREAM_ARG\fR structure (see below).
228 .IP \fBASN1_OP_DUP_PRE\fR 4
229 .IX Item "ASN1_OP_DUP_PRE"
230 Invoked immediate prior to an ASN1_VALUE being duplicated via a call to
231 \&\fBASN1_item_dup()\fR.
232 .IP \fBASN1_OP_DUP_POST\fR 4
233 .IX Item "ASN1_OP_DUP_POST"
234 Invoked immediate after to an ASN1_VALUE has been duplicated via a call to
235 \&\fBASN1_item_dup()\fR.
236 .IP \fBASN1_OP_GET0_LIBCTX\fR 4
237 .IX Item "ASN1_OP_GET0_LIBCTX"
238 Invoked in order to obtain the \fBOSSL_LIB_CTX\fR associated with an \fBASN1_VALUE\fR
239 if any. A pointer to an \fBOSSL_LIB_CTX\fR should be stored in \fI*exarg\fR if such
240 a value exists.
241 .IP \fBASN1_OP_GET0_PROPQ\fR 4
242 .IX Item "ASN1_OP_GET0_PROPQ"
243 Invoked in order to obtain the property query string associated with an
244 \&\fBASN1_VALUE\fR if any. A pointer to the property query string should be stored in
245 \&\fI*exarg\fR if such a value exists.
246 .PP
247 An \fBASN1_PRINT_ARG\fR object is used during processing of \fBASN1_OP_PRINT_PRE\fR
248 and \fBASN1_OP_PRINT_POST\fR callback operations. It contains the following
249 information.
250 .IP \fIout\fR 4
251 .IX Item "out"
252 The \fBBIO\fR being used to print the data out.
253 .IP \fIndef_bio\fR 4
254 .IX Item "ndef_bio"
255 The current number of indent spaces that should be used for printing this data.
256 .IP \fIpctx\fR 4
257 .IX Item "pctx"
258 The context for the \fBASN1_PCTX\fR operation.
259 .PP
260 An \fBASN1_STREAM_ARG\fR object is used during processing of \fBASN1_OP_STREAM_PRE\fR,
261 \&\fBASN1_OP_STREAM_POST\fR, \fBASN1_OP_DETACHED_PRE\fR and \fBASN1_OP_DETACHED_POST\fR
262 callback operations. It contains the following information.
263 .IP \fIout\fR 4
264 .IX Item "out"
265 The \fBBIO\fR to stream through
266 .IP \fIndef_bio\fR 4
267 .IX Item "ndef_bio"
268 The \fBBIO\fR with filters appended
269 .IP \fIboundary\fR 4
270 .IX Item "boundary"
271 The streaming I/O boundary.
272 .SH "RETURN VALUES"
273 .IX Header "RETURN VALUES"
274 The callbacks return 0 on error and a positive value on success. Some operations
275 require specific positive success values as noted above.
276 .SH "SEE ALSO"
277 .IX Header "SEE ALSO"
278 \&\fBASN1_item_new_ex\fR\|(3)
279 .SH HISTORY
280 .IX Header "HISTORY"
281 The \fBASN1_aux_const_cb()\fR callback and the \fBASN1_OP_GET0_LIBCTX\fR and
282 \&\fBASN1_OP_GET0_PROPQ\fR operation types were added in OpenSSL 3.0.
283 .SH COPYRIGHT
284 .IX Header "COPYRIGHT"
285 Copyright 2021\-2025 The OpenSSL Project Authors. All Rights Reserved.
286 .PP
287 Licensed under the Apache License 2.0 (the "License"). You may not use
288 this file except in compliance with the License. You can obtain a copy
289 in the file LICENSE in the source distribution or at
290 <https://www.openssl.org/source/license.html>.