1ASN1_AUX_CB(3ossl) OpenSSL ASN1_AUX_CB(3ossl)
2
6 ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb,
7 ASN1_aux_const_cb - ASN.1 auxiliary data
8
10 #include <openssl/asn1t.h>
11 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 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 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 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
43 ASN.1 data structures can be associated with an ASN1_AUX object to
44 supply additional information about the ASN.1 structure. An ASN1_AUX
45 structure is associated with the structure during the definition of the
46 ASN.1 template. For example an ASN1_AUX structure will be associated by
47 using one of the various ASN.1 template definition macros that supply
48 auxiliary information such as ASN1_SEQUENCE_enc(), ASN1_SEQUENCE_ref(),
49 ASN1_SEQUENCE_cb_const_cb(), ASN1_SEQUENCE_const_cb(),
50 ASN1_SEQUENCE_cb() or ASN1_NDEF_SEQUENCE_cb().
51 An ASN1_AUX structure contains the following information.
53 app_data
55 Arbitrary application data
56 flags
58 Flags which indicate the auxiliarly functionality supported.
59 The ASN1_AFLG_REFCOUNT flag indicates that objects support
61 reference counting.
62 The ASN1_AFLG_ENCODING flag indicates that the original encoding of
64 the object will be saved.
65 The ASN1_AFLG_BROKEN flag is a work around for broken encoders
67 where the sequence length value may not be correct. This should
68 generally not be used.
69 The ASN1_AFLG_CONST_CB flag indicates that the "const" form of the
71 ASN1_AUX callback should be used in preference to the non-const
72 form.
73 ref_offset
75 If the ASN1_AFLG_REFCOUNT flag is set then this value is assumed to
76 be an offset into the ASN1_VALUE structure where a CRYPTO_REF_COUNT
77 may be found for the purposes of reference counting.
78 ref_lock
80 If the ASN1_AFLG_REFCOUNT flag is set then this value is assumed to
81 be an offset into the ASN1_VALUE structure where a CRYPTO_RWLOCK
82 may be found for the purposes of reference counting.
83 asn1_cb
85 A callback that will be invoked at various points during the
86 processing of the the ASN1_VALLUE. See below for further details.
87 enc_offset
89 Offset into the ASN1_VALUE object where the original encoding of
90 the object will be saved if the ASN1_AFLG_ENCODING flag has been
91 set.
92 asn1_const_cb
94 A callback that will be invoked at various points during the
95 processing of the the ASN1_VALLUE. This is used in preference to
96 the asn1_cb callback if the ASN1_AFLG_CONST_CB flag is set. See
97 below for further details.
98 During the processing of an ASN1_VALUE object the callbacks set via
100 asn1_cb or asn1_const_cb will be invoked as a result of various events
101 indicated via the operation parameter. The value of *in will be the
102 ASN1_VALUE object being processed based on the template in it. An
103 additional operation specific parameter may be passed in exarg. The
104 currently supported operations are as follows. The callbacks should
105 return a positive value on success or zero on error, unless otherwise
106 noted below.
107 ASN1_OP_NEW_PRE
109 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
110 structure prior to an ASN1_VALUE object being allocated. The
111 callback may allocate the ASN1_VALUE itself and store it in *pval.
112 If it does so it should return 2 from the callback. On error it
113 should return 0.
114 ASN1_OP_NEW_POST
116 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
117 structure after an ASN1_VALUE object has been allocated. The
118 allocated object is in *pval.
119 ASN1_OP_FREE_PRE
121 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
122 structure immediately before an ASN1_VALUE is freed. If the
123 callback originally constructed the ASN1_VALUE via ASN1_OP_NEW_PRE
124 then it should free it at this point and return 2 from the
125 callback. Otherwise it should return 1 for success or 0 on error.
126 ASN1_OP_FREE_POST
128 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
129 structure immediately after ASN1_VALUE sub-structures are freed.
130 ASN1_OP_D2I_PRE
132 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
133 structure immediately before a "d2i" operation for the ASN1_VALUE.
134 ASN1_OP_D2I_POST
136 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
137 structure immediately after a "d2i" operation for the ASN1_VALUE.
138 ASN1_OP_I2D_PRE
140 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
141 structure immediately before a "i2d" operation for the ASN1_VALUE.
142 ASN1_OP_I2D_POST
144 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
145 structure immediately after a "i2d" operation for the ASN1_VALUE.
146 ASN1_OP_PRINT_PRE
148 Invoked when processing a SEQUENCE or NDEF_SEQUENCE structure
149 immediately before printing the ASN1_VALUE. The exarg argument will
150 be a pointer to an ASN1_PRINT_ARG structure (see below).
151 ASN1_OP_PRINT_POST
153 Invoked when processing a SEQUENCE or NDEF_SEQUENCE structure
154 immediately after printing the ASN1_VALUE. The exarg argument will
155 be a pointer to an ASN1_PRINT_ARG structure (see below).
156 ASN1_OP_STREAM_PRE
158 Invoked immediately prior to streaming the ASN1_VALUE data using
159 indefinite length encoding. The exarg argument will be a pointer to
160 a ASN1_STREAM_ARG structure (see below).
161 ASN1_OP_STREAM_POST
163 Invoked immediately after streaming the ASN1_VALUE data using
164 indefinite length encoding. The exarg argument will be a pointer to
165 a ASN1_STREAM_ARG structure (see below).
166 ASN1_OP_DETACHED_PRE
168 Invoked immediately prior to processing the ASN1_VALUE data as a
169 "detached" value (as used in CMS and PKCS7). The exarg argument
170 will be a pointer to a ASN1_STREAM_ARG structure (see below).
171 ASN1_OP_DETACHED_POST
173 Invoked immediately after processing the ASN1_VALUE data as a
174 "detached" value (as used in CMS and PKCS7). The exarg argument
175 will be a pointer to a ASN1_STREAM_ARG structure (see below).
176 ASN1_OP_DUP_PRE
178 Invoked immediate prior to an ASN1_VALUE being duplicated via a
179 call to ASN1_item_dup().
180 ASN1_OP_DUP_POST
182 Invoked immediate after to an ASN1_VALUE has been duplicated via a
183 call to ASN1_item_dup().
184 ASN1_OP_GET0_LIBCTX
186 Invoked in order to obtain the OSSL_LIB_CTX associated with an
187 ASN1_VALUE if any. A pointer to an OSSL_LIB_CTX should be stored in
188 *exarg if such a value exists.
189 ASN1_OP_GET0_PROPQ
191 Invoked in order to obtain the property query string associated
192 with an ASN1_VALUE if any. A pointer to the property query string
193 should be stored in *exarg if such a value exists.
194 An ASN1_PRINT_ARG object is used during processing of ASN1_OP_PRINT_PRE
196 and ASN1_OP_PRINT_POST callback operations. It contains the following
197 information.
198 out The BIO being used to print the data out.
200 ndef_bio
202 The current number of indent spaces that should be used for
203 printing this data.
204 pctx
206 The context for the ASN1_PCTX operation.
207 An ASN1_STREAM_ARG object is used during processing of
209 ASN1_OP_STREAM_PRE, ASN1_OP_STREAM_POST, ASN1_OP_DETACHED_PRE and
210 ASN1_OP_DETACHED_POST callback operations. It contains the following
211 information.
212 out The BIO to stream through
214 ndef_bio
216 The BIO with filters appended
217 boundary
219 The streaming I/O boundary.
220
222 The callbacks return 0 on error and a positive value on success. Some
223 operations require specific positive success values as noted above.
224
226 ASN1_item_new_ex(3)
227
229 The ASN1_aux_const_cb() callback and the ASN1_OP_GET0_LIBCTX and
230 ASN1_OP_GET0_PROPQ operation types were added in OpenSSL 3.0.
231
233 Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.
234 Licensed under the Apache License 2.0 (the "License"). You may not use
236 this file except in compliance with the License. You can obtain a copy
237 in the file LICENSE in the source distribution or at
238 <https://www.openssl.org/source/license.html>.
2393.1.1 2023-08-31 ASN1_AUX_CB(3ossl)