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