OSSL_PROVIDER(3SSL)

📦

version 4.0.3 · 13 versions

👑 OSSL_PROVIDER — provider routines (3SSL) 💖

okay bestie, sit down, hydrate, because this is the manual page for the OpenSSL provider API and it is a lot — but it's also lowkey iconic once you get the vibe. This is part 1 of 2, so don't go anywhere. ✨

🌸 NAME 🌸

OSSL_PROVIDER_set_default_search_path, OSSL_PROVIDER_get0_default_search_path, OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_try_load, OSSL_PROVIDER_unload, OSSL_PROVIDER_load_ex, OSSL_PROVIDER_try_load_ex, OSSL_PROVIDER_available, OSSL_PROVIDER_do_all, OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params, OSSL_PROVIDER_query_operation, OSSL_PROVIDER_unquery_operation, OSSL_PROVIDER_get0_provider_ctx, OSSL_PROVIDER_get0_dispatch, OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_get0_name, OSSL_PROVIDER_get_capabilities, OSSL_PROVIDER_add_conf_parameter, OSSL_PROVIDER_get_conf_parameters, OSSL_PROVIDER_conf_get_bool, OSSL_PROVIDER_self_test — provider routines.

that's the whole squad. every single one of them. 💅

✨ SYNOPSIS ✨

#include <openssl/provider.h>

typedef struct ossl_provider_st OSSL_PROVIDER;

int OSSL_PROVIDER_set_default_search_path(OSSL_LIB_CTX *libctx,
                                          const char *path);
const char *OSSL_PROVIDER_get0_default_search_path(OSSL_LIB_CTX *libctx);

OSSL_PROVIDER *OSSL_PROVIDER_load(OSSL_LIB_CTX *libctx, const char *name);
OSSL_PROVIDER *OSSL_PROVIDER_load_ex(OSSL_LIB_CTX *, const char *name,
                                     OSSL_PARAM *params);
OSSL_PROVIDER *OSSL_PROVIDER_try_load(OSSL_LIB_CTX *libctx, const char *name,
                                      int retain_fallbacks);
OSSL_PROVIDER *OSSL_PROVIDER_try_load_ex(OSSL_LIB_CTX *, const char *name,
                                         OSSL_PARAM *params,
                                         int retain_fallbacks);
int OSSL_PROVIDER_unload(OSSL_PROVIDER *prov);
int OSSL_PROVIDER_available(OSSL_LIB_CTX *libctx, const char *name);
int OSSL_PROVIDER_do_all(OSSL_LIB_CTX *ctx,
                         int (*cb)(OSSL_PROVIDER *provider, void *cbdata),
                         void *cbdata);

const OSSL_PARAM *OSSL_PROVIDER_gettable_params(OSSL_PROVIDER *prov);
int OSSL_PROVIDER_get_params(OSSL_PROVIDER *prov, OSSL_PARAM params[]);

const OSSL_ALGORITHM *OSSL_PROVIDER_query_operation(const OSSL_PROVIDER *prov,
                                                    int operation_id,
                                                    int *no_cache);
void OSSL_PROVIDER_unquery_operation(const OSSL_PROVIDER *prov,
                                     int operation_id,
                                     const OSSL_ALGORITHM *algs);
void *OSSL_PROVIDER_get0_provider_ctx(const OSSL_PROVIDER *prov);
const OSSL_DISPATCH *OSSL_PROVIDER_get0_dispatch(const OSSL_PROVIDER *prov);

int OSSL_PROVIDER_add_builtin(OSSL_LIB_CTX *libctx, const char *name,
                              ossl_provider_init_fn *init_fn);

const char *OSSL_PROVIDER_get0_name(const OSSL_PROVIDER *prov);

int OSSL_PROVIDER_get_capabilities(const OSSL_PROVIDER *prov,
                                   const char *capability,
                                   OSSL_CALLBACK *cb,
                                   void *arg);
int OSSL_PROVIDER_add_conf_parameter(OSSL_PROVIDER *prov, const char *name,
                                     const char *value);
int OSSL_PROVIDER_get_conf_parameters(OSSL_PROVIDER *prov,
                                      OSSL_PARAM params[]);
int OSSL_PROVIDER_conf_get_bool(const OSSL_PROVIDER *prov,
                                const char *name, int defval);
int OSSL_PROVIDER_self_test(const OSSL_PROVIDER *prov);

look at all those signatures. no cap, it's giving "wall of C" but we're gonna get through it together. 🫶

🦋 DESCRIPTION 🦋

OSSL_PROVIDER is literally the type that holds all the internal tea — the bookkeeping info — about implementation providers. (if you're like "bestie what even is a provider", go read provider(7), it explains the whole concept.) a provider can be baked right into your application or into the OpenSSL libraries themselves, or it can be a loadable module — a lil plugin that shows up at runtime. and bestie, the functions described down here? they handle both forms. equal opportunity API. 😌

some of these functions operate inside a library context, so if you need the deets on that, go check OSSL_LIB_CTX(3). 💜

🌈 Functions 🌈

OSSL_PROVIDER_set_default_search_path() — sets the default search path used when looking for providers in the given libctx. if you never set it, an environment variable and a fallback default value get used instead. (so like, it has a backup plan. iconic.)
OSSL_PROVIDER_get0_default_search_path() — grabs the default search path used for finding providers in the given libctx. if it works, you get the path or an empty string. this path stays valid until the context is released or until somebody calls OSSL_PROVIDER_set_default_search_path(). so don't hoard it forever, it's not yours forever. 🎀
OSSL_PROVIDER_add_builtin() — adds a built-in provider to the OSSL_PROVIDER store inside the given library context, by pairing a provider name with a provider initialization function. after that you can use that name with OSSL_PROVIDER_load(). matchmaking, but for providers. 💖
OSSL_PROVIDER_load() — loads and initializes a provider. this might just initialize a provider you already added with OSSL_PROVIDER_add_builtin() and run the init function it was given — or it might load a provider module with the given name and run its provider entry point, "OSSL_provider_init". the name can also be a path to a provider module, and in that case the provider name that OSSL_PROVIDER_get0_name() gives you back will be that path. fair warning: how relative paths get interpreted is platform dependent, and they're relative to the configured "MODULESDIR" directory, or to whatever path is in the environment variable OPENSSL_MODULES if that's set. 🧚
OSSL_PROVIDER_try_load() — works like OSSL_PROVIDER_load() with one big difference: it does not disable the fallback providers if the provider can't be loaded and initialized, or if retain_fallbacks is nonzero. and if the provider does load successfully and retain_fallbacks is zero? then yeah, the fallback providers get disabled. it tried. it's in the name. 😌
OSSL_PROVIDER_load_ex() and OSSL_PROVIDER_try_load_ex() — the variants of the two functions above that also take an "OSSL_PARAM" array of parameters, which get passed as the configuration of the loaded provider. heads up: any parameter that isn't of type "OSSL_PARAM_UTF8_STRING" is silently ignored 💀. and if you do provide parameters, they replace all the ones specified in the configuration file. all of them. no merging. periodt.
OSSL_PROVIDER_unload() — unloads the given provider. if the provider was added with OSSL_PROVIDER_add_builtin(), this just runs its teardown function. and btw? you do not have to explicitly unload providers before calling OSSL_LIB_CTX_free(3) — freeing a library context automatically deactivates and frees every provider associated with it. self-cleaning queen. ✨

⚠️ but ABSOLUTELY do not call OSSL_PROVIDER_unload() after you've already called OSSL_LIB_CTX_free(3) on the associated library context. that's not it. don't do that. 🙈

OSSL_PROVIDER_available() — checks whether a named provider is available for use. simple. cute. does what it says.
OSSL_PROVIDER_do_all() — iterates over all loaded providers, calling cb for each one, with the current provider in provider and the cbdata that came from you, the caller. and here's a lil plot twist: if no other provider has been loaded before you call this function, the default provider is still available as a fallback. see OSSL_PROVIDER-default(7) for more on that fallback behaviour. 🌸
OSSL_PROVIDER_gettable_params() — used to get a provider parameter descriptor set as a constant OSSL_PARAM(3) array.
OSSL_PROVIDER_get_params() — used to get provider parameter values. you, the caller, have to prepare the OSSL_PARAM(3) array before calling this, and the variables acting as buffers for that parameter array should be filled with data when it returns successfully. prep first, then serve. 💅
OSSL_PROVIDER_add_conf_parameter() — sets the provider configuration parameter name to value. provider configuration parameters are managed by the OpenSSL core and normally get set in the configuration file — but they can also be set early in the main program before a provider is in use by multiple threads. 🫶 now listen, this part matters: parameters that only affect provider initialisation must, for now, be set in the configuration file; only parameters that also get queried later have any effect when set through this interface. and only text parameters can be given, and it's up to the provider to interpret them. no pressure, no promises.
OSSL_PROVIDER_get_conf_parameters() — retrieves the global configuration parameters associated with prov. these config parameters are stored for each provider by the OpenSSL core — not by the provider itself. (parameters managed by the provider are queried via OSSL_PROVIDER_get_params(), described above, so don't mix them up bestie 😭). the parameters come back by reference, not as copies, which means the elements of the param array must have OSSL_PARAM_UTF8_PTR as their data_type. pointers only. no copy-paste energy.
OSSL_PROVIDER_conf_get_bool() — parses the global configuration parameter name associated with provider prov as a boolean value, and returns the default value defval when it can't retrieve or parse the parameter. here's the scoring rubric: values equal (case-insensitively) to 1, "on", "yes", or "true" yield a true (nonzero) result. values equal (case-insensitively) to 0, "off", "no", or "false" yield a false (zero) result. yes means yes, no means no. 🌈
OSSL_PROVIDER_self_test() — runs a provider's self tests on demand. now the serious bit: if the self tests fail, then the provider will fail to provide any further services and algorithms. that's it, done, lights out. 😭 you can call OSSL_SELF_TEST_set_callback(3) beforehand to display diagnostics for the self tests while they're running.
OSSL_PROVIDER_query_operation() — calls the provider's query_operation function (see provider(7)), if the provider has one. it returns an array of OSSL_ALGORITHM for the given operation_id, terminated by an all-NULL OSSL_ALGORITHM entry. this is considered a low-level function that most applications should not need to call. so like... unless you know, you don't. iykyk. ⭐
OSSL_PROVIDER_unquery_operation() — calls the provider's unquery_operation function (see provider(7)), if the provider has one. also a low-level function that most applications should not need to call. same vibe, opposite direction. 🦋
OSSL_PROVIDER_get0_provider_ctx() — returns the provider context for the given provider. that context is an opaque handle set by the provider itself, and it gets passed back to the provider by libcrypto in various function calls. it's the provider's own lil secret handshake. 🤝
OSSL_PROVIDER_get0_dispatch() — returns the provider's dispatch table, exactly as it was returned in the out parameter from the provider's init function. see provider-base(7). 📋
and then this: if it is permissible to cache references to this array, then *no_store is set to 0 or 1 otherwise. if the array is not cacheable, then it is assumed to have a short lifetime. so like, cache it or don't, but know what you're getting into. 🫠
OSSL_PROVIDER_get0_name() — returns the name of the given provider. short, sweet, and it ate. 💅
OSSL_PROVIDER_get_capabilities() — gives you info about the capabilities supported by the provider specified in prov, for the capability named capability. for each capability of that name supported by the provider, it calls the callback cb and supplies a set of OSSL_PARAM(3)s describing that capability. it'll also pass back the argument arg. for more details about capabilities and what they can be used for, please see "CAPABILITIES" in provider-base(7). 💖

part 1 done bestie, more incoming — don't leave me hanging 🎀

✨ RETURN VALUES ✨

okay so here's the vibe check on what these functions hand back to you, bestie:

OSSL_PROVIDER_set_default_search_path(), OSSL_PROVIDER_add(), OSSL_PROVIDER_unload(), OSSL_PROVIDER_get_params(), OSSL_PROVIDER_add_conf_parameter(), OSSL_PROVIDER_get_conf_parameters() and OSSL_PROVIDER_get_capabilities() — they return 1 when everything slays, or 0 when it does not. periodt.
OSSL_PROVIDER_get0_default_search_path() — gives you back a pointer to a path if it worked, or NULL if there was an error or if that path was never set in the first place. no path no pointer, that's the rules 💅
OSSL_PROVIDER_load() and OSSL_PROVIDER_try_load() — return a pointer to a provider object when they succeed, or NULL when they don't. simple as 🫶
OSSL_PROVIDER_do_all() — returns 1 if the callback cb returns 1 for every single provider it gets called with. Returns 0 if any provider callback invocation returns 0. and bestie, heads up: callback processing stops at that first callback invocation on a provider that returns 0. it does not keep going. it's done. 😭
OSSL_PROVIDER_available() — 1 if the named provider is available, 0 otherwise. easy.
OSSL_PROVIDER_gettable_params() — returns a pointer to an array of constant OSSL_PARAM(3), or NULL if none is provided. that's it, that's the whole thing.
OSSL_PROVIDER_get_params() and — returns 1 on success, or 0 on error. (yes bestie the original really does have that stray "and" sitting there, I'm keeping it fr fr, we don't rewrite the source material 💀)
OSSL_PROVIDER_query_operation() — returns an array of OSSL_ALGORITHM, or NULL on error.
OSSL_PROVIDER_self_test() — returns 1 if the self tests pass, or 0 on error. no in-between, no "maybe", we love a binary 🎀

🌸 EXAMPLES 🌸

okay so this little demo right here shows you how to load the provider module "foo" and then ask it for its build info. iconic behavior:

#include <openssl/params.h>
#include <openssl/provider.h>
#include <openssl/err.h>

OSSL_PROVIDER *prov = NULL;
const char *build = NULL;
OSSL_PARAM request[] = {
    { "buildinfo", OSSL_PARAM_UTF8_PTR, &build, 0, 0 },
    { NULL, 0, NULL, 0, 0 }
};

if ((prov = OSSL_PROVIDER_load(NULL, "foo")) != NULL
    && OSSL_PROVIDER_get_params(prov, request))
    printf("Provider 'foo' buildinfo: %s\n", build);
else
    ERR_print_errors_fp(stderr);

see how it does the load, does the get_params, and only prints if both worked? that's the && doing its main character thing 👑 and if anything flopped, we slide straight into ERR_print_errors_fp(stderr) to find out what went wrong. chef's kiss 😘

👀 SEE ALSO 👀

like, go read these too, they're part of the lore:

📜 HISTORY 📜

receipts, because we always cite our sources:

The type and functions described here were added in OpenSSL 3.0. the OGs.
The OSSL_PROVIDER_load_ex and OSSL_PROVIDER_try_load_ex functions were added in OpenSSL 3.2.
The OSSL_PROVIDER_add_conf_parameter, OSSL_PROVIDER_get_conf_parameters, and OSSL_PROVIDER_conf_get_bool functions were added in OpenSSL 3.5. the fresh new babies ✨

🎀 COPYRIGHT 🎀

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

ngl bestie, "except in compliance with the License" is doing a lot of heavy lifting in that sentence. read the license. for real. 💖

aaaand that's a wrap on OSSL_PROVIDER(3SSL)! this whole thing came to you from OpenSSL 4.0.3, dated 2026-09-29 — go forth and load your providers responsibly, bestie, mwah 🫶💅✨

📦 where this page comes from

ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms