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 auxilliary 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 auxilliary information such as ASN1_SEQUENCE_enc(),
49 ASN1_SEQUENCE_ref(), ASN1_SEQUENCE_cb_const_cb(),
50 ASN1_SEQUENCE_const_cb(), ASN1_SEQUENCE_cb() or
51 ASN1_NDEF_SEQUENCE_cb().
52 An ASN1_AUX structure contains the following information.
54 app_data
56 Arbitrary application data
57 flags
59 Flags which indicate the auxiliarly functionality supported.
60 The ASN1_AFLG_REFCOUNT flag indicates that objects support
62 reference counting.
63 The ASN1_AFLG_ENCODING flag indicates that the original encoding of
65 the object will be saved.
66 The ASN1_AFLG_BROKEN flag is a work around for broken encoders
68 where the sequence length value may not be correct. This should
69 generally not be used.
70 The ASN1_AFLG_CONST_CB flag indicates that the "const" form of the
72 ASN1_AUX callback should be used in preference to the non-const
73 form.
74 ref_offset
76 If the ASN1_AFLG_REFCOUNT flag is set then this value is assumed to
77 be an offset into the ASN1_VALUE structure where a CRYPTO_REF_COUNT
78 may be found for the purposes of reference counting.
79 ref_lock
81 If the ASN1_AFLG_REFCOUNT flag is set then this value is assumed to
82 be an offset into the ASN1_VALUE structure where a CRYPTO_RWLOCK
83 may be found for the purposes of reference counting.
84 asn1_cb
86 A callback that will be invoked at various points during the
87 processing of the the ASN1_VALLUE. See below for further details.
88 enc_offset
90 Offset into the ASN1_VALUE object where the original encoding of
91 the object will be saved if the ASN1_AFLG_ENCODING flag has been
92 set.
93 asn1_const_cb
95 A callback that will be invoked at various points during the
96 processing of the the ASN1_VALLUE. This is used in preference to
97 the asn1_cb callback if the ASN1_AFLG_CONST_CB flag is set. See
98 below for further details.
99 During the processing of an ASN1_VALUE object the callbacks set via
101 asn1_cb or asn1_const_cb will be invoked as a result of various events
102 indicated via the operation parameter. The value of *in will be the
103 ASN1_VALUE object being processed based on the template in it. An
104 additional operation specific parameter may be passed in exarg. The
105 currently supported operations are as follows. The callbacks should
106 return a positive value on success or zero on error, unless otherwise
107 noted below.
108 ASN1_OP_NEW_PRE
110 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
111 structure prior to an ASN1_VALUE object being allocated. The
112 callback may allocate the ASN1_VALUE itself and store it in *pval.
113 If it does so it should return 2 from the callback. On error it
114 should return 0.
115 ASN1_OP_NEW_POST
117 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
118 structure after an ASN1_VALUE object has been allocated. The
119 allocated object is in *pval.
120 ASN1_OP_FREE_PRE
122 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
123 structure immediately before an ASN1_VALUE is freed. If the
124 callback originally constructed the ASN1_VALUE via ASN1_OP_NEW_PRE
125 then it should free it at this point and return 2 from the
126 callback. Otherwise it should return 1 for success or 0 on error.
127 ASN1_OP_FREE_POST
129 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
130 structure immediately after ASN1_VALUE sub-structures are freed.
131 ASN1_OP_D2I_PRE
133 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
134 structure immediately before a "d2i" operation for the ASN1_VALUE.
135 ASN1_OP_D2I_POST
137 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
138 structure immediately after a "d2i" operation for the ASN1_VALUE.
139 ASN1_OP_I2D_PRE
141 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
142 structure immediately before a "i2d" operation for the ASN1_VALUE.
143 ASN1_OP_I2D_POST
145 Invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE
146 structure immediately after a "i2d" operation for the ASN1_VALUE.
147 ASN1_OP_PRINT_PRE
149 Invoked when processing a SEQUENCE or NDEF_SEQUENCE structure
150 immediately before printing the ASN1_VALUE. The exarg argument will
151 be a pointer to an ASN1_PRINT_ARG structure (see below).
152 ASN1_OP_PRINT_POST
154 Invoked when processing a SEQUENCE or NDEF_SEQUENCE structure
155 immediately after printing the ASN1_VALUE. The exarg argument will
156 be a pointer to an ASN1_PRINT_ARG structure (see below).
157 ASN1_OP_STREAM_PRE
159 Invoked immediately prior to streaming the ASN1_VALUE data using
160 indefinite length encoding. The exarg argument will be a pointer to
161 a ASN1_STREAM_ARG structure (see below).
162 ASN1_OP_STREAM_POST
164 Invoked immediately after streaming the ASN1_VALUE data using
165 indefinite length encoding. The exarg argument will be a pointer to
166 a ASN1_STREAM_ARG structure (see below).
167 ASN1_OP_DETACHED_PRE
169 Invoked immediately prior to processing the ASN1_VALUE data as a
170 "detached" value (as used in CMS and PKCS7). The exarg argument
171 will be a pointer to a ASN1_STREAM_ARG structure (see below).
172 ASN1_OP_DETACHED_POST
174 Invoked immediately after processing the ASN1_VALUE data as a
175 "detached" value (as used in CMS and PKCS7). The exarg argument
176 will be a pointer to a ASN1_STREAM_ARG structure (see below).
177 ASN1_OP_DUP_PRE
179 Invoked immediate prior to an ASN1_VALUE being duplicated via a
180 call to ASN1_item_dup().
181 ASN1_OP_DUP_POST
183 Invoked immediate after to an ASN1_VALUE has been duplicated via a
184 call to ASN1_item_dup().
185 ASN1_OP_GET0_LIBCTX
187 Invoked in order to obtain the OSSL_LIB_CTX associated with an
188 ASN1_VALUE if any. A pointer to an OSSL_LIB_CTX should be stored in
189 *exarg if such a value exists.
190 ASN1_OP_GET0_PROPQ
192 Invoked in order to obtain the property query string associated
193 with an ASN1_VALUE if any. A pointer to the property query string
194 should be stored in *exarg if such a value exists.
195 An ASN1_PRINT_ARG object is used during processing of ASN1_OP_PRINT_PRE
197 and ASN1_OP_PRINT_POST callback operations. It contains the following
198 information.
199 out The BIO being used to print the data out.
201 ndef_bio
203 The current number of indent spaces that should be used for
204 printing this data.
205 pctx
207 The context for the ASN1_PCTX operation.
208 An ASN1_STREAM_ARG object is used during processing of
210 ASN1_OP_STREAM_PRE, ASN1_OP_STREAM_POST, ASN1_OP_DETACHED_PRE and
211 ASN1_OP_DETACHED_POST callback operations. It contains the following
212 information.
213 out The BIO to stream through
215 ndef_bio
217 The BIO with filters appended
218 boundary
220 The streaming I/O boundary.
221
223 The callbacks return 0 on error and a positive value on success. Some
224 operations require specific positive success values as noted above.
225
227 ASN1_item_new_ex(3)
228
230 The ASN1_aux_const_cb() callback and the ASN1_OP_GET0_LIBCTX and
231 ASN1_OP_GET0_PROPQ operation types were added in OpenSSL 3.0.
232
234 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
235 Licensed under the Apache License 2.0 (the "License"). You may not use
237 this file except in compliance with the License. You can obtain a copy
238 in the file LICENSE in the source distribution or at
239 <https://www.openssl.org/source/license.html>.
2403.0.5 2022-07-05 ASN1_AUX_CB(3ossl)