1ASN1_AUX_CB(3ossl)                  OpenSSL                 ASN1_AUX_CB(3ossl)
2
3
4

NAME

6       ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb,
7       ASN1_aux_const_cb - ASN.1 auxilliary data
8

SYNOPSIS

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

DESCRIPTION

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
53       An ASN1_AUX structure contains the following information.
54
55       app_data
56           Arbitrary application data
57
58       flags
59           Flags which indicate the auxiliarly functionality supported.
60
61           The ASN1_AFLG_REFCOUNT flag indicates that objects support
62           reference counting.
63
64           The ASN1_AFLG_ENCODING flag indicates that the original encoding of
65           the object will be saved.
66
67           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
71           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
75       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
80       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
85       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
89       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
94       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
100       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
109       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
116       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
121       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
128       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
132       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
136       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
140       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
144       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
148       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
153       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
158       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
163       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
168       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
173       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
178       ASN1_OP_DUP_PRE
179           Invoked immediate prior to an ASN1_VALUE being duplicated via a
180           call to ASN1_item_dup().
181
182       ASN1_OP_DUP_POST
183           Invoked immediate after to an ASN1_VALUE has been duplicated via a
184           call to ASN1_item_dup().
185
186       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
191       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
196       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
200       out The BIO being used to print the data out.
201
202       ndef_bio
203           The current number of indent spaces that should be used for
204           printing this data.
205
206       pctx
207           The context for the ASN1_PCTX operation.
208
209       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
214       out The BIO to stream through
215
216       ndef_bio
217           The BIO with filters appended
218
219       boundary
220           The streaming I/O boundary.
221

RETURN VALUES

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

SEE ALSO

227       ASN1_item_new_ex(3)
228

HISTORY

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
236       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>.
240
241
242
2433.0.9                             2023-07-27                ASN1_AUX_CB(3ossl)
Impressum