xref: /freebsd/crypto/openssl/doc/man3/ASN1_aux_cb.pod (revision 7fdf597e96a02165cfe22ff357b857d5fa15ed8a)
1=pod
2
3=head1 NAME
4
5ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb
6- ASN.1 auxiliary data
7
8=head1 SYNOPSIS
9
10 #include <openssl/asn1t.h>
11
12 struct ASN1_AUX_st {
13     void *app_data;
14     int flags;
15     int ref_offset;             /* Offset of reference value */
16     int ref_lock;               /* Offset to an CRYPTO_RWLOCK */
17     ASN1_aux_cb *asn1_cb;
18     int enc_offset;             /* Offset of ASN1_ENCODING structure */
19     ASN1_aux_const_cb *asn1_const_cb; /* for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */
20 };
21 typedef struct ASN1_AUX_st ASN1_AUX;
22
23 struct ASN1_PRINT_ARG_st {
24     BIO *out;
25     int indent;
26     const ASN1_PCTX *pctx;
27 };
28 typedef struct ASN1_PRINT_ARG_st ASN1_PRINT_ARG;
29
30 struct ASN1_STREAM_ARG_st {
31     BIO *out;
32     BIO *ndef_bio;
33     unsigned char **boundary;
34 };
35 typedef struct ASN1_STREAM_ARG_st ASN1_STREAM_ARG;
36
37 typedef int ASN1_aux_cb(int operation, ASN1_VALUE **in, const ASN1_ITEM *it,
38                         void *exarg);
39 typedef int ASN1_aux_const_cb(int operation, const ASN1_VALUE **in,
40                               const ASN1_ITEM *it, void *exarg);
41
42=head1 DESCRIPTION
43
44ASN.1 data structures can be associated with an B<ASN1_AUX> object to supply
45additional information about the ASN.1 structure. An B<ASN1_AUX> structure is
46associated with the structure during the definition of the ASN.1 template. For
47example an B<ASN1_AUX> structure will be associated by using one of the various
48ASN.1 template definition macros that supply auxiliary information such as
49ASN1_SEQUENCE_enc(), ASN1_SEQUENCE_ref(), ASN1_SEQUENCE_cb_const_cb(),
50ASN1_SEQUENCE_const_cb(), ASN1_SEQUENCE_cb() or ASN1_NDEF_SEQUENCE_cb().
51
52An B<ASN1_AUX> structure contains the following information.
53
54=over 4
55
56=item I<app_data>
57
58Arbitrary application data
59
60=item I<flags>
61
62Flags which indicate the auxiliarly functionality supported.
63
64The B<ASN1_AFLG_REFCOUNT> flag indicates that objects support reference counting.
65
66The B<ASN1_AFLG_ENCODING> flag indicates that the original encoding of the
67object will be saved.
68
69The B<ASN1_AFLG_BROKEN> flag is a work around for broken encoders where the
70sequence length value may not be correct. This should generally not be used.
71
72The B<ASN1_AFLG_CONST_CB> flag indicates that the "const" form of the
73B<ASN1_AUX> callback should be used in preference to the non-const form.
74
75=item I<ref_offset>
76
77If the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an
78offset into the B<ASN1_VALUE> structure where a B<CRYPTO_REF_COUNT> may be
79found for the purposes of reference counting.
80
81=item I<ref_lock>
82
83If the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an
84offset into the B<ASN1_VALUE> structure where a B<CRYPTO_RWLOCK> may be
85found for the purposes of reference counting.
86
87=item I<asn1_cb>
88
89A callback that will be invoked at various points during the processing of
90the the B<ASN1_VALLUE>. See below for further details.
91
92=item I<enc_offset>
93
94Offset into the B<ASN1_VALUE> object where the original encoding of the object
95will be saved if the B<ASN1_AFLG_ENCODING> flag has been set.
96
97=item I<asn1_const_cb>
98
99A callback that will be invoked at various points during the processing of
100the the B<ASN1_VALLUE>. This is used in preference to the I<asn1_cb> callback if
101the B<ASN1_AFLG_CONST_CB> flag is set. See below for further details.
102
103=back
104
105During the processing of an B<ASN1_VALUE> object the callbacks set via
106I<asn1_cb> or I<asn1_const_cb> will be invoked as a result of various events
107indicated via the I<operation> parameter. The value of I<*in> will be the
108B<ASN1_VALUE> object being processed based on the template in I<it>. An
109additional operation specific parameter may be passed in I<exarg>. The currently
110supported operations are as follows. The callbacks should return a positive
111value on success or zero on error, unless otherwise noted below.
112
113=over 4
114
115=item B<ASN1_OP_NEW_PRE>
116
117Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
118prior to an B<ASN1_VALUE> object being allocated. The callback may allocate the
119B<ASN1_VALUE> itself and store it in I<*pval>. If it does so it should return 2
120from the callback. On error it should return 0.
121
122=item B<ASN1_OP_NEW_POST>
123
124Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
125after an B<ASN1_VALUE> object has been allocated. The allocated object is in
126I<*pval>.
127
128=item B<ASN1_OP_FREE_PRE>
129
130Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
131immediately before an B<ASN1_VALUE> is freed. If the callback originally
132constructed the B<ASN1_VALUE> via B<ASN1_OP_NEW_PRE> then it should free it at
133this point and return 2 from the callback. Otherwise it should return 1 for
134success or 0 on error.
135
136=item B<ASN1_OP_FREE_POST>
137
138Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
139immediately after B<ASN1_VALUE> sub-structures are freed.
140
141=item B<ASN1_OP_D2I_PRE>
142
143Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
144immediately before a "d2i" operation for the B<ASN1_VALUE>.
145
146=item B<ASN1_OP_D2I_POST>
147
148Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
149immediately after a "d2i" operation for the B<ASN1_VALUE>.
150
151=item B<ASN1_OP_I2D_PRE>
152
153Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
154immediately before a "i2d" operation for the B<ASN1_VALUE>.
155
156=item B<ASN1_OP_I2D_POST>
157
158Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
159immediately after a "i2d" operation for the B<ASN1_VALUE>.
160
161=item B<ASN1_OP_PRINT_PRE>
162
163Invoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately
164before printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an
165B<ASN1_PRINT_ARG> structure (see below).
166
167=item B<ASN1_OP_PRINT_POST>
168
169Invoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately
170after printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an
171B<ASN1_PRINT_ARG> structure (see below).
172
173=item B<ASN1_OP_STREAM_PRE>
174
175Invoked immediately prior to streaming the B<ASN1_VALUE> data using indefinite
176length encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG>
177structure (see below).
178
179=item B<ASN1_OP_STREAM_POST>
180
181Invoked immediately after streaming the B<ASN1_VALUE> data using indefinite
182length encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG>
183structure (see below).
184
185=item B<ASN1_OP_DETACHED_PRE>
186
187Invoked immediately prior to processing the B<ASN1_VALUE> data as a "detached"
188value (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a
189B<ASN1_STREAM_ARG> structure (see below).
190
191=item B<ASN1_OP_DETACHED_POST>
192
193Invoked immediately after processing the B<ASN1_VALUE> data as a "detached"
194value (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a
195B<ASN1_STREAM_ARG> structure (see below).
196
197=item B<ASN1_OP_DUP_PRE>
198
199Invoked immediate prior to an ASN1_VALUE being duplicated via a call to
200ASN1_item_dup().
201
202=item B<ASN1_OP_DUP_POST>
203
204Invoked immediate after to an ASN1_VALUE has been duplicated via a call to
205ASN1_item_dup().
206
207=item B<ASN1_OP_GET0_LIBCTX>
208
209Invoked in order to obtain the B<OSSL_LIB_CTX> associated with an B<ASN1_VALUE>
210if any. A pointer to an B<OSSL_LIB_CTX> should be stored in I<*exarg> if such
211a value exists.
212
213=item B<ASN1_OP_GET0_PROPQ>
214
215Invoked in order to obtain the property query string associated with an
216B<ASN1_VALUE> if any. A pointer to the property query string should be stored in
217I<*exarg> if such a value exists.
218
219=back
220
221An B<ASN1_PRINT_ARG> object is used during processing of B<ASN1_OP_PRINT_PRE>
222and B<ASN1_OP_PRINT_POST> callback operations. It contains the following
223information.
224
225=over 4
226
227=item I<out>
228
229The B<BIO> being used to print the data out.
230
231=item I<ndef_bio>
232
233The current number of indent spaces that should be used for printing this data.
234
235=item I<pctx>
236
237The context for the B<ASN1_PCTX> operation.
238
239=back
240
241An B<ASN1_STREAM_ARG> object is used during processing of B<ASN1_OP_STREAM_PRE>,
242B<ASN1_OP_STREAM_POST>, B<ASN1_OP_DETACHED_PRE> and B<ASN1_OP_DETACHED_POST>
243callback operations. It contains the following information.
244
245=over 4
246
247=item I<out>
248
249The B<BIO> to stream through
250
251=item I<ndef_bio>
252
253The B<BIO> with filters appended
254
255=item I<boundary>
256
257The streaming I/O boundary.
258
259=back
260
261=head1 RETURN VALUES
262
263The callbacks return 0 on error and a positive value on success. Some operations
264require specific positive success values as noted above.
265
266=head1 SEE ALSO
267
268L<ASN1_item_new_ex(3)>
269
270=head1 HISTORY
271
272The ASN1_aux_const_cb() callback and the B<ASN1_OP_GET0_LIBCTX> and
273B<ASN1_OP_GET0_PROPQ> operation types were added in OpenSSL 3.0.
274
275=head1 COPYRIGHT
276
277Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.
278
279Licensed under the Apache License 2.0 (the "License").  You may not use
280this file except in compliance with the License.  You can obtain a copy
281in the file LICENSE in the source distribution or at
282L<https://www.openssl.org/source/license.html>.
283
284=cut
285