1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb 6aa795734SPierre Pronchery- ASN.1 auxiliary data 7b077aed3SPierre Pronchery 8b077aed3SPierre Pronchery=head1 SYNOPSIS 9b077aed3SPierre Pronchery 10b077aed3SPierre Pronchery #include <openssl/asn1t.h> 11b077aed3SPierre Pronchery 12b077aed3SPierre Pronchery struct ASN1_AUX_st { 13b077aed3SPierre Pronchery void *app_data; 14b077aed3SPierre Pronchery int flags; 15b077aed3SPierre Pronchery int ref_offset; /* Offset of reference value */ 16b077aed3SPierre Pronchery int ref_lock; /* Offset to an CRYPTO_RWLOCK */ 17b077aed3SPierre Pronchery ASN1_aux_cb *asn1_cb; 18b077aed3SPierre Pronchery int enc_offset; /* Offset of ASN1_ENCODING structure */ 19b077aed3SPierre Pronchery ASN1_aux_const_cb *asn1_const_cb; /* for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */ 20b077aed3SPierre Pronchery }; 21b077aed3SPierre Pronchery typedef struct ASN1_AUX_st ASN1_AUX; 22b077aed3SPierre Pronchery 23b077aed3SPierre Pronchery struct ASN1_PRINT_ARG_st { 24b077aed3SPierre Pronchery BIO *out; 25b077aed3SPierre Pronchery int indent; 26b077aed3SPierre Pronchery const ASN1_PCTX *pctx; 27b077aed3SPierre Pronchery }; 28b077aed3SPierre Pronchery typedef struct ASN1_PRINT_ARG_st ASN1_PRINT_ARG; 29b077aed3SPierre Pronchery 30b077aed3SPierre Pronchery struct ASN1_STREAM_ARG_st { 31b077aed3SPierre Pronchery BIO *out; 32b077aed3SPierre Pronchery BIO *ndef_bio; 33b077aed3SPierre Pronchery unsigned char **boundary; 34b077aed3SPierre Pronchery }; 35b077aed3SPierre Pronchery typedef struct ASN1_STREAM_ARG_st ASN1_STREAM_ARG; 36b077aed3SPierre Pronchery 37b077aed3SPierre Pronchery typedef int ASN1_aux_cb(int operation, ASN1_VALUE **in, const ASN1_ITEM *it, 38b077aed3SPierre Pronchery void *exarg); 39b077aed3SPierre Pronchery typedef int ASN1_aux_const_cb(int operation, const ASN1_VALUE **in, 40b077aed3SPierre Pronchery const ASN1_ITEM *it, void *exarg); 41b077aed3SPierre Pronchery 42b077aed3SPierre Pronchery=head1 DESCRIPTION 43b077aed3SPierre Pronchery 44b077aed3SPierre ProncheryASN.1 data structures can be associated with an B<ASN1_AUX> object to supply 45b077aed3SPierre Proncheryadditional information about the ASN.1 structure. An B<ASN1_AUX> structure is 46b077aed3SPierre Proncheryassociated with the structure during the definition of the ASN.1 template. For 47b077aed3SPierre Proncheryexample an B<ASN1_AUX> structure will be associated by using one of the various 48aa795734SPierre ProncheryASN.1 template definition macros that supply auxiliary information such as 49b077aed3SPierre ProncheryASN1_SEQUENCE_enc(), ASN1_SEQUENCE_ref(), ASN1_SEQUENCE_cb_const_cb(), 50b077aed3SPierre ProncheryASN1_SEQUENCE_const_cb(), ASN1_SEQUENCE_cb() or ASN1_NDEF_SEQUENCE_cb(). 51b077aed3SPierre Pronchery 52b077aed3SPierre ProncheryAn B<ASN1_AUX> structure contains the following information. 53b077aed3SPierre Pronchery 54b077aed3SPierre Pronchery=over 4 55b077aed3SPierre Pronchery 56b077aed3SPierre Pronchery=item I<app_data> 57b077aed3SPierre Pronchery 58b077aed3SPierre ProncheryArbitrary application data 59b077aed3SPierre Pronchery 60b077aed3SPierre Pronchery=item I<flags> 61b077aed3SPierre Pronchery 62b077aed3SPierre ProncheryFlags which indicate the auxiliarly functionality supported. 63b077aed3SPierre Pronchery 64b077aed3SPierre ProncheryThe B<ASN1_AFLG_REFCOUNT> flag indicates that objects support reference counting. 65b077aed3SPierre Pronchery 66b077aed3SPierre ProncheryThe B<ASN1_AFLG_ENCODING> flag indicates that the original encoding of the 67b077aed3SPierre Proncheryobject will be saved. 68b077aed3SPierre Pronchery 69b077aed3SPierre ProncheryThe B<ASN1_AFLG_BROKEN> flag is a work around for broken encoders where the 70b077aed3SPierre Proncherysequence length value may not be correct. This should generally not be used. 71b077aed3SPierre Pronchery 72b077aed3SPierre ProncheryThe B<ASN1_AFLG_CONST_CB> flag indicates that the "const" form of the 73b077aed3SPierre ProncheryB<ASN1_AUX> callback should be used in preference to the non-const form. 74b077aed3SPierre Pronchery 75b077aed3SPierre Pronchery=item I<ref_offset> 76b077aed3SPierre Pronchery 77b077aed3SPierre ProncheryIf the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an 78b077aed3SPierre Proncheryoffset into the B<ASN1_VALUE> structure where a B<CRYPTO_REF_COUNT> may be 79b077aed3SPierre Proncheryfound for the purposes of reference counting. 80b077aed3SPierre Pronchery 81b077aed3SPierre Pronchery=item I<ref_lock> 82b077aed3SPierre Pronchery 83b077aed3SPierre ProncheryIf the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an 84b077aed3SPierre Proncheryoffset into the B<ASN1_VALUE> structure where a B<CRYPTO_RWLOCK> may be 85b077aed3SPierre Proncheryfound for the purposes of reference counting. 86b077aed3SPierre Pronchery 87b077aed3SPierre Pronchery=item I<asn1_cb> 88b077aed3SPierre Pronchery 89b077aed3SPierre ProncheryA callback that will be invoked at various points during the processing of 90*0d0c8621SEnji Cooperthe B<ASN1_VALUE>. See below for further details. 91b077aed3SPierre Pronchery 92b077aed3SPierre Pronchery=item I<enc_offset> 93b077aed3SPierre Pronchery 94b077aed3SPierre ProncheryOffset into the B<ASN1_VALUE> object where the original encoding of the object 95b077aed3SPierre Proncherywill be saved if the B<ASN1_AFLG_ENCODING> flag has been set. 96b077aed3SPierre Pronchery 97b077aed3SPierre Pronchery=item I<asn1_const_cb> 98b077aed3SPierre Pronchery 99b077aed3SPierre ProncheryA callback that will be invoked at various points during the processing of 100*0d0c8621SEnji Cooperthe B<ASN1_VALUE>. This is used in preference to the I<asn1_cb> callback if 101b077aed3SPierre Proncherythe B<ASN1_AFLG_CONST_CB> flag is set. See below for further details. 102b077aed3SPierre Pronchery 103b077aed3SPierre Pronchery=back 104b077aed3SPierre Pronchery 105b077aed3SPierre ProncheryDuring the processing of an B<ASN1_VALUE> object the callbacks set via 106b077aed3SPierre ProncheryI<asn1_cb> or I<asn1_const_cb> will be invoked as a result of various events 107b077aed3SPierre Proncheryindicated via the I<operation> parameter. The value of I<*in> will be the 108b077aed3SPierre ProncheryB<ASN1_VALUE> object being processed based on the template in I<it>. An 109b077aed3SPierre Proncheryadditional operation specific parameter may be passed in I<exarg>. The currently 110b077aed3SPierre Proncherysupported operations are as follows. The callbacks should return a positive 111b077aed3SPierre Proncheryvalue on success or zero on error, unless otherwise noted below. 112b077aed3SPierre Pronchery 113b077aed3SPierre Pronchery=over 4 114b077aed3SPierre Pronchery 115b077aed3SPierre Pronchery=item B<ASN1_OP_NEW_PRE> 116b077aed3SPierre Pronchery 117b077aed3SPierre ProncheryInvoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure 118b077aed3SPierre Proncheryprior to an B<ASN1_VALUE> object being allocated. The callback may allocate the 119b077aed3SPierre ProncheryB<ASN1_VALUE> itself and store it in I<*pval>. If it does so it should return 2 120b077aed3SPierre Proncheryfrom the callback. On error it should return 0. 121b077aed3SPierre Pronchery 122b077aed3SPierre Pronchery=item B<ASN1_OP_NEW_POST> 123b077aed3SPierre Pronchery 124b077aed3SPierre ProncheryInvoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure 125b077aed3SPierre Proncheryafter an B<ASN1_VALUE> object has been allocated. The allocated object is in 126b077aed3SPierre ProncheryI<*pval>. 127b077aed3SPierre Pronchery 128b077aed3SPierre Pronchery=item B<ASN1_OP_FREE_PRE> 129b077aed3SPierre Pronchery 130b077aed3SPierre ProncheryInvoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure 131b077aed3SPierre Proncheryimmediately before an B<ASN1_VALUE> is freed. If the callback originally 132b077aed3SPierre Proncheryconstructed the B<ASN1_VALUE> via B<ASN1_OP_NEW_PRE> then it should free it at 133b077aed3SPierre Proncherythis point and return 2 from the callback. Otherwise it should return 1 for 134b077aed3SPierre Proncherysuccess or 0 on error. 135b077aed3SPierre Pronchery 136b077aed3SPierre Pronchery=item B<ASN1_OP_FREE_POST> 137b077aed3SPierre Pronchery 138b077aed3SPierre ProncheryInvoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure 139b077aed3SPierre Proncheryimmediately after B<ASN1_VALUE> sub-structures are freed. 140b077aed3SPierre Pronchery 141b077aed3SPierre Pronchery=item B<ASN1_OP_D2I_PRE> 142b077aed3SPierre Pronchery 143b077aed3SPierre ProncheryInvoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure 144b077aed3SPierre Proncheryimmediately before a "d2i" operation for the B<ASN1_VALUE>. 145b077aed3SPierre Pronchery 146b077aed3SPierre Pronchery=item B<ASN1_OP_D2I_POST> 147b077aed3SPierre Pronchery 148b077aed3SPierre ProncheryInvoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure 149b077aed3SPierre Proncheryimmediately after a "d2i" operation for the B<ASN1_VALUE>. 150b077aed3SPierre Pronchery 151b077aed3SPierre Pronchery=item B<ASN1_OP_I2D_PRE> 152b077aed3SPierre Pronchery 153b077aed3SPierre ProncheryInvoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure 154b077aed3SPierre Proncheryimmediately before a "i2d" operation for the B<ASN1_VALUE>. 155b077aed3SPierre Pronchery 156b077aed3SPierre Pronchery=item B<ASN1_OP_I2D_POST> 157b077aed3SPierre Pronchery 158b077aed3SPierre ProncheryInvoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure 159b077aed3SPierre Proncheryimmediately after a "i2d" operation for the B<ASN1_VALUE>. 160b077aed3SPierre Pronchery 161b077aed3SPierre Pronchery=item B<ASN1_OP_PRINT_PRE> 162b077aed3SPierre Pronchery 163b077aed3SPierre ProncheryInvoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately 164b077aed3SPierre Proncherybefore printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an 165b077aed3SPierre ProncheryB<ASN1_PRINT_ARG> structure (see below). 166b077aed3SPierre Pronchery 167b077aed3SPierre Pronchery=item B<ASN1_OP_PRINT_POST> 168b077aed3SPierre Pronchery 169b077aed3SPierre ProncheryInvoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately 170b077aed3SPierre Proncheryafter printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an 171b077aed3SPierre ProncheryB<ASN1_PRINT_ARG> structure (see below). 172b077aed3SPierre Pronchery 173b077aed3SPierre Pronchery=item B<ASN1_OP_STREAM_PRE> 174b077aed3SPierre Pronchery 175b077aed3SPierre ProncheryInvoked immediately prior to streaming the B<ASN1_VALUE> data using indefinite 176b077aed3SPierre Proncherylength encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG> 177b077aed3SPierre Proncherystructure (see below). 178b077aed3SPierre Pronchery 179b077aed3SPierre Pronchery=item B<ASN1_OP_STREAM_POST> 180b077aed3SPierre Pronchery 181b077aed3SPierre ProncheryInvoked immediately after streaming the B<ASN1_VALUE> data using indefinite 182b077aed3SPierre Proncherylength encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG> 183b077aed3SPierre Proncherystructure (see below). 184b077aed3SPierre Pronchery 185b077aed3SPierre Pronchery=item B<ASN1_OP_DETACHED_PRE> 186b077aed3SPierre Pronchery 187b077aed3SPierre ProncheryInvoked immediately prior to processing the B<ASN1_VALUE> data as a "detached" 188b077aed3SPierre Proncheryvalue (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a 189b077aed3SPierre ProncheryB<ASN1_STREAM_ARG> structure (see below). 190b077aed3SPierre Pronchery 191b077aed3SPierre Pronchery=item B<ASN1_OP_DETACHED_POST> 192b077aed3SPierre Pronchery 193b077aed3SPierre ProncheryInvoked immediately after processing the B<ASN1_VALUE> data as a "detached" 194b077aed3SPierre Proncheryvalue (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a 195b077aed3SPierre ProncheryB<ASN1_STREAM_ARG> structure (see below). 196b077aed3SPierre Pronchery 197b077aed3SPierre Pronchery=item B<ASN1_OP_DUP_PRE> 198b077aed3SPierre Pronchery 199b077aed3SPierre ProncheryInvoked immediate prior to an ASN1_VALUE being duplicated via a call to 200b077aed3SPierre ProncheryASN1_item_dup(). 201b077aed3SPierre Pronchery 202b077aed3SPierre Pronchery=item B<ASN1_OP_DUP_POST> 203b077aed3SPierre Pronchery 204b077aed3SPierre ProncheryInvoked immediate after to an ASN1_VALUE has been duplicated via a call to 205b077aed3SPierre ProncheryASN1_item_dup(). 206b077aed3SPierre Pronchery 207b077aed3SPierre Pronchery=item B<ASN1_OP_GET0_LIBCTX> 208b077aed3SPierre Pronchery 209b077aed3SPierre ProncheryInvoked in order to obtain the B<OSSL_LIB_CTX> associated with an B<ASN1_VALUE> 210b077aed3SPierre Proncheryif any. A pointer to an B<OSSL_LIB_CTX> should be stored in I<*exarg> if such 211b077aed3SPierre Proncherya value exists. 212b077aed3SPierre Pronchery 213b077aed3SPierre Pronchery=item B<ASN1_OP_GET0_PROPQ> 214b077aed3SPierre Pronchery 215b077aed3SPierre ProncheryInvoked in order to obtain the property query string associated with an 216b077aed3SPierre ProncheryB<ASN1_VALUE> if any. A pointer to the property query string should be stored in 217b077aed3SPierre ProncheryI<*exarg> if such a value exists. 218b077aed3SPierre Pronchery 219b077aed3SPierre Pronchery=back 220b077aed3SPierre Pronchery 221b077aed3SPierre ProncheryAn B<ASN1_PRINT_ARG> object is used during processing of B<ASN1_OP_PRINT_PRE> 222b077aed3SPierre Proncheryand B<ASN1_OP_PRINT_POST> callback operations. It contains the following 223b077aed3SPierre Proncheryinformation. 224b077aed3SPierre Pronchery 225b077aed3SPierre Pronchery=over 4 226b077aed3SPierre Pronchery 227b077aed3SPierre Pronchery=item I<out> 228b077aed3SPierre Pronchery 229b077aed3SPierre ProncheryThe B<BIO> being used to print the data out. 230b077aed3SPierre Pronchery 231b077aed3SPierre Pronchery=item I<ndef_bio> 232b077aed3SPierre Pronchery 233b077aed3SPierre ProncheryThe current number of indent spaces that should be used for printing this data. 234b077aed3SPierre Pronchery 235b077aed3SPierre Pronchery=item I<pctx> 236b077aed3SPierre Pronchery 237b077aed3SPierre ProncheryThe context for the B<ASN1_PCTX> operation. 238b077aed3SPierre Pronchery 239b077aed3SPierre Pronchery=back 240b077aed3SPierre Pronchery 241b077aed3SPierre ProncheryAn B<ASN1_STREAM_ARG> object is used during processing of B<ASN1_OP_STREAM_PRE>, 242b077aed3SPierre ProncheryB<ASN1_OP_STREAM_POST>, B<ASN1_OP_DETACHED_PRE> and B<ASN1_OP_DETACHED_POST> 243b077aed3SPierre Proncherycallback operations. It contains the following information. 244b077aed3SPierre Pronchery 245b077aed3SPierre Pronchery=over 4 246b077aed3SPierre Pronchery 247b077aed3SPierre Pronchery=item I<out> 248b077aed3SPierre Pronchery 249b077aed3SPierre ProncheryThe B<BIO> to stream through 250b077aed3SPierre Pronchery 251b077aed3SPierre Pronchery=item I<ndef_bio> 252b077aed3SPierre Pronchery 253b077aed3SPierre ProncheryThe B<BIO> with filters appended 254b077aed3SPierre Pronchery 255b077aed3SPierre Pronchery=item I<boundary> 256b077aed3SPierre Pronchery 257b077aed3SPierre ProncheryThe streaming I/O boundary. 258b077aed3SPierre Pronchery 259b077aed3SPierre Pronchery=back 260b077aed3SPierre Pronchery 261b077aed3SPierre Pronchery=head1 RETURN VALUES 262b077aed3SPierre Pronchery 263b077aed3SPierre ProncheryThe callbacks return 0 on error and a positive value on success. Some operations 264b077aed3SPierre Proncheryrequire specific positive success values as noted above. 265b077aed3SPierre Pronchery 266b077aed3SPierre Pronchery=head1 SEE ALSO 267b077aed3SPierre Pronchery 268b077aed3SPierre ProncheryL<ASN1_item_new_ex(3)> 269b077aed3SPierre Pronchery 270b077aed3SPierre Pronchery=head1 HISTORY 271b077aed3SPierre Pronchery 272b077aed3SPierre ProncheryThe ASN1_aux_const_cb() callback and the B<ASN1_OP_GET0_LIBCTX> and 273b077aed3SPierre ProncheryB<ASN1_OP_GET0_PROPQ> operation types were added in OpenSSL 3.0. 274b077aed3SPierre Pronchery 275b077aed3SPierre Pronchery=head1 COPYRIGHT 276b077aed3SPierre Pronchery 277*0d0c8621SEnji CooperCopyright 2021-2025 The OpenSSL Project Authors. All Rights Reserved. 278b077aed3SPierre Pronchery 279b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 280b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 281b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 282b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 283b077aed3SPierre Pronchery 284b077aed3SPierre Pronchery=cut 285