OSSL_STORE_LOADER(3SSL)
💖 NAME 💖
okay so. OSSL_STORE_LOADER(3SSL) — that's the OpenSSL 3 manual page we're on, and bestie, it's a whole squad. The official one-liner is types and functions to manipulate, register and unregister STORE loaders for different URI schemes. That's the entire vibe: you got a URI scheme, you got a loader that knows how to deal with it, and this page is the group chat where they all live. 🌈
Roll call, everyone say hi:
OSSL_STORE_LOADER— the main character, the type itself 👑OSSL_STORE_LOADER_fetch— go get oneOSSL_STORE_LOADER_up_ref— add a ref, keep it aliveOSSL_STORE_LOADER_free— let it go 💀OSSL_STORE_LOADER_get0_provider— which provider gave us thisOSSL_STORE_LOADER_get0_properties— the properties it was fetched withOSSL_STORE_LOADER_is_a— are you this scheme?OSSL_STORE_LOADER_get0_description— tell me about yourselfOSSL_STORE_LOADER_do_all_provided— everybody, all at onceOSSL_STORE_LOADER_names_do_all— every name it answers toOSSL_STORE_LOADER_CTX— the per-loader context, each loader defines its ownOSSL_STORE_LOADER_newOSSL_STORE_LOADER_get0_schemeOSSL_STORE_LOADER_set_openOSSL_STORE_LOADER_set_open_exOSSL_STORE_LOADER_set_attachOSSL_STORE_LOADER_set_ctrlOSSL_STORE_LOADER_set_expectOSSL_STORE_LOADER_set_findOSSL_STORE_LOADER_set_loadOSSL_STORE_LOADER_set_eofOSSL_STORE_LOADER_set_errorOSSL_STORE_LOADER_set_closeOSSL_STORE_LOADER_settable_ctx_paramsOSSL_STORE_register_loaderOSSL_STORE_unregister_loaderOSSL_STORE_open_fnOSSL_STORE_open_ex_fnOSSL_STORE_attach_fnOSSL_STORE_ctrl_fnOSSL_STORE_expect_fnOSSL_STORE_find_fnOSSL_STORE_load_fnOSSL_STORE_eof_fnOSSL_STORE_error_fnOSSL_STORE_close_fn
and every single one of them is here for the same reason: to manipulate, register and unregister STORE loaders for different URI schemes. no notes. periodt. 💅
✨ SYNOPSIS ✨
first, the include. don't forget it, it's giving "I didn't read the docs" energy if you skip it:
#include <openssl/store.h>then the type, and the whole modern crew:
typedef struct ossl_store_loader_st OSSL_STORE_LOADER;
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);
const OSSL_PARAM *
OSSL_STORE_LOADER_settable_ctx_params(const OSSL_STORE_LOADER *loader);now. the plot twist. everything below this line has been deprecated since OpenSSL 3.0, and you can hide it entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7). that's not me being dramatic, that's literally what it says. 🫠
OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme);
const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER
*store_loader);and here's the part where each loader gets to be its own lil person, because struct ossl_store_loader_ctx_st is defined differently by each loader — no cap, that comment is in the source:
/* struct ossl_store_loader_ctx_st is defined differently by each loader */
typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX;the function-pointer girlies, all set through their setters:
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);and finally, the two that handle the whole "is this loader even in the building" question:
int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);🔥 so that's the shape of it — the type, the refcounting, the introspection, the deprecated ENGINE-era setters, every function pointer typedef, and the register/unregister pair. slate clean, everything accounted for. hold that thought though, because this page does not stop here —
✨ DESCRIPTION ✨
Okay so OSSL_STORE_LOADER is a method for OSSL_STORE loaders 💖 Like, it's the blueprint. An actual loader implements OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_load(), OSSL_STORE_eof(), OSSL_STORE_error() and OSSL_STORE_close() — one specific storage scheme each. One scheme, one glow-up. ✨
OSSL_STORE_LOADER_fetch() goes hunting for an implementation of a storage scheme among the providers loaded into the OSSL_LIB_CTX you passed as libctx, filtered by whatever properties you gave it. It's giving "vibe check the providers". 🔍
OSSL_STORE_LOADER_up_ref() bumps the reference count on the loader you handed it. One more, bestie. ⬆️
OSSL_STORE_LOADER_free() drops the reference count, and when it hits zero, it frees the thing entirely. And if the argument is NULL? Literally nothing happens, it just says "ok" and moves on. 💀
OSSL_STORE_LOADER_get0_provider() hands back the provider of the given loader.
OSSL_STORE_LOADER_get0_properties() hands back the property definition string that goes with that loader.
OSSL_STORE_LOADER_is_a() checks whether loader is an implementation of an algorithm that's identifiable with <italic>scheme*. Slay, or not slay. 🎀
OSSL_STORE_LOADER_get0_description() gives you a description of the loader, meant for display and human consumption (i.e. so people can read it 🫶). The description is completely at the discretion of the loader implementation — they can write whatever.
OSSL_STORE_LOADER_do_all_provided() walks every store implementation across every activated provider in the library context libctx, and for each one it calls user_fn with the implementation method and user_arg. Every single one. No skipping. 👑
OSSL_STORE_LOADER_names_do_all() walks all the names of the given loader, calling fn with each name and data.
OSSL_STORE_LOADER_settable_ctx_params() returns a constant OSSL_PARAM(3) array describing the names and types of key parameters that can be passed to OSSL_STORE_open_ex(3). It's the menu 📋.
🕰️ Legacy Types and Functions (deprecated) 🕰️
⚠️ Bestie, listen. Everything in this section is deprecated. It's all discouraged in favour of provider implementations — go read provider-storemgmt(7). This is the lore,, not the move. 🙈
These functions exist to help applications build loaders for the schemes they support. Cute of them. But no. 💅
OSSL_STORE_LOADER_CTX is a type template — each loader defines its own with "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 inside a STORE loader. The functions they point at define the functionality of a given loader — that's the whole personality right there. ✨
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. It also takes a UI_METHOD and associated data, to be used any time something needs to be prompted for (yes, prompted, like, it needs to ask a human 😭), plus a library context libctx with an associated property query propq, which get used when fetching the algorithms necessary to do the loads.
On top of all that, this function is expected to initialize whatever needs initializing, create a private data store (OSSL_STORE_LOADER_CTX, see above 👆), and return it. If something goes wrong? It returns NULL. Sad.
OSSL_STORE_open_fn does the exact same thing, but it uses NULL for the library context libctx and the property query propq.
OSSL_STORE_attach_fn
This function takes a BIO — otherwise it works like OSSL_STORE_open_ex_fn. Same energy, BIO-flavoured. 🦋
OSSL_STORE_ctrl_fn
This function takes an OSSL_STORE_LOADER_CTX pointer, a command number cmd and a va_list args, and it's used to manipulate loader-specific parameters. Remote control for your loader. 🎛️
Loader-specific command numbers must begin at OSSL_STORE_C_CUSTOM_START. Any number below that is reserved for future globally known command numbers — so do not go messing around down there, that's not your territory.
This function is expected to return 1 on success, 0 on error.
OSSL_STORE_expect_fn
This function takes an OSSL_STORE_LOADER_CTX pointer and an OSSL_STORE_INFO identity expected, and it's used to tell the loader what object type is expected. expected may be zero, which signifies that no specific object type is expected at all — "surprise me" energy. 🌈
This function is expected to return 1 on success, 0 on error.
OSSL_STORE_find_fn
This function takes an OSSL_STORE_LOADER_CTX pointer and an OSSL_STORE_SEARCH search criterion, and it's used to tell the loader what to search for. Scavenger hunt time 🔍
- When it's called with the loader context being
NULL, this function is expected to return1if the loader supports the criterion, otherwise0. - When it's called with the loader context being something other than
NULL, this function is expected to return1on success,0on error.
OSSL_STORE_load_fn
This function takes an 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 an OSSL_STORE_INFO using one of the OSSL_STORE_INFO(3) functions. If there's no more data available or an error happens, this function is expected to return NULL.
Then OSSL_STORE_eof_fn and OSSL_STORE_error_fn have to tell you which one it actually was — end of data, or an actual error. Because NULL alone is not telling you anything and honestly, communication is key. 💅
📌 Note that this function retrieves one data item only. One. Just one. Don't get greedy.
OSSL_STORE_eof_fn
This function takes an OSSL_STORE_LOADER_CTX pointer and is expected to return 1 to indicate that the end of available data has been reached. Otherwise it's expected to return 0.
OSSL_STORE_error_fn
This function takes an 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. Otherwise it's expected to return 0.
OSSL_STORE_close_fn
This function takes an OSSL_STORE_LOADER_CTX pointer and is expected to close or shut down whatever needs closing, and finally free the contents of the OSSL_STORE_LOADER_CTX pointer. Cleanup era 🧹 It returns 1 on success and 0 on error.
OSSL_STORE_LOADER_new() creates a brand new OSSL_STORE_LOADER. It takes a string scheme. scheme must always be set. e must be NULL. And heads up — scheme is used as-is, so it must stay alive for as long as the created loader exists. No dangling, bestie 🫶
OSSL_STORE_LOADER_get0_scheme() returns the scheme of the <italic>store_loader*.
OSSL_STORE_LOADER_set_open() sets the opener function for the <italic>store_loader*.
OSSL_STORE_LOADER_set_open_ex() sets the opener-with-library-context function for the <italic>store_loader*.
OSSL_STORE_LOADER_set_attach() sets the attacher function for the <italic>store_loader*.
OSSL_STORE_LOADER_set_ctrl() sets the control function for the <italic>store_loader*.
OSSL_STORE_LOADER_set_expect() sets the expect function for the <italic>store_loader*.
OSSL_STORE_LOADER_set_load() sets the loader function for the <italic>store_loader*.
OSSL_STORE_LOADER_set_eof() sets the end-of-file checker function for the <italic>store_loader*.
OSSL_STORE_LOADER_set_close() sets the closing function for the <italic>store_loader*.
OSSL_STORE_LOADER_free() frees the given <italic>store_loader*. If the argument is NULL, nothing is done. We love a no-op. ✨
OSSL_STORE_register_loader() registers 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 officially on the roster 👑
OSSL_STORE_unregister_loader() unregisters the store loader for the given scheme. Off the roster. 💔
💫 RETURN VALUES 💫
OSSL_STORE_LOADER_fetch() returns a pointer to an OSSL_STORE_LOADER object, or NULL on error.
OSSL_STORE_LOADER_up_ref() returns 1 on success, or 0 on error.
OSSL_STORE_LOADER_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.
OSSL_STORE_LOADER_free() doesn't return any value. It just does its thing and leaves. 💅
OSSL_STORE_LOADER_get0_provider() returns a pointer to a provider object, or NULL on error.
OSSL_STORE_LOADER_get0_properties() returns a pointer to a property definition string, or NULL on error.
OSSL_STORE_LOADER_is_a() returns 1 if loader was identifiable, otherwise 0.
OSSL_STORE_LOADER_get0_description() returns a pointer to a description, or NULL if there isn't one. Some loaders are mysterious like that. 🙈
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, matching energy 💖
OSSL_STORE_LOADER_new() returns a pointer to an OSSL_STORE_LOADER on success, or NULL on 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() and OSSL_STORE_LOADER_set_close() return 1 on success, or 0 on failure.
OSSL_STORE_register_loader() returns 1 on success, or 0 on failure.
OSSL_STORE_unregister_loader() returns the unregistered loader on success, or NULL on failure.
🦋 SEE ALSO 🦋
ossl_store(7), OSSL_STORE_open(3), OSSL_LIB_CTX(3), provider-storemgmt(7)
📜 HISTORY 📜
Listen, we're doing a whole timeline. History class but make it cute 🎀
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.
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. 😬
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.
OSSL_STORE_LOADER_settable_ctx_params() was added in OpenSSL 3.6.
The OSSL_STORE_LOADER_get0_engine() was removed in OpenSSL 4.0. Gone. Not here anymore. RIP 🪦
©️ COPYRIGHT ©️
Copyright 2016-2025 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 a wrap on the whole page, bestie 🫶 this one came from OpenSSL 4.0.3, dated 2026-09-29, and it lives at OSSL_STORE_LOADER(3SSL). go forth and load your stores, you absolute icon 👑✨
📦 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 : a language model's rewrite of the original, under its terms