doc/man3/ASN1_aux_cb.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ASN1_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
  44 ASN.1 data structures can be associated with an B<ASN1_AUX> object to supply
  45 additional information about the ASN.1 structure. An B<ASN1_AUX> structure is
  46 associated with the structure during the definition of the ASN.1 template. For
  47 example an B<ASN1_AUX> structure will be associated by using one of the various
  48 ASN.1 template definition macros that supply auxiliary information such as
  49 ASN1_SEQUENCE_enc(), ASN1_SEQUENCE_ref(), ASN1_SEQUENCE_cb_const_cb(),
  50 ASN1_SEQUENCE_const_cb(), ASN1_SEQUENCE_cb() or ASN1_NDEF_SEQUENCE_cb().
  51
  52 An B<ASN1_AUX> structure contains the following information.
  53
  54 =over 4
  55
  56 =item I<app_data>
  57
  58 Arbitrary application data
  59
  60 =item I<flags>
  61
  62 Flags which indicate the auxiliarly functionality supported.
  63
  64 The B<ASN1_AFLG_REFCOUNT> flag indicates that objects support reference counting.
  65
  66 The B<ASN1_AFLG_ENCODING> flag indicates that the original encoding of the
  67 object will be saved.
  68
  69 The B<ASN1_AFLG_BROKEN> flag is a work around for broken encoders where the
  70 sequence length value may not be correct. This should generally not be used.
  71
  72 The B<ASN1_AFLG_CONST_CB> flag indicates that the "const" form of the
  73 B<ASN1_AUX> callback should be used in preference to the non-const form.
  74
  75 =item I<ref_offset>
  76
  77 If the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an
  78 offset into the B<ASN1_VALUE> structure where a B<CRYPTO_REF_COUNT> may be
  79 found for the purposes of reference counting.
  80
  81 =item I<ref_lock>
  82
  83 If the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an
  84 offset into the B<ASN1_VALUE> structure where a B<CRYPTO_RWLOCK> may be
  85 found for the purposes of reference counting.
  86
  87 =item I<asn1_cb>
  88
  89 A callback that will be invoked at various points during the processing of
  90 the the B<ASN1_VALLUE>. See below for further details.
  91
  92 =item I<enc_offset>
  93
  94 Offset into the B<ASN1_VALUE> object where the original encoding of the object
  95 will be saved if the B<ASN1_AFLG_ENCODING> flag has been set.
  96
  97 =item I<asn1_const_cb>
  98
  99 A callback that will be invoked at various points during the processing of
 100 the the B<ASN1_VALLUE>. This is used in preference to the I<asn1_cb> callback if
 101 the B<ASN1_AFLG_CONST_CB> flag is set. See below for further details.
 102
 103 =back
 104
 105 During the processing of an B<ASN1_VALUE> object the callbacks set via
 106 I<asn1_cb> or I<asn1_const_cb> will be invoked as a result of various events
 107 indicated via the I<operation> parameter. The value of I<*in> will be the
 108 B<ASN1_VALUE> object being processed based on the template in I<it>. An
 109 additional operation specific parameter may be passed in I<exarg>. The currently
 110 supported operations are as follows. The callbacks should return a positive
 111 value on success or zero on error, unless otherwise noted below.
 112
 113 =over 4
 114
 115 =item B<ASN1_OP_NEW_PRE>
 116
 117 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 118 prior to an B<ASN1_VALUE> object being allocated. The callback may allocate the
 119 B<ASN1_VALUE> itself and store it in I<*pval>. If it does so it should return 2
 120 from the callback. On error it should return 0.
 121
 122 =item B<ASN1_OP_NEW_POST>
 123
 124 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 125 after an B<ASN1_VALUE> object has been allocated. The allocated object is in
 126 I<*pval>.
 127
 128 =item B<ASN1_OP_FREE_PRE>
 129
 130 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 131 immediately before an B<ASN1_VALUE> is freed. If the callback originally
 132 constructed the B<ASN1_VALUE> via B<ASN1_OP_NEW_PRE> then it should free it at
 133 this point and return 2 from the callback. Otherwise it should return 1 for
 134 success or 0 on error.
 135
 136 =item B<ASN1_OP_FREE_POST>
 137
 138 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 139 immediately after B<ASN1_VALUE> sub-structures are freed.
 140
 141 =item B<ASN1_OP_D2I_PRE>
 142
 143 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 144 immediately before a "d2i" operation for the B<ASN1_VALUE>.
 145
 146 =item B<ASN1_OP_D2I_POST>
 147
 148 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 149 immediately after a "d2i" operation for the B<ASN1_VALUE>.
 150
 151 =item B<ASN1_OP_I2D_PRE>
 152
 153 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 154 immediately before a "i2d" operation for the B<ASN1_VALUE>.
 155
 156 =item B<ASN1_OP_I2D_POST>
 157
 158 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 159 immediately after a "i2d" operation for the B<ASN1_VALUE>.
 160
 161 =item B<ASN1_OP_PRINT_PRE>
 162
 163 Invoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately
 164 before printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an
 165 B<ASN1_PRINT_ARG> structure (see below).
 166
 167 =item B<ASN1_OP_PRINT_POST>
 168
 169 Invoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately
 170 after printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an
 171 B<ASN1_PRINT_ARG> structure (see below).
 172
 173 =item B<ASN1_OP_STREAM_PRE>
 174
 175 Invoked immediately prior to streaming the B<ASN1_VALUE> data using indefinite
 176 length encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG>
 177 structure (see below).
 178
 179 =item B<ASN1_OP_STREAM_POST>
 180
 181 Invoked immediately after streaming the B<ASN1_VALUE> data using indefinite
 182 length encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG>
 183 structure (see below).
 184
 185 =item B<ASN1_OP_DETACHED_PRE>
 186
 187 Invoked immediately prior to processing the B<ASN1_VALUE> data as a "detached"
 188 value (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a
 189 B<ASN1_STREAM_ARG> structure (see below).
 190
 191 =item B<ASN1_OP_DETACHED_POST>
 192
 193 Invoked immediately after processing the B<ASN1_VALUE> data as a "detached"
 194 value (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a
 195 B<ASN1_STREAM_ARG> structure (see below).
 196
 197 =item B<ASN1_OP_DUP_PRE>
 198
 199 Invoked immediate prior to an ASN1_VALUE being duplicated via a call to
 200 ASN1_item_dup().
 201
 202 =item B<ASN1_OP_DUP_POST>
 203
 204 Invoked immediate after to an ASN1_VALUE has been duplicated via a call to
 205 ASN1_item_dup().
 206
 207 =item B<ASN1_OP_GET0_LIBCTX>
 208
 209 Invoked in order to obtain the B<OSSL_LIB_CTX> associated with an B<ASN1_VALUE>
 210 if any. A pointer to an B<OSSL_LIB_CTX> should be stored in I<*exarg> if such
 211 a value exists.
 212
 213 =item B<ASN1_OP_GET0_PROPQ>
 214
 215 Invoked in order to obtain the property query string associated with an
 216 B<ASN1_VALUE> if any. A pointer to the property query string should be stored in
 217 I<*exarg> if such a value exists.
 218
 219 =back
 220
 221 An B<ASN1_PRINT_ARG> object is used during processing of B<ASN1_OP_PRINT_PRE>
 222 and B<ASN1_OP_PRINT_POST> callback operations. It contains the following
 223 information.
 224
 225 =over 4
 226
 227 =item I<out>
 228
 229 The B<BIO> being used to print the data out.
 230
 231 =item I<ndef_bio>
 232
 233 The current number of indent spaces that should be used for printing this data.
 234
 235 =item I<pctx>
 236
 237 The context for the B<ASN1_PCTX> operation.
 238
 239 =back
 240
 241 An B<ASN1_STREAM_ARG> object is used during processing of B<ASN1_OP_STREAM_PRE>,
 242 B<ASN1_OP_STREAM_POST>, B<ASN1_OP_DETACHED_PRE> and B<ASN1_OP_DETACHED_POST>
 243 callback operations. It contains the following information.
 244
 245 =over 4
 246
 247 =item I<out>
 248
 249 The B<BIO> to stream through
 250
 251 =item I<ndef_bio>
 252
 253 The B<BIO> with filters appended
 254
 255 =item I<boundary>
 256
 257 The streaming I/O boundary.
 258
 259 =back
 260
 261 =head1 RETURN VALUES
 262
 263 The callbacks return 0 on error and a positive value on success. Some operations
 264 require specific positive success values as noted above.
 265
 266 =head1 SEE ALSO
 267
 268 L<ASN1_item_new_ex(3)>
 269
 270 =head1 HISTORY
 271
 272 The ASN1_aux_const_cb() callback and the B<ASN1_OP_GET0_LIBCTX> and
 273 B<ASN1_OP_GET0_PROPQ> operation types were added in OpenSSL 3.0.
 274
 275 =head1 COPYRIGHT
 276
 277 Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.
 278
 279 Licensed under the Apache License 2.0 (the "License").  You may not use
 280 this file except in compliance with the License.  You can obtain a copy
 281 in the file LICENSE in the source distribution or at
 282 L<https://www.openssl.org/source/license.html>.
 283
 284 =cut