OSSL_DECODER(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

✨ OSSL_DECODER — the decoder method routines (from the OpenSSL manuals, section 3SSL) ✨

okay bestie, gather round 💖 you know 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, and OSSL_DECODER_get_params? yeah. those. the decoder method routines. let's get into it 🎀

🌸 SYNOPSIS 🌸

#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 💅

OSSL_DECODER is a method for decoders, and decoders are literally the ones who know how to turn encoded data into an object of some type that the rest of OpenSSL actually knows how to handle. it's giving translator energy, no cap 🦋

  • OSSL_DECODER_fetch() — hunts for an algorithm inside the provider that's been loaded into the OSSL_LIB_CTX you passed as ctx, matching the name you gave and the properties you gave. the name is what decides which type of object the fetched decoder method is supposed to be able to decode, and the properties are what determine the expected output type. for the known properties and the values they can have, go peek at "Names and properties" in provider-encoder(7) 👀
  • OSSL_DECODER_up_ref() — bumps the reference count on the given decoder ⬆️
  • OSSL_DECODER_free() — drops the reference count on the given decoder, and the second it hits zero, it frees it. if the argument is NULL, nothing happens. she's chill like that 💅
  • OSSL_DECODER_get0_provider() — hands you back the provider of the given decoder 🫶
  • OSSL_DECODER_get0_properties() — hands you back the property definition 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, meant for display and for human consumption. the description is entirely at the discretion of the decoder implementation, so don't come for her if it's weird 🙈
  • 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 all decoder implementations from all activated providers in the library context libctx, and for every single implementation, calls fn with the implementation method and arg as arguments 🌈
  • 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. any parameters the implementation doesn't recognise should just be ignored, we're not forcing anything 💀

🎀 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. queen of saying nothing ✨
  • 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. note that the decoder may have multiple synonyms associated with it 🫠 in that case, the first name from the algorithm definition is returned. ownership of the returned string is retained by the decoder object and should not be freed by the caller — do not touch, she is not yours 💅
  • 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 was not called for any names.

🦋 NOTES 🦋

OSSL_DECODER_fetch() may be called implicitly by other fetching functions, using the same library context and properties. any other API that uses keys will typically do this. so like… she shows up uninvited but it's fine, it's always fine 🫶

🌟 EXAMPLES 🌟

to list all decoders in a provider to a bio_out:

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

fr fr, copy it, run it, it works 👑

👀 SEE ALSO 👀

provider(7), OSSL_DECODER_CTX(3), OSSL_DECODER_from_bio(3), OSSL_DECODER_CTX_new_for_pkey(3), OSSL_LIB_CTX(3)

💜 HISTORY 💜

the functions described here were added in OpenSSL 3.0 ⭐

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

okay that's the whole thing, bestie, no notes 🎀 and for the record: this is from OpenSSL 4.0.3, dated 2026-09-29. icon behavior, honestly. mwah 💋
📦 where this page comes from