OSSL_STORE_LOADER(3ossl)
🌸 OSSL_STORE_LOADER 🌸
ok so first things first: this is OSSL_STORE_LOADER(3ossl), i.e. the OpenSSL 3ossl manual, and it's the page about STORE loaders — the little guys that know how to handle different URI schemes. Part 1 of the tea, bestie, so buckle up 🫶
🎀 NAME 🎀
The whole squad of types and functions on this page is here to manipulate, register and unregister STORE loaders for different URI schemes. That's the vibe. Here's literally everyone invited to the party ✨
The loader object itself, and the modern (non-deprecated) crew:
OSSL_STORE_LOADER— the main character,typedef struct ossl_store_loader_st OSSL_STORE_LOADER;OSSL_STORE_LOADER_fetch,OSSL_STORE_LOADER_up_ref,OSSL_STORE_LOADER_free— the fetch-it / refcount-it / yeet-it trio 💅OSSL_STORE_LOADER_get0_provider,OSSL_STORE_LOADER_get0_properties,OSSL_STORE_LOADER_is_a,OSSL_STORE_LOADER_get0_description— all theget0_getters plus theis_acheck, the info-gathering bestiesOSSL_STORE_LOADER_do_all_provided,OSSL_STORE_LOADER_names_do_all— the "iterate over everything" girliesOSSL_STORE_register_loader,OSSL_STORE_unregister_loader— registering and unregistering, no cap 🌈
The deprecated era (still invited, but like… legacy):
OSSL_STORE_LOADER_new,OSSL_STORE_LOADER_get0_engine,OSSL_STORE_LOADER_get0_schemeOSSL_STORE_LOADER_CTX— the context type, and yes it's defined differently by each loader 🦋OSSL_STORE_LOADER_set_open+OSSL_STORE_open_fnOSSL_STORE_LOADER_set_open_ex+OSSL_STORE_open_ex_fnOSSL_STORE_LOADER_set_attach+OSSL_STORE_attach_fnOSSL_STORE_LOADER_set_ctrl+OSSL_STORE_ctrl_fnOSSL_STORE_LOADER_set_expect+OSSL_STORE_expect_fnOSSL_STORE_LOADER_set_find+OSSL_STORE_find_fnOSSL_STORE_LOADER_set_load+OSSL_STORE_load_fnOSSL_STORE_LOADER_set_eof+OSSL_STORE_eof_fnOSSL_STORE_LOADER_set_error+OSSL_STORE_error_fnOSSL_STORE_LOADER_set_close+OSSL_STORE_close_fn
every single one of those names is on this page, and every single one of them gets its moment, okay? periodt 💖
✨ SYNOPSIS ✨
so you wanna call these? here's the include, bestie, don't forget it:
#include <openssl/store.h>
typedef struct ossl_store_loader_st OSSL_STORE_LOADER;and now the actual function lineup — look at all these signatures, they ate 👑
OSSL_STORE_LOADER *OSSL_STORE_LOADER_fetch(OSSL_LIB_CTX *libctx,
const char *scheme,
const char *properties);
int OSSL_STORE_LOADER_up_ref(OSSL_STORE_LOADER *loader);
void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *loader);
const OSSL_PROVIDER *OSSL_STORE_LOADER_get0_provider(const OSSL_STORE_LOADER *
loader);
const char *OSSL_STORE_LOADER_get0_properties(const OSSL_STORE_LOADER *loader);
const char *OSSL_STORE_LOADER_get0_description(const OSSL_STORE_LOADER *loader);
int OSSL_STORE_LOADER_is_a(const OSSL_STORE_LOADER *loader,
const char *scheme);
void OSSL_STORE_LOADER_do_all_provided(OSSL_LIB_CTX *libctx,
void (*user_fn)(OSSL_STORE_LOADER *loader,
void *arg),
void *user_arg);
int OSSL_STORE_LOADER_names_do_all(const OSSL_STORE_LOADER *loader,
void (*fn)(const char *name, void *data),
void *data);⚠️ okay now the part where I have to be the responsible one: the following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by definingOPENSSL_API_COMPATwith a suitable version value — seeopenssl_user_macros(7). so like, they still exist, but they're giving "left on read since 3.0" 💀 use them and that's on you, not me.
here's the deprecated block in all its glory — every line, exactly as it lives:
OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme);
const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER
*store_loader);
const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER
*store_loader);
/* struct ossl_store_loader_ctx_st is defined differently by each loader */
typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX;
typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)(
const char *uri, const UI_METHOD *ui_method, void *ui_data);
int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_open_fn store_open_function);
typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_ex_fn)(
const char *uri, const UI_METHOD *ui_method, void *ui_data);
int OSSL_STORE_LOADER_set_open_ex
(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_open_ex_fn store_open_ex_function);
typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_attach_fn)
(const OSSL_STORE_LOADER *loader, BIO *bio,
OSSL_LIB_CTX *libctx, const char *propq,
const UI_METHOD *ui_method, void *ui_data);
int OSSL_STORE_LOADER_set_attach(OSSL_STORE_LOADER *loader,
OSSL_STORE_attach_fn attach_function);
typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd,
va_list args);
int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_ctrl_fn store_ctrl_function);
typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected);
int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader,
OSSL_STORE_expect_fn expect_function);
typedef int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx,
OSSL_STORE_SEARCH *criteria);
int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader,
OSSL_STORE_find_fn find_function);
typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
UI_METHOD *ui_method,
void *ui_data);
int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_load_fn store_load_function);
typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx);
int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_eof_fn store_eof_function);
typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx);
int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_error_fn store_error_function);
typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx);
int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_close_fn store_close_function);
int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);that's the whole synopsis, and yes I kept every va_list args and every OSSL_STORE_SEARCH *criteria because I would never do you dirty like that 😭 we're literally just getting started over here 💜
💖 DESCRIPTION 💖
Okay bestie, so OSSL_STORE_LOADER is a method — the blueprint vibe — for OSSL_STORE loaders. And what do loaders do? They implement OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_load(), OSSL_STORE_eof(), OSSL_STORE_error() and OSSL_STORE_close() for specific storage schemes. That's the whole gig. Each scheme gets its own little loader bestie to handle the actual fetching. 🎀
OSSL_STORE_LOADER_fetch() goes looking for an implementation for a storage scheme, and it searches inside the providers that have been loaded into the OSSL_LIB_CTX given by libctx, filtered by the properties given by properties. Like a vibe check but for providers. ✨
OSSL_STORE_LOADER_up_ref() bumps the reference count for the given loader. Up, up, up 🔥
OSSL_STORE_LOADER_free() decrements the reference count for the given loader, and when the count hits zero, it frees it. And if the argument is NULL, nothing is done. Nothing. Zero. Nada. It literally says "if the argument is NULL, nothing is done" and honestly slay for the safety. 💅
OSSL_STORE_LOADER_get0_provider() returns the provider of the given loader — who's your parent, bestie?
OSSL_STORE_LOADER_get0_properties() returns the property definition associated with the given loader.
OSSL_STORE_LOADER_is_a() checks if loader is an implementation of an algorithm that's identifiable with scheme. Basically "are you who you say you are" 🦋
OSSL_STORE_LOADER_get0_description() returns a description of the loader, meant for display and human consumption. And the tea? The description is at the discretion of the loader implementation. So like, whatever the loader feels like saying about itself. 🙈
OSSL_STORE_LOADER_do_all_provided() traverses all store implementations by all activated providers in the library context libctx, and for each of the implementations, calls user_fn with the implementation method and user_arg as arguments. It's giving "roll call, everybody say hi". 👑
OSSL_STORE_LOADER_names_do_all() traverses all names for the given loader, and calls fn with each name and data.
🧚 Legacy Types and Functions (deprecated) 🧚
Okay so these functions help applications and engines create loaders for schemes they support. But — and I need you to hear me — these are all deprecated and discouraged in favour of provider implementations. See provider-storemgmt(7). Like, they're cute, they're vintage, they're giving 1.1.1 nostalgia, but we've moved on. 💀
OSSL_STORE_LOADER_CTX is a type template, to be defined by each loader using "struct ossl_store_loader_ctx_st { ... }".
OSSL_STORE_open_fn, OSSL_STORE_open_ex_fn, OSSL_STORE_ctrl_fn, OSSL_STORE_expect_fn, OSSL_STORE_find_fn, OSSL_STORE_load_fn, OSSL_STORE_eof_fn, and OSSL_STORE_close_fn are the function pointer types used within a STORE loader. The functions pointed at define the functionality of the given loader. They're the whole personality of the loader honestly. 🌸
🌈 OSSL_STORE_open_fn and OSSL_STORE_open_ex_fn
OSSL_STORE_open_ex_fn takes a URI and is expected to interpret it in the best manner possible according to the scheme the loader implements. Main character energy: best manner possible, no notes. 💅
It also takes a UI_METHOD and associated data, to be used any time something needs to be prompted for, as well as a library context libctx with an associated property query propq, to be used when fetching necessary algorithms to perform the loads.
Furthermore, this function is expected to initialize what needs to be initialized, to create a private data store (OSSL_STORE_LOADER_CTX, see above), and to return it. If something goes wrong, this function is expected to return NULL. 😭
OSSL_STORE_open_fn does the same thing as OSSL_STORE_open_ex_fn but uses NULL for the library context libctx and property query propq. Same vibe, fewer args. ✨
🫶 OSSL_STORE_attach_fn
This function takes a BIO, otherwise works like OSSL_STORE_open_ex_fn. That's it. That's the whole subsection. Short but iconic. 🎀
⭐ OSSL_STORE_ctrl_fn
This function takes a OSSL_STORE_LOADER_CTX pointer, a command number cmd and a va_list args and is used to manipulate loader specific parameters.
Loader specific command numbers must begin at OSSL_STORE_C_CUSTOM_START. Any number below that is reserved for future globally known command numbers. Respect the boundary, bestie 🚧
This function is expected to return 1 on success, 0 on error.
🦋 OSSL_STORE_expect_fn
This function takes a OSSL_STORE_LOADER_CTX pointer and a OSSL_STORE_INFO identity expected, and is used to tell the loader what object type is expected. expected may be zero to signify that no specific object type is expected. Zero means "surprise me" ig 💜
This function is expected to return 1 on success, 0 on error.
🍓 OSSL_STORE_find_fn
This function takes a OSSL_STORE_LOADER_CTX pointer and a OSSL_STORE_SEARCH search criterion, and is used to tell the loader what to search for. Detective mode activated 🔍
When called with the loader context being NULL, this function is expected to return 1 if the loader supports the criterion, otherwise 0.
When called with the loader context being something other than NULL, this function is expected to return 1 on success, 0 on error.
🌸 OSSL_STORE_load_fn
This function takes a OSSL_STORE_LOADER_CTX pointer and a UI_METHOD with associated data. It's expected to load the next available data, mold it into a data structure that can be wrapped in a OSSL_STORE_INFO using one of the OSSL_STORE_INFO(3) functions. Molding! Like clay but data 🫶
If no more data is available or an error occurs, this function is expected to return NULL. The OSSL_STORE_eof_fn and OSSL_STORE_error_fn functions must indicate if it was in fact the end of data or if an error occurred. They're the ones who call it, okay?? 😤
Note that this function retrieves one data item only. One. Not two. Not a bundle. One. 🎯
💀 OSSL_STORE_eof_fn
This function takes a OSSL_STORE_LOADER_CTX pointer and is expected to return 1 to indicate that the end of available data has been reached. It is otherwise expected to return 0. The "we're so done here" check ✌️
🙈 OSSL_STORE_error_fn
This function takes a OSSL_STORE_LOADER_CTX pointer and is expected to return 1 to indicate that an error occurred in a previous call to the OSSL_STORE_load_fn function. It is otherwise expected to return 0. Retroactive snitching, but make it useful 💅
🎀 OSSL_STORE_close_fn
This function takes a OSSL_STORE_LOADER_CTX pointer and is expected to close or shut down what needs to be closed, and finally free the contents of the OSSL_STORE_LOADER_CTX pointer. It returns 1 on success and 0 on error. Cleanup era, we love to see it 🧹✨
OSSL_STORE_LOADER_new() creates a new OSSL_STORE_LOADER. It takes an ENGINE e and a string scheme. scheme must always be set. Both e and scheme are used as is and must therefore be alive as long as the created loader is. No borrowing-and-then-dipping, bestie — they gotta stick around 💖
OSSL_STORE_LOADER_get0_engine() returns the engine of the store_loader. OSSL_STORE_LOADER_get0_scheme() returns the scheme of the store_loader.
OSSL_STORE_LOADER_set_open() sets the opener function for the store_loader.
OSSL_STORE_LOADER_set_open_ex() sets the opener with library context function for the store_loader.
OSSL_STORE_LOADER_set_attach() sets the attacher function for the store_loader.
OSSL_STORE_LOADER_set_ctrl() sets the control function for the store_loader.
OSSL_STORE_LOADER_set_expect() sets the expect function for the store_loader.
OSSL_STORE_LOADER_set_load() sets the loader function for the store_loader.
OSSL_STORE_LOADER_set_eof() sets the end of file checker function for the store_loader.
OSSL_STORE_LOADER_set_close() sets the closing function for the store_loader.
OSSL_STORE_LOADER_free() frees the given store_loader. If the argument is NULL, nothing is done. Again! Nothing! Protected! 🛡️
OSSL_STORE_register_loader() register the given store_loader and thereby makes it available for use with OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close(). It's on the list now 💫
OSSL_STORE_unregister_loader() unregister the store loader for the given scheme. Bye bestie 👋
✨ RETURN VALUES ✨
OSSL_STORE_LOADER_fetch()returns a pointer to anOSSL_STORE_LOADERobject, orNULLon error.OSSL_STORE_LOADER_up_ref()returns1on success, or0on error.OSSL_STORE_LOADER_names_do_all()returns1if the callback was called for all names. A return value of0means that the callback was not called for any names. Not "some", any. That distinction is doing heavy lifting ngl 👀OSSL_STORE_LOADER_free()doesn't return any value. It's a void king 👑OSSL_STORE_LOADER_get0_provider()returns a pointer to a provider object, orNULLon error.OSSL_STORE_LOADER_get0_properties()returns a pointer to a property definition string, orNULLon error.OSSL_STORE_LOADER_is_a()returns1if loader was identifiable, otherwise0.OSSL_STORE_LOADER_get0_description()returns a pointer to a description, orNULLif there isn't one. Sometimes there's just no description and that's valid 🦋
The functions with the types OSSL_STORE_open_fn, OSSL_STORE_open_ex_fn, OSSL_STORE_ctrl_fn, OSSL_STORE_expect_fn, OSSL_STORE_load_fn, OSSL_STORE_eof_fn and OSSL_STORE_close_fn have the same return values as OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_ctrl(), OSSL_STORE_expect(), OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close(), respectively. Matching set, slay 💅
OSSL_STORE_LOADER_new()returns a pointer to aOSSL_STORE_LOADERon success, orNULLon failure.OSSL_STORE_LOADER_set_open(),OSSL_STORE_LOADER_set_open_ex(),OSSL_STORE_LOADER_set_ctrl(),OSSL_STORE_LOADER_set_load(),OSSL_STORE_LOADER_set_eof()andOSSL_STORE_LOADER_set_close()return1on success, or0on failure.OSSL_STORE_register_loader()returns1on success, or0on failure.OSSL_STORE_unregister_loader()returns the unregistered loader on success, orNULLon failure. You get the actual loader back, cute 🎁
🌈 SEE ALSO 🌈
ossl_store(7), OSSL_STORE_open(3), OSSL_LIB_CTX(3), provider-storemgmt(7)
Go read those, they're the supporting cast and they ate 🫶
🕰️ HISTORY 🕰️
OSSL_STORE_LOADER_fetch(), OSSL_STORE_LOADER_up_ref(), OSSL_STORE_LOADER_get0_provider(), OSSL_STORE_LOADER_get0_properties(), OSSL_STORE_LOADER_get0_description(), OSSL_STORE_LOADER_is_a(), OSSL_STORE_LOADER_do_all_provided() and OSSL_STORE_LOADER_names_do_all() were added in OpenSSL 3.0. Glow-up era 💫
OSSL_STORE_LOADER and OSSL_STORE_LOADER_free() were added in OpenSSL 1.1.1.
OSSL_STORE_LOADER_set_open_ex() and OSSL_STORE_open_ex_fn() were added in OpenSSL 3.0, and are deprecated. Added and deprecated basically in the same breath, the whiplash 😭
OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new(), OSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_get0_scheme(), OSSL_STORE_LOADER_get0_engine(), OSSL_STORE_LOADER_set_expect(), OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_attach(), OSSL_STORE_LOADER_set_open_ex(), OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_eof(), OSSL_STORE_LOADER_set_close(), OSSL_STORE_register_loader(), OSSL_STORE_LOADER_set_error(), OSSL_STORE_unregister_loader(), OSSL_STORE_open_fn(), OSSL_STORE_ctrl_fn(), OSSL_STORE_load_fn(), OSSL_STORE_eof_fn() and OSSL_STORE_close_fn() were added in OpenSSL 1.1.1, and became deprecated in OpenSSL 3.0. They had their moment, we respect the legacy 💜
©️ COPYRIGHT ©️
Copyright 2016-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 — no cap, you're now fully briefed on store loaders 🫶✨ This one came from the OpenSSL docs, version 3.5.6, dated 2026-04-07, and the page signs off as OSSL_STORE_LOADER(3ossl). Go forth and load 💅💖
📦 where this page comes from
- freebsd 15.1: base 15.1
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms