ASN1_AUX_CB(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

💖 ASN1_AUX_CB 💖

okay so bestie, this is the 3ossl page for the OpenSSL ASN.1 auxiliary data crew: ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, and ASN1_aux_const_cb. it's giving ✨ plumbing ✨ but the important kind. let's get into it 🫶

✨ 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. ASN.1 data structures can be besties with an ASN1_AUX object, and that object carries extra deets about the ASN.1 structure. you associate an ASN1_AUX structure with your structure while you're defining the ASN.1 template. like, an ASN1_AUX structure gets 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 ASN1_AUX structure contains the following info 👇

  • app_data — arbitrary application data. do whatever, it's yours 💅
  • flags — flags that indicate which auxiliary functionality is supported. let's break them down:
    • the ASN1_AFLG_REFCOUNT flag says objects support reference counting.
    • the ASN1_AFLG_ENCODING flag says the original encoding of the object will be saved.
    • the ASN1_AFLG_BROKEN flag is a workaround for broken encoders where the sequence length value may not be correct. this should generally not be used — no cap, it's a band-aid 🩹
    • 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, 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, 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. more below bestie 👇
  • 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. more below too 👇

🦋 the callback operations 🦋

while an ASN1_VALUE object is being processed, the callbacks set via asn1_cb or asn1_const_cb get invoked because 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.

the currently supported operations are these. 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. iconic honestly 💅

  • 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 that, 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, 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 (see 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.

🎀 ASN1_PRINT_ARG 🎀

an ASN1_PRINT_ARG object is used during processing of the ASN1_OP_PRINT_PRE and ASN1_OP_PRINT_POST callback operations. it contains the following information:

  • 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.
bestie i'm just the messenger 💀 that's literally what the page says, i'm not touching it.

🌈 ASN1_STREAM_ARG 🌈

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 the following information:

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

⭐ RETURN VALUES ⭐

in general, the callbacks return zero on error and a positive value on success. but several operations have additional or different return-value semantics, so here's the summary, 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. it's giving ignored 💀
  • 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. glow-up era ✨

Copyright 2021-2026 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>.

and that's the whole page, bestie!! this was OpenSSL 3.5.9, dated 2026-09-29, from ASN1_AUX_CB(3ossl) — go forth and be auxiliary 💅💖🦋

📦 where this page comes from