ASN1_AUX_CB(3SSL)

📦

version 4.0.3 · 13 versions

💖 NAME 💖

ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb — bestie, it's the ASN.1 auxiliary data squad ✨ (this whole page lives in the OpenSSL manuals, section 3SSL, iykyk)

🎀 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);

🦋 DESCRIPTION 🦋

So here's the vibe: your ASN.1 data structures can be besties with an ASN1_AUX object, and that little guy carries all the extra tea about the structure 🫖. You hook an ASN1_AUX structure up to your structure while you're defining the ASN.1 template. For example, an ASN1_AUX structure gets associated by using one of the various ASN.1 template definition macros that supply auxiliary information, like ASN1_SEQUENCE_enc(), ASN1_SEQUENCE_ref(), ASN1_SEQUENCE_cb_const_cb(), ASN1_SEQUENCE_const_cb(), ASN1_SEQUENCE_cb() or ASN1_NDEF_SEQUENCE_cb().

An ASN1_AUX structure holds all of this info:

app_data — arbitrary application data, no questions asked 💅
flags — the flags that say which auxiliary functionality is supported:
- The ASN1_AFLG_REFCOUNT flag says these objects support reference counting.
- The ASN1_AFLG_ENCODING flag says the original encoding of the object is gonna be saved.
- The ASN1_AFLG_BROKEN flag is a work around for broken encoders where the sequence length value may not be correct. Generally you should NOT use this one, bestie, fr fr.
- The ASN1_AFLG_CONST_CB flag says the "const" form of the ASN1_AUX callback should be used in preference to the non-const form.
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 — 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 — a callback that gets invoked at various points during the processing of the ASN1_VALUE. Details below, keep reading 👇
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 — a callback that gets invoked at various points during the processing of the ASN1_VALUE. This one is used in preference to the asn1_cb callback if the ASN1_AFLG_CONST_CB flag is set. Details below too 👇

✨ The callbacks, and when they fire ✨

While an ASN1_VALUE object is being processed, the callbacks you set via asn1_cb or asn1_const_cb get invoked as a result of various events, and those events are indicated via the operation parameter. The value of *in is the ASN1_VALUE object being processed, based on the template in it. An additional operation-specific parameter may be passed in exarg. Here are the currently supported operations, bestie. Unless noted otherwise below, the callbacks should return a positive value on success and zero on error; some operations recognise additional return values, and a few don't even look at the return value at all 🙈.

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 ASN1_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 — invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE structure, after an ASN1_VALUE object has been allocated. The allocated object is in *pval.
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; the caller will then skip its normal freeing. Any other return value (including zero) causes the caller to proceed with normal freeing; the hook cannot signal an error.
ASN1_OP_FREE_POST — invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE structure, immediately after ASN1_VALUE sub-structures are freed. The caller does not consult the return value from this hook.
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 — invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE structure, immediately after a "d2i" operation for the ASN1_VALUE.
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 — invoked when processing a CHOICE, SEQUENCE or NDEF_SEQUENCE structure, immediately after a "i2d" operation for the ASN1_VALUE.
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 ASN1_PRINT_ARG structure (peep below 👀). If the callback has fully printed the value itself, it should return 2; the caller will then skip the per-field printing loop and the matching ASN1_OP_PRINT_POST callback. Return zero on error, or any other positive value to continue with normal printing.
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 ASN1_PRINT_ARG structure (see below).
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 — 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 — 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 ASN1_STREAM_ARG structure (see below).
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 ASN1_STREAM_ARG structure (see below).
ASN1_OP_DUP_PRE — invoked immediate prior to an ASN1_VALUE being duplicated via a call to ASN1_item_dup().
ASN1_OP_DUP_POST — invoked immediate after to an ASN1_VALUE has been duplicated via a call to ASN1_item_dup().
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 — invoked in order to obtain the property query string associated with an ASN1_VALUE, if any. A pointer to the property query string should be stored in *exarg if such a value exists.

🌸 The `ASN1_PRINT_ARG` object 🌸

An ASN1_PRINT_ARG object is used during processing of the ASN1_OP_PRINT_PRE and ASN1_OP_PRINT_POST callback operations. It contains this info:

out — The BIO being used to print the data out.
ndef_bio — The current number of indent spaces that should be used for printing this data.
pctx — The context for the ASN1_PCTX operation.

💜 The `ASN1_STREAM_ARG` object 💜

An ASN1_STREAM_ARG object is used during processing of the ASN1_OP_STREAM_PRE, ASN1_OP_STREAM_POST, ASN1_OP_DETACHED_PRE and ASN1_OP_DETACHED_POST callback operations. It contains this info:

out — The BIO to stream through
ndef_bio — The BIO with filters appended
boundary — The streaming I/O boundary.

🔥 RETURN VALUES 🔥

Generally speaking, the callbacks return zero on error and a positive value on success. But several operations have additional or different return-value semantics, and here they are, summarised for you bestie:

ASN1_OP_NEW_PRE recognises a return of 2, meaning that the callback has allocated the ASN1_VALUE itself and normal allocation should be skipped. 👑
ASN1_OP_FREE_PRE recognises a return of 2, meaning that the callback has freed the ASN1_VALUE itself and normal freeing should be skipped. Other return values (including zero) cause normal freeing to proceed; the hook cannot signal an error.
ASN1_OP_FREE_POST's return value is not consulted by the caller. Not me returning whatever, it literally does not matter 💀
ASN1_OP_PRINT_PRE recognises a return of 2, meaning that the callback has printed the value itself; the caller will skip the per-field printing loop and the matching ASN1_OP_PRINT_POST invocation.
ASN1_OP_STREAM_PRE, ASN1_OP_STREAM_POST, ASN1_OP_DETACHED_PRE, and ASN1_OP_DETACHED_POST treat any non-positive return value (zero or negative) as an error.

🌈 SEE ALSO 🌈

ASN1_item_new_ex(3)

⭐ HISTORY ⭐

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

💅 COPYRIGHT 💅

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>.

and that's the whole page, bestie — OpenSSL 4.0.3, dated 2026-09-29, ASN1_AUX_CB(3SSL), periodt 💖✨🎀🦋

📦 where this page comes from

ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms