$NetBSD: ASN1_aux_cb.3,v 1.5 2024/09/08 13:08:14 christos Exp $ -*- mode: troff; coding: utf-8 -*- Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) Standard preamble: ========================================================================..
..
..
\*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.. ds C` ""
. ds C' ""
'br\}
. ds C`
. ds C'
'br\}
Escape single quotes in literal strings from groff's Unicode transform. If the F register is >0, we'll generate index entries on stderr for titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index entries marked with X<> in POD. Of course, you'll have to process the output yourself in some meaningful fashion. Avoid warning from groff about undefined register 'F'...
.nr rF 0
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
======================================================================== Title "ASN1_aux_cb 3" ASN1_aux_cb 3 2024-09-03 3.0.15 OpenSSL
For nroff, turn off justification. Always turn off hyphenation; it makes way too many mistakes in technical documents. NAME
ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb
\- ASN.1 auxiliary data
SYNOPSIS
Header "SYNOPSIS" .Vb 1
#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);
.Ve
DESCRIPTION
Header "DESCRIPTION" ASN.1 data structures can be associated with an
ASN1_AUX object to supply
additional information about the ASN.1 structure. An
ASN1_AUX structure is
associated with the structure during the definition of the ASN.1 template. For
example an
ASN1_AUX structure will be associated by using one of the various
ASN.1 template definition macros that supply auxiliary information such as
\fBASN1_SEQUENCE_enc(),
ASN1_SEQUENCE_ref(),
ASN1_SEQUENCE_cb_const_cb(),
\fBASN1_SEQUENCE_const_cb(),
ASN1_SEQUENCE_cb() or
ASN1_NDEF_SEQUENCE_cb().
An ASN1_AUX structure contains the following information.
app_data 4
Item "app_data" Arbitrary application data
flags 4
Item "flags" Flags which indicate the auxiliarly functionality supported.
.Sp
The
ASN1_AFLG_REFCOUNT flag indicates that objects support reference counting.
.Sp
The
ASN1_AFLG_ENCODING flag indicates that the original encoding of the
object will be saved.
.Sp
The
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.
.Sp
The
ASN1_AFLG_CONST_CB flag indicates that the "const" form of the
\fBASN1_AUX callback should be used in preference to the non-const form.
ref_offset 4
Item "ref_offset" If the
ASN1_AFLG_REFCOUNT flag is set then this value is assumed to be an
offset into the
ASN1_VALUE structure where a
CRYPTO_REF_COUNT may be
found for the purposes of reference counting.
ref_lock 4
Item "ref_lock" If the
ASN1_AFLG_REFCOUNT flag is set then this value is assumed to be an
offset into the
ASN1_VALUE structure where a
CRYPTO_RWLOCK may be
found for the purposes of reference counting.
asn1_cb 4
Item "asn1_cb" A callback that will be invoked at various points during the processing of
the the
ASN1_VALLUE. See below for further details.
enc_offset 4
Item "enc_offset" Offset into the
ASN1_VALUE object where the original encoding of the object
will be saved if the
ASN1_AFLG_ENCODING flag has been set.
asn1_const_cb 4
Item "asn1_const_cb" A callback that will be invoked at various points during the processing of
the the
ASN1_VALLUE. This is used in preference to the
asn1_cb callback if
the
ASN1_AFLG_CONST_CB flag is set. See below for further details.
During the processing of an ASN1_VALUE object the callbacks set via
\fIasn1_cb or asn1_const_cb will be invoked as a result of various events
indicated via the operation parameter. The value of *in will be the
\fBASN1_VALUE object being processed based on the template in it. An
additional operation specific parameter may be passed in 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.
ASN1_OP_NEW_PRE 4
Item "ASN1_OP_NEW_PRE" Invoked when processing a
CHOICE,
SEQUENCE or
NDEF_SEQUENCE structure
prior to an
ASN1_VALUE object being allocated. The callback may allocate the
\fBASN1_VALUE itself and store it in
*pval. If it does so it should return 2
from the callback. On error it should return 0.
ASN1_OP_NEW_POST 4
Item "ASN1_OP_NEW_POST" Invoked when processing a
CHOICE,
SEQUENCE or
NDEF_SEQUENCE structure
after an
ASN1_VALUE object has been allocated. The allocated object is in
\fI*pval.
ASN1_OP_FREE_PRE 4
Item "ASN1_OP_FREE_PRE" Invoked when processing a
CHOICE,
SEQUENCE or
NDEF_SEQUENCE structure
immediately before an
ASN1_VALUE is freed. If the callback originally
constructed the
ASN1_VALUE via
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.
ASN1_OP_FREE_POST 4
Item "ASN1_OP_FREE_POST" Invoked when processing a
CHOICE,
SEQUENCE or
NDEF_SEQUENCE structure
immediately after
ASN1_VALUE sub-structures are freed.
ASN1_OP_D2I_PRE 4
Item "ASN1_OP_D2I_PRE" Invoked when processing a
CHOICE,
SEQUENCE or
NDEF_SEQUENCE structure
immediately before a "d2i" operation for the
ASN1_VALUE.
ASN1_OP_D2I_POST 4
Item "ASN1_OP_D2I_POST" Invoked when processing a
CHOICE,
SEQUENCE or
NDEF_SEQUENCE structure
immediately after a "d2i" operation for the
ASN1_VALUE.
ASN1_OP_I2D_PRE 4
Item "ASN1_OP_I2D_PRE" Invoked when processing a
CHOICE,
SEQUENCE or
NDEF_SEQUENCE structure
immediately before a "i2d" operation for the
ASN1_VALUE.
ASN1_OP_I2D_POST 4
Item "ASN1_OP_I2D_POST" Invoked when processing a
CHOICE,
SEQUENCE or
NDEF_SEQUENCE structure
immediately after a "i2d" operation for the
ASN1_VALUE.
ASN1_OP_PRINT_PRE 4
Item "ASN1_OP_PRINT_PRE" Invoked when processing a
SEQUENCE or
NDEF_SEQUENCE structure immediately
before printing the
ASN1_VALUE. The
exarg argument will be a pointer to an
\fBASN1_PRINT_ARG structure (see below).
ASN1_OP_PRINT_POST 4
Item "ASN1_OP_PRINT_POST" Invoked when processing a
SEQUENCE or
NDEF_SEQUENCE structure immediately
after printing the
ASN1_VALUE. The
exarg argument will be a pointer to an
\fBASN1_PRINT_ARG structure (see below).
ASN1_OP_STREAM_PRE 4
Item "ASN1_OP_STREAM_PRE" Invoked immediately prior to streaming the
ASN1_VALUE data using indefinite
length encoding. The
exarg argument will be a pointer to a
ASN1_STREAM_ARG
structure (see below).
ASN1_OP_STREAM_POST 4
Item "ASN1_OP_STREAM_POST" Invoked immediately after streaming the
ASN1_VALUE data using indefinite
length encoding. The
exarg argument will be a pointer to a
ASN1_STREAM_ARG
structure (see below).
ASN1_OP_DETACHED_PRE 4
Item "ASN1_OP_DETACHED_PRE" Invoked immediately prior to processing the
ASN1_VALUE data as a "detached"
value (as used in CMS and PKCS7). The
exarg argument will be a pointer to a
\fBASN1_STREAM_ARG structure (see below).
ASN1_OP_DETACHED_POST 4
Item "ASN1_OP_DETACHED_POST" Invoked immediately after processing the
ASN1_VALUE data as a "detached"
value (as used in CMS and PKCS7). The
exarg argument will be a pointer to a
\fBASN1_STREAM_ARG structure (see below).
ASN1_OP_DUP_PRE 4
Item "ASN1_OP_DUP_PRE" Invoked immediate prior to an ASN1_VALUE being duplicated via a call to
\fBASN1_item_dup().
ASN1_OP_DUP_POST 4
Item "ASN1_OP_DUP_POST" Invoked immediate after to an ASN1_VALUE has been duplicated via a call to
\fBASN1_item_dup().
ASN1_OP_GET0_LIBCTX 4
Item "ASN1_OP_GET0_LIBCTX" Invoked in order to obtain the
OSSL_LIB_CTX associated with an
ASN1_VALUE
if any. A pointer to an
OSSL_LIB_CTX should be stored in
*exarg if such
a value exists.
ASN1_OP_GET0_PROPQ 4
Item "ASN1_OP_GET0_PROPQ" Invoked in order to obtain the property query string associated with an
\fBASN1_VALUE if any. A pointer to the property query string should be stored in
\fI*exarg if such a value exists.
An ASN1_PRINT_ARG object is used during processing of ASN1_OP_PRINT_PRE
and ASN1_OP_PRINT_POST callback operations. It contains the following
information.
out 4
Item "out" The
BIO being used to print the data out.
ndef_bio 4
Item "ndef_bio" The current number of indent spaces that should be used for printing this data.
pctx 4
Item "pctx" The context for the
ASN1_PCTX operation.
An ASN1_STREAM_ARG object is used during processing of ASN1_OP_STREAM_PRE,
\fBASN1_OP_STREAM_POST, ASN1_OP_DETACHED_PRE and ASN1_OP_DETACHED_POST
callback operations. It contains the following information.
out 4
Item "out" The
BIO to stream through
ndef_bio 4
Item "ndef_bio" The
BIO with filters appended
boundary 4
Item "boundary" The streaming I/O boundary.
"RETURN VALUES"
Header "RETURN VALUES" The callbacks return 0 on error and a positive value on success. Some operations
require specific positive success values as noted above.
"SEE ALSO"
Header "SEE ALSO" \fBASN1_item_new_ex\|(3)
HISTORY
Header "HISTORY" The
ASN1_aux_const_cb() callback and the
ASN1_OP_GET0_LIBCTX and
\fBASN1_OP_GET0_PROPQ operation types were added in OpenSSL 3.0.
COPYRIGHT
Header "COPYRIGHT" Copyright 2021-2023 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
<https://www.openssl.org/source/license.html>.