OSSL_DECODER_CTX(3ossl)

📦

version 3.5.9 · 8 versions

3.5.9 · fedora 43, fedora 44 (latest)
3.5.9 · centos-stream 9
3.5.9 · centos-stream 10
3.5.9 · alpine 3.22
3.5.9 · alpine 3.23, alpine 3.24
3.5.8 · fedora 43
3.5.1 · fedora 43
3.5.5 · fedora 44

✨ NAME ✨

okay so welcome to OSSL_DECODER_CTX(3ossl), straight outta the OpenSSL manual bestie 💖 — it's the decoder context routines, and there's a LOT of them, so buckle up.

The whole squad, no one left behind:

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

🌸 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 🦋

So like. The OSSL_DECODER_CTX is holding all the tea about multiple decoders at once — everything you need to (a) figure out what your input data even is, and (b) try to unpack it into one of several possible related results. It also does chaining of decoders, so the output from one can become the input for another. Which is iconic because it means you get the generic format decoders (like PEM to DER) and the more specialised ones (like DER to RSA). slay. 💅

The chains can be limited by setting an input type, and that's basically the starting point. Two things care about it:

OSSL_DECODER_CTX_add_extra(), which stops adding more decoder implementations once it's already added the ones that take the specified input type, and
functions like OSSL_DECODER_from_bio(3), which will only kick off the decoding process with the decoder implementations that take that input type.

Example bestie: if the input type is set to "DER", then a PEM to DER decoder is getting ignored. periodt.

The input type can also be NULL, and that means the caller doesn't know what type of input they've got. In that case, OSSL_DECODER_from_bio() will just try one decoder implementation after the other and thereby discover what kind of input the caller gave it. main character energy fr fr ✨

For every decoding done — even an intermediary one — a constructor provided by the caller gets called, to attempt to construct an appropriate type / structure that the caller knows how to handle, from the current decoding result. You set that constructor with OSSL_DECODER_CTX_set_construct().

OSSL_DECODER_INSTANCE is an opaque structure containing 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, and they're described further down. 🫶

🎀 Functions 🎀

OSSL_DECODER_CTX_new() — creates a new, empty OSSL_DECODER_CTX. a whole new baby.
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 get passed to all decoders that have been added to the ctx so far. And if an implementation doesn't recognise a parameter? It should just ignore it. no drama.
OSSL_DECODER_CTX_free() — frees the given context ctx. If the argument is NULL, nothing is done. (nothing. zero. zilch.)
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 the decoders you already added, and adds them too. This is literally how you build decoder chains. 🔗
OSSL_DECODER_CTX_set_input_type() — sets the starting input type. This limits which decoder chains get considered, as explained up in the general description.
OSSL_DECODER_CTX_set_input_structure() — sets the name of the structure that the input is expected to have. This may be used to determine 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 themselves.
OSSL_DECODER_CTX_get_num_decoders() — gets the number of decoders currently added to the context ctx.
OSSL_DECODER_CTX_set_construct() — sets the constructor construct.
OSSL_DECODER_CTX_set_construct_data() — sets the constructor data that gets passed to the constructor every single time it's called.
OSSL_DECODER_CTX_set_cleanup() — sets the constructor data cleanup function. This one 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. getters gonna get. 💖
OSSL_DECODER_export() — a fallback function for constructors that can't use the data they get directly, for diverse reasons. It takes the same decode instance decoder_inst that the constructor got, plus 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.

okay so this next bit is a BIG DEAL ⚠️ — 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(). don't do it bestie, it's giving chaos 😭

🧚 Constructor 🧚

A 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 info on the provider-native object abstraction lives 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. simple as that 💅

These utility functions may be used by a constructor:

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

⭐ RETURN VALUES ⭐

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.

👑 HISTORY 👑

The functions described here were added in OpenSSL 3.0. ✨

💖 COPYRIGHT 💖

okay bestie, legal era incoming, but it's short and sweet so we're fine 💅

that's the whole vibe. every single right, reserved, no cap. 🫶

🎀 the license bit (iykyk) 🎀

so this file is Licensed under the Apache License 2.0 (the "License"). and like, read carefully bestie:

you may not use this file except in compliance with the License ✋
you can grab a copy of the License in the file LICENSE in the source distribution, or over at:

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

fr fr, unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, without warranties or conditions of any kind — that part is in the License itself, so go read it, it's giving very important ✨

and that's a wrap on OSSL_DECODER_CTX(3ossl), bestie 🎀 this one's from OpenSSL version 3.5.9, dated 2026-09-29, and honestly? iconic. go decode something. slay 💅✨🦋

📦 where this page comes from

fedora 43: openssl-devel 1:3.5.9-1.fc43 · Apache-2.0
fedora 43: openssl-devel 1:3.5.9-1.fc43 · Apache-2.0
fedora 44: openssl-devel 1:3.5.9-1.fc44 · Apache-2.0
fedora 44: openssl-devel 1:3.5.9-1.fc44 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms