OSSL_ENCODER(3ossl)

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

💖 OSSL_ENCODER — encoder method routines 💖

okay bestie, sit down, hydrate, because today we're learning about OSSL_ENCODER, which lives in the 3ossl section of the OpenSSL manual and is genuinely one of the most useful little guys in the whole library. no cap. 🫶

✨ NAME ✨

OSSL_ENCODER, OSSL_ENCODER_fetch, OSSL_ENCODER_up_ref, OSSL_ENCODER_free, OSSL_ENCODER_get0_provider, OSSL_ENCODER_get0_properties, OSSL_ENCODER_is_a, OSSL_ENCODER_get0_name, OSSL_ENCODER_get0_description, OSSL_ENCODER_do_all_provided, OSSL_ENCODER_names_do_all, OSSL_ENCODER_gettable_params, OSSL_ENCODER_get_params — the Encoder method routines, all of them, together, slaying 💅

🌸 SYNOPSIS 🌸

#include <openssl/encoder.h>

typedef struct ossl_encoder_st OSSL_ENCODER;

OSSL_ENCODER *OSSL_ENCODER_fetch(OSSL_LIB_CTX *ctx, const char *name,
                                 const char *properties);
int OSSL_ENCODER_up_ref(OSSL_ENCODER *encoder);
void OSSL_ENCODER_free(OSSL_ENCODER *encoder);
const OSSL_PROVIDER *OSSL_ENCODER_get0_provider(const OSSL_ENCODER *encoder);
const char *OSSL_ENCODER_get0_properties(const OSSL_ENCODER *encoder);
int OSSL_ENCODER_is_a(const OSSL_ENCODER *encoder, const char *name);
const char *OSSL_ENCODER_get0_name(const OSSL_ENCODER *encoder);
const char *OSSL_ENCODER_get0_description(const OSSL_ENCODER *encoder);
void OSSL_ENCODER_do_all_provided(OSSL_LIB_CTX *libctx,
                                  void (*fn)(OSSL_ENCODER *encoder, void *arg),
                                  void *arg);
int OSSL_ENCODER_names_do_all(const OSSL_ENCODER *encoder,
                              void (*fn)(const char *name, void *data),
                              void *data);
const OSSL_PARAM *OSSL_ENCODER_gettable_params(OSSL_ENCODER *encoder);
int OSSL_ENCODER_get_params(OSSL_ENCODER_CTX *ctx, const OSSL_PARAM params[]);

copy that into your editor exactly, do not freestyle it, i am begging 🙈

🦋 DESCRIPTION 🦋

so OSSL_ENCODER is a method for encoders. and what is an encoder, you ask? it's the thing that knows how to take an object of some kind and turn it into an encoded form — like PEM, DER, or honestly even human readable text. it's giving translator, but for data structures. iconic. ✨

OSSL_ENCODER_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 matching the name you gave it and the properties you gave it. here's the tea: the name is what tells you what type of object the fetched encoder method is expected to be able to encode, and the properties are what determine the expected output type. if you wanna know which properties exist and what values they can have, go read "Names and properties" in provider-encoder(7). iykyk 🎀

OSSL_ENCODER_up_ref() bumps the reference count on the encoder you handed it. up, up, and away 🎈

OSSL_ENCODER_free() drops the reference count on the given encoder, and the moment that count hits zero — poof — it frees it. and if the argument is NULL? nothing happens. nothing. we simply do not react. 💅

OSSL_ENCODER_get0_provider() hands you back the provider that owns the given encoder.

OSSL_ENCODER_get0_properties() returns the property definition string that's associated with the given encoder.

OSSL_ENCODER_is_a() checks whether encoder is an implementation of an algorithm that's identifiable with name. vibe check: is this encoder that algorithm? 🔍

OSSL_ENCODER_get0_name() returns the name that was used to fetch the given encoder.

OSSL_ENCODER_get0_description() returns a description of the loader, meant for display and human consumption. yes, it literally says loader in the source text — i don't make the rules bestie, i just report them 😭 — and that description is entirely at the discretion of the loader implementation.

OSSL_ENCODER_names_do_all() walks through all the names for the given encoder and calls fn with each name and data as arguments. every single one. no name left behind. 🌈

OSSL_ENCODER_do_all_provided() traverses all encoder implementations from all activated providers in the library context libctx, and for each of those implementations it calls fn with the implementation method and arg as arguments. it's the group chat of encoders, and fn is the notification. 🔔

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

OSSL_ENCODER_get_params() attempts to get the parameters specified with an OSSL_PARAM(3) array params. and here's the important bit: parameters that the implementation doesn't recognise should be ignored. ignore, don't panic, don't crash, just let it go 🧚

💜 RETURN VALUES 💜

okay so here's what you actually get back, function by function, no surprises:

  • OSSL_ENCODER_fetch() returns a pointer to the key management implementation represented by an OSSL_ENCODER object, or NULL on error.
  • OSSL_ENCODER_up_ref() returns 1 on success, or 0 on error.
  • OSSL_ENCODER_free() doesn't return any value. it's a void. it gives nothing and takes nothing (except your reference count).
  • OSSL_ENCODER_get0_provider() returns a pointer to a provider object, or NULL on error.
  • OSSL_ENCODER_get0_properties() returns a pointer to a property definition string, or NULL on error.
  • OSSL_ENCODER_is_a() returns 1 if the encoder was identifiable, otherwise 0.
  • OSSL_ENCODER_get0_name() returns the algorithm name from the provided implementation for the given encoder. heads up though: the encoder may have multiple synonyms associated with it, and in that case the first name from the algorithm definition is the one you get. also, ownership of the returned string stays with the encoder object — so do not free it yourself, that's not your string, put it down 🙅
  • OSSL_ENCODER_get0_description() returns a pointer to a description, or NULL if there isn't one.
  • OSSL_ENCODER_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. zero names, zero calls, zero notes. 💀

👑 SEE ALSO 👑

go read these next, bestie, they're the extended universe:

⭐ HISTORY ⭐

everything described on this page? added in OpenSSL 3.0. so if you're on some ancient 1.x build wondering where all this is — that's where. it's giving before the glow-up. ✨

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

fr fr, that license bit is not optional. read it. respect it. it's the whole point of the whole thing. 🫶

and that's the page!! this was OpenSSL 3.5.9, dated 2026-09-29, page OSSL_ENCODER(3ossl) — go forth and encode, main character. you ate. periodt. 💖🌈👑

📦 where this page comes from