OSSL_DECODER(3ossl)

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

💖 OSSL_DECODER(3ossl) — the OpenSSL decoder method routines, explained by your fav Unix bestie 🦋

okay so. bestie. you're in the OpenSSL manual, page OSSL_DECODER(3ossl), and we are about to have the cutest little deep-dive on decoder method routines. no cap, this is genuinely the plumbing that turns your encoded bytes into actual usable objects. slay. ✨

🌸 NAME 🌸

OSSL_DECODER, OSSL_DECODER_fetch, OSSL_DECODER_up_ref, OSSL_DECODER_free, OSSL_DECODER_get0_provider, OSSL_DECODER_get0_properties, OSSL_DECODER_is_a, OSSL_DECODER_get0_name, OSSL_DECODER_get0_description, OSSL_DECODER_do_all_provided, OSSL_DECODER_names_do_all, OSSL_DECODER_gettable_params, OSSL_DECODER_get_params — Decoder method routines 💅

✨ SYNOPSIS ✨

like, here's the whole squad's signatures, verbatim, don't touch:

#include <openssl/decoder.h>

typedef struct ossl_decoder_st OSSL_DECODER;

OSSL_DECODER *OSSL_DECODER_fetch(OSSL_LIB_CTX *ctx, const char *name,
                                 const char *properties);
int OSSL_DECODER_up_ref(OSSL_DECODER *decoder);
void OSSL_DECODER_free(OSSL_DECODER *decoder);
const OSSL_PROVIDER *OSSL_DECODER_get0_provider(const OSSL_DECODER *decoder);
const char *OSSL_DECODER_get0_properties(const OSSL_DECODER *decoder);
int OSSL_DECODER_is_a(const OSSL_DECODER *decoder, const char *name);
const char *OSSL_DECODER_get0_name(const OSSL_DECODER *decoder);
const char *OSSL_DECODER_get0_description(const OSSL_DECODER *decoder);
void OSSL_DECODER_do_all_provided(OSSL_LIB_CTX *libctx,
                                  void (*fn)(OSSL_DECODER *decoder, void *arg),
                                  void *arg);
int OSSL_DECODER_names_do_all(const OSSL_DECODER *decoder,
                              void (*fn)(const char *name, void *data),
                              void *data);
const OSSL_PARAM *OSSL_DECODER_gettable_params(OSSL_DECODER *decoder);
int OSSL_DECODER_get_params(OSSL_DECODER_CTX *ctx, const OSSL_PARAM params[]);

🎀 DESCRIPTION 🎀

so OSSL_DECODER is, like, the method for decoders. and what do decoders do? they take encoded data and decode it into an object of some type that the rest of OpenSSL actually knows how to handle. it's giving translator energy, it's giving "I got you bestie, let me make sense of this for you." 🔥

OSSL_DECODER_fetch() goes looking for an algorithm inside the provider that's been loaded into the OSSL_LIB_CTX you passed as ctx. it wants one with the name you gave it and the properties you gave it. and here's the tea: the name determines what type of object the fetched decoder method is expected to be able to decode, and the properties are what determine the expected output type. if you wanna know the known properties and all the values they can have, go peek at "Names and properties" in provider-encoder(7). 🫶

OSSL_DECODER_up_ref() bumps the reference count up for the decoder you hand it. one more friend holding a hand, basically. 💖

OSSL_DECODER_free() does the opposite — it decrements the reference count for the given decoder, and when that count hits zero, it frees it. and if the argument is NULL? literally nothing happens. nothing. we love a chill function. 😌

OSSL_DECODER_get0_provider() hands you back the provider of the decoder you gave it.

OSSL_DECODER_get0_properties() hands you back the property definition that's associated with the given decoder.

OSSL_DECODER_is_a() checks whether decoder is an implementation of an algorithm that's identifiable with name.

OSSL_DECODER_get0_name() returns the name that was used to fetch the given decoder.

OSSL_DECODER_get0_description() returns a description of the decoder — and this one is meant for display and human consumption, so it's purely at the discretion of the decoder implementation. whatever the impl felt like writing, that's what you get. 🙈

OSSL_DECODER_names_do_all() walks through all the names for the given decoder, and calls fn with each name and data as arguments.

OSSL_DECODER_do_all_provided() walks through every single decoder implementation from every activated provider in the library context libctx, and for each of those implementations it calls fn with the implementation method and arg as arguments. the full tour, no skips. 🌈

OSSL_DECODER_gettable_params() returns an OSSL_PARAM(3) array of parameter descriptors.

OSSL_DECODER_get_params() attempts to get parameters specified with an OSSL_PARAM(3) array params. and important: parameters that the implementation doesn't recognise should be ignored. not an error, just ignored. periodt.

⭐ RETURN VALUES ⭐

  • OSSL_DECODER_fetch() — returns a pointer to an OSSL_DECODER object, or NULL on error. 😭
  • OSSL_DECODER_up_ref() — returns 1 on success, or 0 on error.
  • OSSL_DECODER_free() — doesn't return any value. it just vibes.
  • OSSL_DECODER_get0_provider() — returns a pointer to a provider object, or NULL on error.
  • OSSL_DECODER_get0_properties() — returns a pointer to a property definition string, or NULL on error.
  • OSSL_DECODER_is_a() — returns 1 if decoder was identifiable, otherwise 0.
  • OSSL_DECODER_get0_name() — returns the algorithm name from the provided implementation for the given decoder. heads up though: the decoder may have multiple synonyms associated with it, and in that case, the first name from the algorithm definition is what gets returned. ownership of the returned string is retained by the decoder object, so do not free it yourself, bestie, I'm so serious. 🫣
  • OSSL_DECODER_get0_description() — returns a pointer to a description, or NULL if there isn't one.
  • OSSL_DECODER_names_do_all() — returns 1 if the callback was called for all names. a return value of 0 means the callback wasn't called for any names.

💜 NOTES 💜

OSSL_DECODER_fetch() may be called implicitly by other fetching functions, using the same library context and properties. and literally any other API that uses keys will typically do this. so like, even when you didn't ask for it, it's happening. main character energy fr fr. 👑

🧚 EXAMPLES 🧚

wanna list all decoders in a provider to a bio_out? here's the whole thing, copy it exactly, no typos:

static void collect_decoders(OSSL_DECODER *decoder, void *stack)
{
    STACK_OF(OSSL_DECODER) *decoder_stack = stack;

    sk_OSSL_DECODER_push(decoder_stack, decoder);
    OSSL_DECODER_up_ref(decoder);
}

void print_name(const char *name, void *vdata)
{
    BIO *bio = vdata;

    BIO_printf(bio, "%s ", name);
}

STACK_OF(OSSL_DECODER) *decoders;
int i;

decoders = sk_OSSL_DECODER_new_null();

BIO_printf(bio_out, "DECODERs provided by %s:\n", provider);
OSSL_DECODER_do_all_provided(NULL, collect_decoders,
                             decoders);

for (i = 0; i < sk_OSSL_DECODER_num(decoders); i++) {
    OSSL_DECODER *decoder = sk_OSSL_DECODER_value(decoders, i);

    if (strcmp(OSSL_PROVIDER_get0_name(OSSL_DECODER_get0_provider(decoder)),
               provider) != 0)
        continue;

    if (OSSL_DECODER_names_do_all(decoder, print_name, bio_out))
           BIO_printf(bio_out, "\n");
}
sk_OSSL_DECODER_pop_free(decoders, OSSL_DECODER_free);

ate. no crumbs. 🍓

🌸 SEE ALSO 🌸

provider(7), OSSL_DECODER_CTX(3), OSSL_DECODER_from_bio(3), OSSL_DECODER_CTX_new_for_pkey(3), OSSL_LIB_CTX(3) — go read those next, bestie, they're the rest of the lore. 🦋

🎀 HISTORY 🎀

all the functions described here were added in OpenSSL 3.0. so if you're on something older... yeah. iykyk. 😭

Copyright 2020-2024 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>.

⚠️ ok one tiny reminder before you go: that OSSL_DECODER_get0_name() string? borrowed, not yours. do not free it. I will know. 💀

and that's the whole page!! this was OpenSSL version 3.5.9, dated 2026-09-29 — love that for us, mwah, go decode something iconic 💅✨🫶

📦 where this page comes from