OSSL_DECODER_CTX(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💅 OSSL_DECODER_CTX — Decoder context routines (from 3ossl, the OpenSSL girlies ✨)

okay bestie, grab a strawberry 🍓 and sit down, because this one's a whole thing and it's honestly kind of iconic. This is OSSL_DECODER_CTX(3ossl) — the page about how OpenSSL figures out what the heck your input data even is, and then unpacks it. no cap, it's a lot, but we're gonna get through it together 🫶

🌸 NAME 🌸

ok so like, a lot of things live here. All of these, periodt:

  • OSSL_DECODER_CTX, OSSL_DECODER_CTX_new, OSSL_DECODER_settable_ctx_params, OSSL_DECODER_CTX_set_params, OSSL_DECODER_CTX_free
  • OSSL_DECODER_CTX_set_selection, OSSL_DECODER_CTX_set_input_type, OSSL_DECODER_CTX_set_input_structure
  • OSSL_DECODER_CTX_add_decoder, OSSL_DECODER_CTX_add_extra, OSSL_DECODER_CTX_get_num_decoders
  • OSSL_DECODER_INSTANCE, OSSL_DECODER_CONSTRUCT, OSSL_DECODER_CLEANUP
  • OSSL_DECODER_CTX_set_construct, OSSL_DECODER_CTX_set_construct_data, OSSL_DECODER_CTX_set_cleanup
  • OSSL_DECODER_CTX_get_construct, OSSL_DECODER_CTX_get_construct_data, OSSL_DECODER_CTX_get_cleanup
  • OSSL_DECODER_export
  • OSSL_DECODER_INSTANCE_get_decoder, OSSL_DECODER_INSTANCE_get_decoder_ctx, OSSL_DECODER_INSTANCE_get_input_type, OSSL_DECODER_INSTANCE_get_input_structure

and the collective vibe name for all of it? Decoder context routines. slay 💅

✨ SYNOPSIS ✨

#include <openssl/decoder.h>

typedef struct ossl_decoder_ctx_st OSSL_DECODER_CTX;

OSSL_DECODER_CTX *OSSL_DECODER_CTX_new(void);
const OSSL_PARAM *OSSL_DECODER_settable_ctx_params(OSSL_DECODER *decoder);
int OSSL_DECODER_CTX_set_params(OSSL_DECODER_CTX *ctx,
                                const OSSL_PARAM params[]);
void OSSL_DECODER_CTX_free(OSSL_DECODER_CTX *ctx);

int OSSL_DECODER_CTX_set_selection(OSSL_DECODER_CTX *ctx, int selection);
int OSSL_DECODER_CTX_set_input_type(OSSL_DECODER_CTX *ctx,
                                    const char *input_type);
int OSSL_DECODER_CTX_set_input_structure(OSSL_DECODER_CTX *ctx,
                                         const char *input_structure);
int OSSL_DECODER_CTX_add_decoder(OSSL_DECODER_CTX *ctx, OSSL_DECODER *decoder);
int OSSL_DECODER_CTX_add_extra(OSSL_DECODER_CTX *ctx,
                               OSSL_LIB_CTX *libctx,
                               const char *propq);
int OSSL_DECODER_CTX_get_num_decoders(OSSL_DECODER_CTX *ctx);

typedef struct ossl_decoder_instance_st OSSL_DECODER_INSTANCE;
OSSL_DECODER *
OSSL_DECODER_INSTANCE_get_decoder(OSSL_DECODER_INSTANCE *decoder_inst);
void *
OSSL_DECODER_INSTANCE_get_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst);
const char *
OSSL_DECODER_INSTANCE_get_input_type(OSSL_DECODER_INSTANCE *decoder_inst);
OSSL_DECODER_INSTANCE_get_input_structure(OSSL_DECODER_INSTANCE *decoder_inst,
                                          int *was_set);

typedef int OSSL_DECODER_CONSTRUCT(OSSL_DECODER_INSTANCE *decoder_inst,
                                   const OSSL_PARAM *object,
                                   void *construct_data);
typedef void OSSL_DECODER_CLEANUP(void *construct_data);

int OSSL_DECODER_CTX_set_construct(OSSL_DECODER_CTX *ctx,
                                   OSSL_DECODER_CONSTRUCT *construct);
int OSSL_DECODER_CTX_set_construct_data(OSSL_DECODER_CTX *ctx,
                                        void *construct_data);
int OSSL_DECODER_CTX_set_cleanup(OSSL_DECODER_CTX *ctx,
                                 OSSL_DECODER_CLEANUP *cleanup);
OSSL_DECODER_CONSTRUCT *OSSL_DECODER_CTX_get_construct(OSSL_DECODER_CTX *ctx);
void *OSSL_DECODER_CTX_get_construct_data(OSSL_DECODER_CTX *ctx);
OSSL_DECODER_CLEANUP *OSSL_DECODER_CTX_get_cleanup(OSSL_DECODER_CTX *ctx);

int OSSL_DECODER_export(OSSL_DECODER_INSTANCE *decoder_inst,
                        void *reference, size_t reference_sz,
                        OSSL_CALLBACK *export_cb, void *export_cbarg);

🦋 DESCRIPTION 🦋

okay so the whole concept: OSSL_DECODER_CTX is like the group chat of decoders 👑. It holds all the data about multiple decoders at once — because you need a squad to figure out what your input data actually is, and then to attempt to unpack it into one of several possible related results.

and yes, that includes chaining decoders, so the output from one becomes the input for the next. literally passing the aux. 🔥 that's how you get generic format decoders like PEM to DER, and also the more specialized ones like DER to RSA.

the chains can be limited by specifying an input type, which counts as a starting point. two things care about this:

  • OSSL_DECODER_CTX_add_extra(), which will stop adding one more decoder implementations once it's already added the ones that take the specified input type
  • functions like OSSL_DECODER_from_bio(3), which will only start the decoding process with the decoder implementations that take that input type

so like, fr fr: if the input type is set to "DER", a PEM to DER decoder gets ignored. not invited to the party 🙈

the input type can also be NULL, which means the caller has no idea what type of input they have. relatable tbh 😭 in that case, OSSL_DECODER_from_bio() will simply try one decoder implementation after the other, and thereby discover what kind of input the caller gave it. main character energy: it just figures it out.

every single time a decoding happens — even an intermediary one — a constructor provided by the caller gets called. its job? attempt to construct an appropriate type / structure that the caller knows how to handle from the current decoding result 💖

the constructor is set with OSSL_DECODER_CTX_set_construct().

OSSL_DECODER_INSTANCE is an opaque structure holding data about the decoder that was just used, and that may be useful for the constructor. there are some functions to extract data from this type, described further down 👇

🎀 Functions 🎀

  • OSSL_DECODER_CTX_new() — creates a new empty OSSL_DECODER_CTX. fresh start, blank slate, no baggage ✨
  • OSSL_DECODER_settable_ctx_params() — returns an OSSL_PARAM(3) array of parameter descriptors.
  • OSSL_DECODER_CTX_set_params() — attempts to set parameters specified with an OSSL_PARAM(3) array params. These parameters are passed to all decoders that have been added to the ctx so far. Parameters that an implementation doesn't recognise should be ignored by it. (not me ignoring things I don't understand 💀)
  • OSSL_DECODER_CTX_free() — frees the given context ctx. If the argument is NULL, nothing is done. no drama.
  • OSSL_DECODER_CTX_add_decoder() — populates the OSSL_DECODER_CTX ctx with a decoder, to be used to attempt to decode some encoded input.
  • OSSL_DECODER_CTX_add_extra() — finds decoders that generate input for already added decoders, and adds them as well. This is used to build decoder chains. 🦋 matching matching.
  • OSSL_DECODER_CTX_set_input_type() — sets the starting input type. This limits the decoder chains to be considered, as explained in the general description above.
  • OSSL_DECODER_CTX_set_input_structure() — sets the name of the structure that the input is expected to have. This may be used to determines what decoder implementations may be used. NULL is a valid input structure, when it's not relevant, or when the decoder implementations are expected to figure it out.
  • OSSL_DECODER_CTX_get_num_decoders() — gets the number of decoders currently added to the context ctx. (a headcount, basically 💅)
  • OSSL_DECODER_CTX_set_construct() — sets the constructor construct.
  • OSSL_DECODER_CTX_set_construct_data() — sets the constructor data that is passed to the constructor every time it's called.
  • OSSL_DECODER_CTX_set_cleanup() — sets the constructor data cleanup function. This is called by OSSL_DECODER_CTX_free(3).
  • OSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data() and OSSL_DECODER_CTX_get_cleanup() — return the values that have been set by OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and OSSL_DECODER_CTX_set_cleanup() respectively.
  • OSSL_DECODER_export() — a fallback function for constructors that cannot use the data they get directly for diverse reasons. It takes the same decode instance decoder_inst that the constructor got and an object reference, unpacks the object which it refers to, and exports it by creating an OSSL_PARAM(3) array that it then passes to export_cb, along with export_arg. the backup plan that still ate 🔥
