xref: /freebsd/secure/lib/libcrypto/man/man3/ASN1_aux_cb.3 (revision 9f23cbd6cae82fd77edfad7173432fa8dccd0a95)
Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)

Standard preamble:
========================================================================
..
..
.. Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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
Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================

Title "ASN1_AUX_CB 3"
ASN1_AUX_CB 3 "2023-05-30" "3.0.9" "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 auxilliary 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" \s-1ASN.1\s0 data structures can be associated with an \s-1ASN1_AUX\s0 object to supply additional information about the \s-1ASN.1\s0 structure. An \s-1ASN1_AUX\s0 structure is associated with the structure during the definition of the \s-1ASN.1\s0 template. For example an \s-1ASN1_AUX\s0 structure will be associated by using one of the various \s-1ASN.1\s0 template definition macros that supply auxilliary 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 \s-1ASN1_AUX\s0 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 \s-1ASN1_AFLG_REFCOUNT\s0 flag indicates that objects support reference counting. .Sp The \s-1ASN1_AFLG_ENCODING\s0 flag indicates that the original encoding of the object will be saved. .Sp The \s-1ASN1_AFLG_BROKEN\s0 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 \s-1ASN1_AFLG_CONST_CB\s0 flag indicates that the \*(L"const\*(R" form of the \fB\s-1ASN1_AUX\s0 callback should be used in preference to the non-const form.
"ref_offset" 4
Item "ref_offset" If the \s-1ASN1_AFLG_REFCOUNT\s0 flag is set then this value is assumed to be an offset into the \s-1ASN1_VALUE\s0 structure where a \s-1CRYPTO_REF_COUNT\s0 may be found for the purposes of reference counting.
"ref_lock" 4
Item "ref_lock" If the \s-1ASN1_AFLG_REFCOUNT\s0 flag is set then this value is assumed to be an offset into the \s-1ASN1_VALUE\s0 structure where a \s-1CRYPTO_RWLOCK\s0 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 \s-1ASN1_VALLUE\s0. See below for further details.
"enc_offset" 4
Item "enc_offset" Offset into the \s-1ASN1_VALUE\s0 object where the original encoding of the object will be saved if the \s-1ASN1_AFLG_ENCODING\s0 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 \s-1ASN1_VALLUE\s0. This is used in preference to the asn1_cb callback if the \s-1ASN1_AFLG_CONST_CB\s0 flag is set. See below for further details.

During the processing of an \s-1ASN1_VALUE\s0 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 \fB\s-1ASN1_VALUE\s0 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.

"\s-1ASN1_OP_NEW_PRE\s0" 4
Item "ASN1_OP_NEW_PRE" Invoked when processing a \s-1CHOICE\s0, \s-1SEQUENCE\s0 or \s-1NDEF_SEQUENCE\s0 structure prior to an \s-1ASN1_VALUE\s0 object being allocated. The callback may allocate the \fB\s-1ASN1_VALUE\s0 itself and store it in *pval. If it does so it should return 2 from the callback. On error it should return 0.
"\s-1ASN1_OP_NEW_POST\s0" 4
Item "ASN1_OP_NEW_POST" Invoked when processing a \s-1CHOICE\s0, \s-1SEQUENCE\s0 or \s-1NDEF_SEQUENCE\s0 structure after an \s-1ASN1_VALUE\s0 object has been allocated. The allocated object is in \fI*pval.
"\s-1ASN1_OP_FREE_PRE\s0" 4
Item "ASN1_OP_FREE_PRE" Invoked when processing a \s-1CHOICE\s0, \s-1SEQUENCE\s0 or \s-1NDEF_SEQUENCE\s0 structure immediately before an \s-1ASN1_VALUE\s0 is freed. If the callback originally constructed the \s-1ASN1_VALUE\s0 via \s-1ASN1_OP_NEW_PRE\s0 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.
"\s-1ASN1_OP_FREE_POST\s0" 4
Item "ASN1_OP_FREE_POST" Invoked when processing a \s-1CHOICE\s0, \s-1SEQUENCE\s0 or \s-1NDEF_SEQUENCE\s0 structure immediately after \s-1ASN1_VALUE\s0 sub-structures are freed.
"\s-1ASN1_OP_D2I_PRE\s0" 4
Item "ASN1_OP_D2I_PRE" Invoked when processing a \s-1CHOICE\s0, \s-1SEQUENCE\s0 or \s-1NDEF_SEQUENCE\s0 structure immediately before a \*(L"d2i\*(R" operation for the \s-1ASN1_VALUE\s0.
"\s-1ASN1_OP_D2I_POST\s0" 4
Item "ASN1_OP_D2I_POST" Invoked when processing a \s-1CHOICE\s0, \s-1SEQUENCE\s0 or \s-1NDEF_SEQUENCE\s0 structure immediately after a \*(L"d2i\*(R" operation for the \s-1ASN1_VALUE\s0.
"\s-1ASN1_OP_I2D_PRE\s0" 4
Item "ASN1_OP_I2D_PRE" Invoked when processing a \s-1CHOICE\s0, \s-1SEQUENCE\s0 or \s-1NDEF_SEQUENCE\s0 structure immediately before a \*(L"i2d\*(R" operation for the \s-1ASN1_VALUE\s0.
"\s-1ASN1_OP_I2D_POST\s0" 4
Item "ASN1_OP_I2D_POST" Invoked when processing a \s-1CHOICE\s0, \s-1SEQUENCE\s0 or \s-1NDEF_SEQUENCE\s0 structure immediately after a \*(L"i2d\*(R" operation for the \s-1ASN1_VALUE\s0.
"\s-1ASN1_OP_PRINT_PRE\s0" 4
Item "ASN1_OP_PRINT_PRE" Invoked when processing a \s-1SEQUENCE\s0 or \s-1NDEF_SEQUENCE\s0 structure immediately before printing the \s-1ASN1_VALUE\s0. The exarg argument will be a pointer to an \fB\s-1ASN1_PRINT_ARG\s0 structure (see below).
"\s-1ASN1_OP_PRINT_POST\s0" 4
Item "ASN1_OP_PRINT_POST" Invoked when processing a \s-1SEQUENCE\s0 or \s-1NDEF_SEQUENCE\s0 structure immediately after printing the \s-1ASN1_VALUE\s0. The exarg argument will be a pointer to an \fB\s-1ASN1_PRINT_ARG\s0 structure (see below).
"\s-1ASN1_OP_STREAM_PRE\s0" 4
Item "ASN1_OP_STREAM_PRE" Invoked immediately prior to streaming the \s-1ASN1_VALUE\s0 data using indefinite length encoding. The exarg argument will be a pointer to a \s-1ASN1_STREAM_ARG\s0 structure (see below).
"\s-1ASN1_OP_STREAM_POST\s0" 4
Item "ASN1_OP_STREAM_POST" Invoked immediately after streaming the \s-1ASN1_VALUE\s0 data using indefinite length encoding. The exarg argument will be a pointer to a \s-1ASN1_STREAM_ARG\s0 structure (see below).
"\s-1ASN1_OP_DETACHED_PRE\s0" 4
Item "ASN1_OP_DETACHED_PRE" Invoked immediately prior to processing the \s-1ASN1_VALUE\s0 data as a \*(L"detached\*(R" value (as used in \s-1CMS\s0 and \s-1PKCS7\s0). The exarg argument will be a pointer to a \fB\s-1ASN1_STREAM_ARG\s0 structure (see below).
"\s-1ASN1_OP_DETACHED_POST\s0" 4
Item "ASN1_OP_DETACHED_POST" Invoked immediately after processing the \s-1ASN1_VALUE\s0 data as a \*(L"detached\*(R" value (as used in \s-1CMS\s0 and \s-1PKCS7\s0). The exarg argument will be a pointer to a \fB\s-1ASN1_STREAM_ARG\s0 structure (see below).
"\s-1ASN1_OP_DUP_PRE\s0" 4
Item "ASN1_OP_DUP_PRE" Invoked immediate prior to an \s-1ASN1_VALUE\s0 being duplicated via a call to \fBASN1_item_dup().
"\s-1ASN1_OP_DUP_POST\s0" 4
Item "ASN1_OP_DUP_POST" Invoked immediate after to an \s-1ASN1_VALUE\s0 has been duplicated via a call to \fBASN1_item_dup().
"\s-1ASN1_OP_GET0_LIBCTX\s0" 4
Item "ASN1_OP_GET0_LIBCTX" Invoked in order to obtain the \s-1OSSL_LIB_CTX\s0 associated with an \s-1ASN1_VALUE\s0 if any. A pointer to an \s-1OSSL_LIB_CTX\s0 should be stored in *exarg if such a value exists.
"\s-1ASN1_OP_GET0_PROPQ\s0" 4
Item "ASN1_OP_GET0_PROPQ" Invoked in order to obtain the property query string associated with an \fB\s-1ASN1_VALUE\s0 if any. A pointer to the property query string should be stored in \fI*exarg if such a value exists.

An \s-1ASN1_PRINT_ARG\s0 object is used during processing of \s-1ASN1_OP_PRINT_PRE\s0 and \s-1ASN1_OP_PRINT_POST\s0 callback operations. It contains the following information.

"out" 4
Item "out" The \s-1BIO\s0 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 \s-1ASN1_PCTX\s0 operation.

An \s-1ASN1_STREAM_ARG\s0 object is used during processing of \s-1ASN1_OP_STREAM_PRE\s0, \fB\s-1ASN1_OP_STREAM_POST\s0, \s-1ASN1_OP_DETACHED_PRE\s0 and \s-1ASN1_OP_DETACHED_POST\s0 callback operations. It contains the following information.

"out" 4
Item "out" The \s-1BIO\s0 to stream through
"ndef_bio" 4
Item "ndef_bio" The \s-1BIO\s0 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 \s-1ASN1_OP_GET0_LIBCTX\s0 and \fB\s-1ASN1_OP_GET0_PROPQ\s0 operation types were added in OpenSSL 3.0.
"COPYRIGHT"
Header "COPYRIGHT" Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

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