doc/man3/ASN1_aux_cb.pod - third_party/openssl - Git at Google

 =pod

 =head1 NAME

 ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb
 - ASN.1 auxiliary data

 =head1 SYNOPSIS

  #include <openssl/asn1t.h>

  struct ASN1_AUX_st {
      void *app_data;
      int flags;
      int ref_offset;             /* Offset of reference value */
      int ref_lock;               /* Offset to an CRYPTO_RWLOCK */
      ASN1_aux_cb *asn1_cb;
      int enc_offset;             /* Offset of ASN1_ENCODING structure */
      ASN1_aux_const_cb *asn1_const_cb; /* for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */
  };
  typedef struct ASN1_AUX_st ASN1_AUX;

  struct ASN1_PRINT_ARG_st {
      BIO *out;
      int indent;
      const ASN1_PCTX *pctx;
  };
  typedef struct ASN1_PRINT_ARG_st ASN1_PRINT_ARG;

  struct ASN1_STREAM_ARG_st {
      BIO *out;
      BIO *ndef_bio;
      unsigned char **boundary;
  };
  typedef struct ASN1_STREAM_ARG_st ASN1_STREAM_ARG;

  typedef int ASN1_aux_cb(int operation, ASN1_VALUE **in, const ASN1_ITEM *it,
                          void *exarg);
  typedef int ASN1_aux_const_cb(int operation, const ASN1_VALUE **in,
                                const ASN1_ITEM *it, void *exarg);

 =head1 DESCRIPTION

 ASN.1 data structures can be associated with an B<ASN1_AUX> object to supply
 additional information about the ASN.1 structure. An B<ASN1_AUX> structure is
 associated with the structure during the definition of the ASN.1 template. For
 example an B<ASN1_AUX> structure will be associated by using one of the various
 ASN.1 template definition macros that supply auxiliary information such as
 ASN1_SEQUENCE_enc(), ASN1_SEQUENCE_ref(), ASN1_SEQUENCE_cb_const_cb(),
 ASN1_SEQUENCE_const_cb(), ASN1_SEQUENCE_cb() or ASN1_NDEF_SEQUENCE_cb().

 An B<ASN1_AUX> structure contains the following information.

 =over 4

 =item I<app_data>

 Arbitrary application data

 =item I<flags>

 Flags which indicate the auxiliarly functionality supported.

 The B<ASN1_AFLG_REFCOUNT> flag indicates that objects support reference counting.

 The B<ASN1_AFLG_ENCODING> flag indicates that the original encoding of the
 object will be saved.

 The B<ASN1_AFLG_BROKEN> flag is a work around for broken encoders where the
 sequence length value may not be correct. This should generally not be used.

 The B<ASN1_AFLG_CONST_CB> flag indicates that the "const" form of the
 B<ASN1_AUX> callback should be used in preference to the non-const form.

 =item I<ref_offset>

 If the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an
 offset into the B<ASN1_VALUE> structure where a B<CRYPTO_REF_COUNT> may be
 found for the purposes of reference counting.

 =item I<ref_lock>

 If the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an
 offset into the B<ASN1_VALUE> structure where a B<CRYPTO_RWLOCK> may be
 found for the purposes of reference counting.

 =item I<asn1_cb>

 A callback that will be invoked at various points during the processing of
 the the B<ASN1_VALLUE>. See below for further details.

 =item I<enc_offset>

 Offset into the B<ASN1_VALUE> object where the original encoding of the object
 will be saved if the B<ASN1_AFLG_ENCODING> flag has been set.

 =item I<asn1_const_cb>

 A callback that will be invoked at various points during the processing of
 the the B<ASN1_VALLUE>. This is used in preference to the I<asn1_cb> callback if
 the B<ASN1_AFLG_CONST_CB> flag is set. See below for further details.

 =back

 During the processing of an B<ASN1_VALUE> object the callbacks set via
 I<asn1_cb> or I<asn1_const_cb> will be invoked as a result of various events
 indicated via the I<operation> parameter. The value of I<*in> will be the
 B<ASN1_VALUE> object being processed based on the template in I<it>. An
 additional operation specific parameter may be passed in I<exarg>. The currently
 supported operations are as follows. The callbacks should return a positive
 value on success or zero on error, unless otherwise noted below.

 =over 4

 =item B<ASN1_OP_NEW_PRE>

 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 prior to an B<ASN1_VALUE> object being allocated. The callback may allocate the
 B<ASN1_VALUE> itself and store it in I<*pval>. If it does so it should return 2
 from the callback. On error it should return 0.

 =item B<ASN1_OP_NEW_POST>

 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 after an B<ASN1_VALUE> object has been allocated. The allocated object is in
 I<*pval>.

 =item B<ASN1_OP_FREE_PRE>

 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 immediately before an B<ASN1_VALUE> is freed. If the callback originally
 constructed the B<ASN1_VALUE> via B<ASN1_OP_NEW_PRE> then it should free it at
 this point and return 2 from the callback. Otherwise it should return 1 for
 success or 0 on error.

 =item B<ASN1_OP_FREE_POST>

 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 immediately after B<ASN1_VALUE> sub-structures are freed.

 =item B<ASN1_OP_D2I_PRE>

 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 immediately before a "d2i" operation for the B<ASN1_VALUE>.

 =item B<ASN1_OP_D2I_POST>

 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 immediately after a "d2i" operation for the B<ASN1_VALUE>.

 =item B<ASN1_OP_I2D_PRE>

 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 immediately before a "i2d" operation for the B<ASN1_VALUE>.

 =item B<ASN1_OP_I2D_POST>

 Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
 immediately after a "i2d" operation for the B<ASN1_VALUE>.

 =item B<ASN1_OP_PRINT_PRE>

 Invoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately
 before printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an
 B<ASN1_PRINT_ARG> structure (see below).

 =item B<ASN1_OP_PRINT_POST>

 Invoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately
 after printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an
 B<ASN1_PRINT_ARG> structure (see below).

 =item B<ASN1_OP_STREAM_PRE>

 Invoked immediately prior to streaming the B<ASN1_VALUE> data using indefinite
 length encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG>
 structure (see below).

 =item B<ASN1_OP_STREAM_POST>

 Invoked immediately after streaming the B<ASN1_VALUE> data using indefinite
 length encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG>
 structure (see below).

 =item B<ASN1_OP_DETACHED_PRE>

 Invoked immediately prior to processing the B<ASN1_VALUE> data as a "detached"
 value (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a
 B<ASN1_STREAM_ARG> structure (see below).

 =item B<ASN1_OP_DETACHED_POST>

 Invoked immediately after processing the B<ASN1_VALUE> data as a "detached"
 value (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a
 B<ASN1_STREAM_ARG> structure (see below).

 =item B<ASN1_OP_DUP_PRE>

 Invoked immediate prior to an ASN1_VALUE being duplicated via a call to
 ASN1_item_dup().

 =item B<ASN1_OP_DUP_POST>

 Invoked immediate after to an ASN1_VALUE has been duplicated via a call to
 ASN1_item_dup().

 =item B<ASN1_OP_GET0_LIBCTX>

 Invoked in order to obtain the B<OSSL_LIB_CTX> associated with an B<ASN1_VALUE>
 if any. A pointer to an B<OSSL_LIB_CTX> should be stored in I<*exarg> if such
 a value exists.

 =item B<ASN1_OP_GET0_PROPQ>

 Invoked in order to obtain the property query string associated with an
 B<ASN1_VALUE> if any. A pointer to the property query string should be stored in
 I<*exarg> if such a value exists.

 =back

 An B<ASN1_PRINT_ARG> object is used during processing of B<ASN1_OP_PRINT_PRE>
 and B<ASN1_OP_PRINT_POST> callback operations. It contains the following
 information.

 =over 4

 =item I<out>

 The B<BIO> being used to print the data out.

 =item I<ndef_bio>

 The current number of indent spaces that should be used for printing this data.

 =item I<pctx>

 The context for the B<ASN1_PCTX> operation.

 =back

 An B<ASN1_STREAM_ARG> object is used during processing of B<ASN1_OP_STREAM_PRE>,
 B<ASN1_OP_STREAM_POST>, B<ASN1_OP_DETACHED_PRE> and B<ASN1_OP_DETACHED_POST>
 callback operations. It contains the following information.

 =over 4

 =item I<out>

 The B<BIO> to stream through

 =item I<ndef_bio>

 The B<BIO> with filters appended

 =item I<boundary>

 The streaming I/O boundary.

 =back

 =head1 RETURN VALUES

 The callbacks return 0 on error and a positive value on success. Some operations
 require specific positive success values as noted above.

 =head1 SEE ALSO

 L<ASN1_item_new_ex(3)>

 =head1 HISTORY

 The ASN1_aux_const_cb() callback and the B<ASN1_OP_GET0_LIBCTX> and
 B<ASN1_OP_GET0_PROPQ> operation types were added in OpenSSL 3.0.

 =head1 COPYRIGHT

 Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.

 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.

 =cut
	=pod

	=head1 NAME

	ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb
	- ASN.1 auxiliary data

	=head1 SYNOPSIS

	#include <openssl/asn1t.h>

	struct ASN1_AUX_st {
	void *app_data;
	int flags;
	int ref_offset; /* Offset of reference value */
	int ref_lock; /* Offset to an CRYPTO_RWLOCK */
	ASN1_aux_cb *asn1_cb;
	int enc_offset; /* Offset of ASN1_ENCODING structure */
	ASN1_aux_const_cb asn1_const_cb; / for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */
	};
	typedef struct ASN1_AUX_st ASN1_AUX;

	struct ASN1_PRINT_ARG_st {
	BIO *out;
	int indent;
	const ASN1_PCTX *pctx;
	};
	typedef struct ASN1_PRINT_ARG_st ASN1_PRINT_ARG;

	struct ASN1_STREAM_ARG_st {
	BIO *out;
	BIO *ndef_bio;
	unsigned char **boundary;
	};
	typedef struct ASN1_STREAM_ARG_st ASN1_STREAM_ARG;

	typedef int ASN1_aux_cb(int operation, ASN1_VALUE *in, const ASN1_ITEM it,
	void *exarg);
	typedef int ASN1_aux_const_cb(int operation, const ASN1_VALUE **in,
	const ASN1_ITEM it, void exarg);

	=head1 DESCRIPTION

	ASN.1 data structures can be associated with an B<ASN1_AUX> object to supply
	additional information about the ASN.1 structure. An B<ASN1_AUX> structure is
	associated with the structure during the definition of the ASN.1 template. For
	example an B<ASN1_AUX> structure will be associated by using one of the various
	ASN.1 template definition macros that supply auxiliary information such as
	ASN1_SEQUENCE_enc(), ASN1_SEQUENCE_ref(), ASN1_SEQUENCE_cb_const_cb(),
	ASN1_SEQUENCE_const_cb(), ASN1_SEQUENCE_cb() or ASN1_NDEF_SEQUENCE_cb().

	An B<ASN1_AUX> structure contains the following information.

	=over 4

	=item I<app_data>

	Arbitrary application data

	=item I<flags>

	Flags which indicate the auxiliarly functionality supported.

	The B<ASN1_AFLG_REFCOUNT> flag indicates that objects support reference counting.

	The B<ASN1_AFLG_ENCODING> flag indicates that the original encoding of the
	object will be saved.

	The B<ASN1_AFLG_BROKEN> flag is a work around for broken encoders where the
	sequence length value may not be correct. This should generally not be used.

	The B<ASN1_AFLG_CONST_CB> flag indicates that the "const" form of the
	B<ASN1_AUX> callback should be used in preference to the non-const form.

	=item I<ref_offset>

	If the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an
	offset into the B<ASN1_VALUE> structure where a B<CRYPTO_REF_COUNT> may be
	found for the purposes of reference counting.

	=item I<ref_lock>

	If the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an
	offset into the B<ASN1_VALUE> structure where a B<CRYPTO_RWLOCK> may be
	found for the purposes of reference counting.

	=item I<asn1_cb>

	A callback that will be invoked at various points during the processing of
	the the B<ASN1_VALLUE>. See below for further details.

	=item I<enc_offset>

	Offset into the B<ASN1_VALUE> object where the original encoding of the object
	will be saved if the B<ASN1_AFLG_ENCODING> flag has been set.

	=item I<asn1_const_cb>

	A callback that will be invoked at various points during the processing of
	the the B<ASN1_VALLUE>. This is used in preference to the I<asn1_cb> callback if
	the B<ASN1_AFLG_CONST_CB> flag is set. See below for further details.

	=back

	During the processing of an B<ASN1_VALUE> object the callbacks set via
	I<asn1_cb> or I<asn1_const_cb> will be invoked as a result of various events
	indicated via the I<operation> parameter. The value of I<*in> will be the
	B<ASN1_VALUE> object being processed based on the template in I<it>. An
	additional operation specific parameter may be passed in I<exarg>. The currently
	supported operations are as follows. The callbacks should return a positive
	value on success or zero on error, unless otherwise noted below.

	=over 4

	=item B<ASN1_OP_NEW_PRE>

	Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
	prior to an B<ASN1_VALUE> object being allocated. The callback may allocate the
	B<ASN1_VALUE> itself and store it in I<*pval>. If it does so it should return 2
	from the callback. On error it should return 0.

	=item B<ASN1_OP_NEW_POST>

	Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
	after an B<ASN1_VALUE> object has been allocated. The allocated object is in
	I<*pval>.

	=item B<ASN1_OP_FREE_PRE>

	Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
	immediately before an B<ASN1_VALUE> is freed. If the callback originally
	constructed the B<ASN1_VALUE> via B<ASN1_OP_NEW_PRE> then it should free it at
	this point and return 2 from the callback. Otherwise it should return 1 for
	success or 0 on error.

	=item B<ASN1_OP_FREE_POST>

	Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
	immediately after B<ASN1_VALUE> sub-structures are freed.

	=item B<ASN1_OP_D2I_PRE>

	Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
	immediately before a "d2i" operation for the B<ASN1_VALUE>.

	=item B<ASN1_OP_D2I_POST>

	Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
	immediately after a "d2i" operation for the B<ASN1_VALUE>.

	=item B<ASN1_OP_I2D_PRE>

	Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
	immediately before a "i2d" operation for the B<ASN1_VALUE>.

	=item B<ASN1_OP_I2D_POST>

	Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
	immediately after a "i2d" operation for the B<ASN1_VALUE>.

	=item B<ASN1_OP_PRINT_PRE>

	Invoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately
	before printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an
	B<ASN1_PRINT_ARG> structure (see below).

	=item B<ASN1_OP_PRINT_POST>

	Invoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately
	after printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an
	B<ASN1_PRINT_ARG> structure (see below).

	=item B<ASN1_OP_STREAM_PRE>

	Invoked immediately prior to streaming the B<ASN1_VALUE> data using indefinite
	length encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG>
	structure (see below).

	=item B<ASN1_OP_STREAM_POST>

	Invoked immediately after streaming the B<ASN1_VALUE> data using indefinite
	length encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG>
	structure (see below).

	=item B<ASN1_OP_DETACHED_PRE>

	Invoked immediately prior to processing the B<ASN1_VALUE> data as a "detached"
	value (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a
	B<ASN1_STREAM_ARG> structure (see below).

	=item B<ASN1_OP_DETACHED_POST>

	Invoked immediately after processing the B<ASN1_VALUE> data as a "detached"
	value (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a
	B<ASN1_STREAM_ARG> structure (see below).

	=item B<ASN1_OP_DUP_PRE>

	Invoked immediate prior to an ASN1_VALUE being duplicated via a call to
	ASN1_item_dup().

	=item B<ASN1_OP_DUP_POST>

	Invoked immediate after to an ASN1_VALUE has been duplicated via a call to
	ASN1_item_dup().

	=item B<ASN1_OP_GET0_LIBCTX>

	Invoked in order to obtain the B<OSSL_LIB_CTX> associated with an B<ASN1_VALUE>
	if any. A pointer to an B<OSSL_LIB_CTX> should be stored in I<*exarg> if such
	a value exists.

	=item B<ASN1_OP_GET0_PROPQ>

	Invoked in order to obtain the property query string associated with an
	B<ASN1_VALUE> if any. A pointer to the property query string should be stored in
	I<*exarg> if such a value exists.

	=back

	An B<ASN1_PRINT_ARG> object is used during processing of B<ASN1_OP_PRINT_PRE>
	and B<ASN1_OP_PRINT_POST> callback operations. It contains the following
	information.

	=over 4

	=item I<out>

	The B<BIO> being used to print the data out.

	=item I<ndef_bio>

	The current number of indent spaces that should be used for printing this data.

	=item I<pctx>

	The context for the B<ASN1_PCTX> operation.

	=back

	An B<ASN1_STREAM_ARG> object is used during processing of B<ASN1_OP_STREAM_PRE>,
	B<ASN1_OP_STREAM_POST>, B<ASN1_OP_DETACHED_PRE> and B<ASN1_OP_DETACHED_POST>
	callback operations. It contains the following information.

	=over 4

	=item I<out>

	The B<BIO> to stream through

	=item I<ndef_bio>

	The B<BIO> with filters appended

	=item I<boundary>

	The streaming I/O boundary.

	=back

	=head1 RETURN VALUES

	The callbacks return 0 on error and a positive value on success. Some operations
	require specific positive success values as noted above.

	=head1 SEE ALSO

	L<ASN1_item_new_ex(3)>

	=head1 HISTORY

	The ASN1_aux_const_cb() callback and the B<ASN1_OP_GET0_LIBCTX> and
	B<ASN1_OP_GET0_PROPQ> operation types were added in OpenSSL 3.0.

	=head1 COPYRIGHT

	Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.

	Licensed under the Apache License 2.0 (the "License"). You may not use
	this file except in compliance with the License. You can obtain a copy
	in the file LICENSE in the source distribution or at
	L<https://www.openssl.org/source/license.html>.

	=cut