⚠️ attention bestie, this part matters: note that functions OSSL_DECODER_CTX_set_selection(), OSSL_DECODER_CTX_set_output_type(), OSSL_DECODER_CTX_set_output_structure(), OSSL_DECODER_CTX_add_encoder(), OSSL_DECODER_CTX_add_extra(), OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data(), and OSSL_DECODER_CTX_set_cleanup() shouldn't be used after the context is finalised, in particular after calling the function OSSL_DECODER_CTX_new_for_pkey(). like, the glow-up is done, stop touching it 💀

🌈 Constructor 🌈

an OSSL_DECODER_CONSTRUCT gets the following arguments:

  • decoder_inst — the OSSL_DECODER_INSTANCE for the decoder from which the constructor gets its data.
  • object — a provider-native object abstraction produced by the decoder. Further information on the provider-native object abstraction can be found in provider-object(7).
  • construct_data — the pointer that was set with OSSL_DECODE_CTX_set_construct_data().

the constructor is expected to return 1 when the data it receives can be constructed, otherwise 0. yes/no, icon behaviour only ✨

these utility functions may be used by a constructor:

  • OSSL_DECODER_INSTANCE_get_decoder() — can be used to get the decoder implementation from a decoder instance decoder_inst.
  • OSSL_DECODER_INSTANCE_get_decoder_ctx() — can be used to get the decoder implementation's provider context from a decoder instance decoder_inst.
  • OSSL_DECODER_INSTANCE_get_input_type() — can be used to get the decoder implementation's input type from a decoder instance decoder_inst.
  • OSSL_DECODER_INSTANCE_get_input_structure() — can be used to get the input structure for the decoder implementation from a decoder instance decoder_inst. This may be NULL.

💜 RETURN VALUES 💜

okay, scoreboard time 📋:

  • OSSL_DECODER_CTX_new() — returns a pointer to a OSSL_DECODER_CTX, or NULL if the context structure couldn't be allocated.
  • OSSL_DECODER_settable_ctx_params() — returns an OSSL_PARAM(3) array, or NULL if none is available.
  • OSSL_DECODER_CTX_set_params() — returns 1 if all recognised parameters were valid, or 0 if one of them was invalid or caused some other failure in the implementation.
  • OSSL_DECODER_CTX_add_decoder(), OSSL_DECODER_CTX_add_extra(), OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and OSSL_DECODER_CTX_set_cleanup() — return 1 on success, or 0 on failure.
  • OSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data() and OSSL_DECODER_CTX_get_cleanup() — return the current pointers to the constructor, the constructor data and the cleanup functions, respectively.
  • OSSL_DECODER_CTX_num_decoders() — returns the current number of decoders. It returns 0 if ctx is NULL.
  • OSSL_DECODER_export() — returns 1 on success, or 0 on failure.
  • OSSL_DECODER_INSTANCE_decoder() — returns an OSSL_DECODER pointer on success, or NULL on failure.
  • OSSL_DECODER_INSTANCE_decoder_ctx() — returns a provider context pointer on success, or NULL on failure.

🧚 SEE ALSO 🧚

provider(7), OSSL_DECODER(3), OSSL_DECODER_from_bio(3) — go read those next, bestie, iykyk 📚

⭐ HISTORY ⭐

the functions described here were added in OpenSSL 3.0. vintage-ish but still cute 🎀

okay so legally we gotta do this part and honestly? respect the paperwork bestie 💅

Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.

This whole thing is licensed under the Apache License 2.0 (that's "the License" btw, capital L, main character energy 👑). You may not use this file except in compliance with the License — like, fr fr, it's not a suggestion 🫶

You can obtain a copy of the License in the file LICENSE in the source distribution, or at:

https://www.openssl.org/source/license.html

and that's the whole page, bestie!! 🌸 no cap, you now know OSSL_DECODER_CTX inside and out. this diva is documented as OpenSSL 3.5.6, dated 2026-04-07, filed under OSSL_DECODER_CTX(3ossl) — go forth and decode slayfully 💖✨🦋

📦 where this page comes from