OSSL_ENCODER(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 OSSL_ENCODER 💅

okay so bestie, welcome to OSSL_ENCODER — that's the manual page name right there, in section 3ossl of the OpenSSL docs. this is genuinely one of my favorite little corner of the OpenSSL API and i'm gonna walk you through it, no gatekeeping 🫶

✨ 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 — these are the encoder method routines 🎀

like, the whole girl squad. one function per line, all of them iconic, all of them here.

🌸 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 verbatim, don't be cute with it, it compiles exactly like that 💖

🦋 DESCRIPTION 🦋

so like, OSSL_ENCODER is a method for encoders. and what do encoders do? they know how to encode an object of some kind into an encoded form — think PEM, DER, or even human readable text. that's their whole personality. main character behavior honestly 🔥

  • OSSL_ENCODER_fetch() — looks for an algorithm inside the provider that's been loaded into the OSSL_LIB_CTX you passed as ctx, with the name you gave as name and the properties you gave as properties. the name decides what type of object the fetched encoder method is supposed to be able to encode, and the properties are what determines the expected output type. wanna know the known properties and the values they can have? go peek at "Names and properties" in provider-encoder(7). iykyk 💅
  • OSSL_ENCODER_up_ref() — bumps the reference count on the given encoder up by one. very "i'm keeping you around" of you.
  • OSSL_ENCODER_free() — decrements the reference count on the given encoder, and when the count hits zero, it frees it. and if the argument is NULL? nothing happens. it just. does nothing. respect honestly 🙈
  • OSSL_ENCODER_get0_provider() — hands you the provider of the given encoder.
  • OSSL_ENCODER_get0_properties() — hands you the property definition that's associated with the given encoder.
  • OSSL_ENCODER_is_a() — vibe checks whether encoder is an implementation of an algorithm that's identifiable with name 🎀
  • 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. and noted: the description is entirely at the discretion of the loader implementation. so like, whatever the loader feels like saying, bestie.
  • OSSL_ENCODER_names_do_all() — walks every name for the given encoder, and calls fn with each name and data as arguments.
  • OSSL_ENCODER_do_all_provided() — walks all encoder implementations across all activated providers in the library context libctx, and for each of those implementations, calls fn with the implementation method and arg as arguments.
  • OSSL_ENCODER_gettable_params() — returns an OSSL_PARAM(3) array of parameter descriptors.
  • OSSL_ENCODER_get_params() — tries to get parameters specified with an OSSL_PARAM(3) array params. any parameters the implementation doesn't recognise should just be ignored. not me being unbothered ✨

⭐ RETURN VALUES ⭐

this is the part where we find out what we actually get back, so pay attention bestie 👑

  • OSSL_ENCODER_fetch() returns a pointer to the key management implementation represented by an OSSL_ENCODER object, or NULL on error. (yes, it really says key management in there, i don't make the rules, i just report them 💀)
  • OSSL_ENCODER_up_ref() returns 1 on success, or 0 on error.
  • OSSL_ENCODER_free() doesn't return any value. it's giving "i don't owe you a response".
  • 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 what gets returned. ownership of the returned string stays with the encoder object, so the caller should not free it. do not touch, do not free, it's not yours, periodt 💅
  • 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. that's the whole scale, 1 or 0, no in-between 😭

🌈 SEE ALSO 🌈

go read these next, they're the friends of this page and they all slay:

🧚 HISTORY 🧚

the functions described here were added in OpenSSL 3.0. so like, they've been around, they're not new new, they're 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>.

okay that's the whole page, you made it, i'm so proud of you 🥹💜 this was OSSL_ENCODER(3ossl) from the OpenSSL 3.5.0 docs, dated 2026-09-25 — go encode something cute, mwah 😘🫶

📦 where this page comes from