OSSL_ENCODER(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💖 OSSL_ENCODER(3ossl) 💖

okay bestie, buckle up, because this is the OSSL_ENCODER(3ossl) page and it's giving "the whole encoder method routine situation," and honestly? kinda iconic.

Here's the whole squad of functions this page covers, so you know who's at the party:

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 — all of them are Encoder method routines. main character energy fr fr 💅

✨ 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[]);

🌸 DESCRIPTION 🌸

so like. OSSL_ENCODER is a method for encoders — and encoders are the lil guys who know how to take an object of some kind and encode it into an encoded form. examples? PEM, DER, or even human readable text. versatile queen behavior 👑

🎀 OSSL_ENCODER_fetch 🎀

OSSL_ENCODER_fetch() goes looking for an algorithm inside the provider that's been loaded into the OSSL_LIB_CTX you handed it as ctx, matching the name you gave and the properties you gave. easy enough.

now the important part: the name determines what type of object the fetched encoder method is expected to be able to encode, and the properties determine the expected output type. got it? good, because there will be a quiz.

for the known properties and the values they can have, go peek at "Names and properties" in provider-encoder(7). iykyk 📖

💜 OSSL_ENCODER_up_ref 💜

OSSL_ENCODER_up_ref() bumps the reference count for the given encoder up by one. keeping it alive, keeping it thriving 🫶

🦋 OSSL_ENCODER_free 🦋

OSSL_ENCODER_free() brings the reference count for the given encoder down by one, and the moment that count hits zero — she's freed. gone. released into the void 😭

pro tip though: if the argument is NULL, literally nothing happens. no crash, no drama, we just move on.

🌈 OSSL_ENCODER_get0_provider 🌈

OSSL_ENCODER_get0_provider() returns the provider of the given encoder. that's it, that's the whole thing.

⭐ OSSL_ENCODER_get0_properties ⭐

OSSL_ENCODER_get0_properties() returns the property definition associated with the given encoder.

🍓 OSSL_ENCODER_is_a 🍓

OSSL_ENCODER_is_a() checks whether encoder is an implementation of an algorithm that's identifiable with name. the vibe check function, basically.

🧚 OSSL_ENCODER_get0_name 🧚

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

💀 OSSL_ENCODER_get0_description 💀

OSSL_ENCODER_get0_description() returns a description of the loader, meant for display and human consumption. and that description is entirely at the discretion of the loader implementation — yeah, the page says loader, we're not gonna interrogate it, we're just gonna report it 🙈

🔥 OSSL_ENCODER_names_do_all 🔥

OSSL_ENCODER_names_do_all() traverses all the names for the given encoder, and calls fn with each name and data as arguments. every single name gets a turn, no skipping the line 💅

👑 OSSL_ENCODER_do_all_provided 👑

OSSL_ENCODER_do_all_provided() traverses all encoder implementations across all activated providers in the library context libctx, and for each one of those implementations, it calls fn with the implementation method and arg as arguments. the full tour, no cap.

🌸 OSSL_ENCODER_gettable_params 🌸

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

✨ OSSL_ENCODER_get_params ✨

OSSL_ENCODER_get_params() tries to get parameters specified with an OSSL_PARAM(3) array params. and heads up: parameters the implementation doesn't recognise should just be ignored. no errors, no sulking, just ignore ✌️

💖 RETURN VALUES 💖

okay this is the part where we find out what you actually get back. pay attention bestie:

  • 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. she gives nothing and that's fine.
  • 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 of encoder was identifiable, otherwise 0. (yes, we know, it says "of" — we're keeping it, it's canon)
  • OSSL_ENCODER_get0_name() returns the algorithm name from the provided implementation for the given encoder. and listen — the encoder may have multiple synonyms associated with it. in that case, the first name from the algorithm definition is the one you get. also: ownership of the returned string is retained by the encoder object, so do not free it yourself, the caller does not get custody 🫵
  • 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.
ngl the names_do_all one is a little unhinged — it's 0 for "never called at all," not "called for some but not all." read it twice. 🫠

🎀 SEE ALSO 🎀

go read these next, they're all part of the lore:

provider(7), OSSL_ENCODER_CTX(3), OSSL_ENCODER_to_bio(3), OSSL_ENCODER_CTX_new_for_pkey(3), OSSL_LIB_CTX(3)

🦋 HISTORY 🦋

the functions described here were added in OpenSSL 3.0. so they're not ancient, they're just established 💅

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

and that's the whole page, bestie 🫶 go encode something gorgeous. this was 3.5.6, dated 2026-04-07, and it was giving OSSL_ENCODER(3ossl) the entire time — periodt 💖✨🎀

📦 where this page comes from