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-2022 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
