OSSL_STORE_LOADER(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 OSSL_STORE_LOADER — the whole entire vibe ✨

okay so bestie, this is the OSSL_STORE_LOADER(3ossl) page from OpenSSL, and it's literally the main character energy for STORE loaders. no cap. 🎀

🌸 NAME 🌸

OSSL_STORE_LOADER, OSSL_STORE_LOADER_fetch, OSSL_STORE_LOADER_up_ref, OSSL_STORE_LOADER_free, OSSL_STORE_LOADER_get0_provider, OSSL_STORE_LOADER_get0_properties, OSSL_STORE_LOADER_is_a, OSSL_STORE_LOADER_get0_description, OSSL_STORE_LOADER_do_all_provided, OSSL_STORE_LOADER_names_do_all, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new, OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme, OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_open_ex, OSSL_STORE_LOADER_set_attach, OSSL_STORE_LOADER_set_ctrl, OSSL_STORE_LOADER_set_expect, OSSL_STORE_LOADER_set_find, OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof, OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close, OSSL_STORE_register_loader, OSSL_STORE_unregister_loader, OSSL_STORE_open_fn, OSSL_STORE_open_ex_fn, OSSL_STORE_attach_fn, OSSL_STORE_ctrl_fn, OSSL_STORE_expect_fn, OSSL_STORE_find_fn, OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn, OSSL_STORE_close_fn — literally all the types and functions you need to manipulate, register, and unregister STORE loaders for all the different URI schemes. iykyk 💖

✨ SYNOPSIS ✨

here's the whole lineup, bestie. copy-paste energy:

#include <openssl/store.h>

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);

okay but like — heads up, the following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value. see openssl_user_macros(7) for the deets. lowkey sad but we move 💀

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);

🦋 DESCRIPTION 🦋

okay so boom — these functions let you see and work with STORE loaders, which are the little legends that actually implement the STORE API so it can work with URIs of different schemes. it's giving behind-the-scenes crew that makes everything slay. we got the boring chapters (examining and maneuvring) and the main character part (creating and manipulating your own loader). periodt. 💅

the exported fetchers and loaders, bestie

OSSL_STORE_LOADER_fetch() fetches a STORE loader implementation from any provider that's been loaded into the OSSL_LIB_CTX that libctx points at, using a URI scheme as its name, and with the property query properties. like grabbing the right one for the job. ✨

`OSSL_STORE_LOADER_up_ref()` increments the reference count for a loader,
`OSSL_STORE_LOADER_free()` decrements it — and when it hits zero, the loader is done-zo.

OSSL_STORE_LOADER_get0_provider() returns the provider that this loader was fetched from. no cap, that's where it came from. 🎀

OSSL_STORE_LOADER_get0_properties() returns the property definition associated with the loader. it's giving receipts.

OSSL_STORE_LOADER_is_a() checks if the loader's implementation name matches scheme — basically "are you who you say you are?" vibe check. 👑

OSSL_STORE_LOADER_get0_description() returns a human readable description of the loader, or NULL if there isn't one. nice-to-have, not must-have. 🫶

OSSL_STORE_LOADER_do_all_provided() iterates over all loaders implemented by any activated provider, calling user_fn for each one, with the loader as the first argument and user_arg as the second. literal tour of the whole roster. 🌈

OSSL_STORE_LOADER_names_do_all() iterates over all names that the loader has been given or can be fetched under, calling fn for each, with the name and data as args. slay names, slay vibes. ⭐

the maneuvring functions (deprecated era, lowkey)

OSSL_STORE_LOADER_new() creates a new OSSL_STORE_LOADER, with the given ENGINE e and the given scheme name. the ENGINE is only used for the loader name. OSSL_STORE_LOADER_get0_engine() gets that engine. OSSL_STORE_LOADER_get0_scheme() gets the scheme name. all deprecated, all still documented for the culture. 💀

how each function gets set (the deprecation era continues)

  • OSSL_STORE_LOADER_set_open() sets the function the loader can use to start a new operation stream (open).
  • OSSL_STORE_LOADER_set_open_ex() does the same, but it's literally the same prototype as OSSL_STORE_open_fn, so ngl bestie, kinda sus it exists at all. but there it is.
  • OSSL_STORE_LOADER_set_attach() sets the function that attaches the loader to a BIO. once set, you can't set it again. one and done. 🙈
  • OSSL_STORE_LOADER_set_ctrl() sets the function that can accept commands (control interface).
  • OSSL_STORE_LOADER_set_expect() sets the function that can say "okay, I only care about this kind of stuff" (expect).
  • OSSL_STORE_LOADER_set_find() sets the function that can find specific objects (OSSL_STORE_SEARCH).
  • OSSL_STORE_LOADER_set_load() sets the function that actually loads your data.
  • OSSL_STORE_LOADER_set_eof() sets the function that tells you when you've hit the end.
  • OSSL_STORE_LOADER_set_error() sets the function that checks for an outstanding error on the context.
  • OSSL_STORE_LOADER_set_close() sets the function that closes the loader's context.
yeah bestie, it's a lot of setters, but they all matter — and you can only set each one once. don't try to double up. 💅

the context types and callbacks, because besties need types

OSSL_STORE_LOADER_CTX is a type that's defined per loader — the docs literally say "struct ossl_store_loader_ctx_st is defined differently by each loader." so it's giving customizable, main character, yours-to-shape energy. 🧚

OSSL_STORE_open_fn and OSSL_STORE_open_ex_fn take a URI, a UI_METHOD pointer, and a void pointer to UI data, and return an OSSL_STORE_LOADER_CTX *. basically "start me up." 🎀

OSSL_STORE_attach_fn takes the loader itself, a BIO *, a OSSL_LIB_CTX *, a propq, a UI_METHOD, and UI data — and returns the context. attach energy.

OSSL_STORE_ctrl_fn takes a context, an int cmd, and a va_list args — returns int. this is where commands get handled.

OSSL_STORE_expect_fn takes a context and the int expected — returns int. expectation setting, very boundary queen.

OSSL_STORE_find_fn takes a context and an OSSL_STORE_SEARCH *criteria — returns int. finding exactly what you came for. 🔥

OSSL_STORE_load_fn takes a context, a UI_METHOD *, and UI data — returns an OSSL_STORE_INFO *. the actual loading, iconic.

OSSL_STORE_eof_fn is a context in, int out — checks if you're at the end. no cap.

OSSL_STORE_error_fn is a context in, int out — checks for an error. because sometimes things go 💀.

OSSL_STORE_close_fn is a context in, int out — closes the context. clean exit, bestie. 🌸

register and unregister (the deprecated glue)

OSSL_STORE_register_loader() registers the given loader — stored for future reference. and OSSL_STORE_unregister_loader() takes a scheme name and unregisters (and pops off) the loader associated with it. bay goodbye to that scheme! 🌈

okay bestie, that's part one — go forth and maneuvre some storage. more coming! 🎀✨

💾 DESCRIPTION 💾

okay so OSSL_STORE_LOADER is the method for OSSL_STORE loaders — the little implementation crew that makes OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_load(), OSSL_STORE_eof(), OSSL_STORE_error() and OSSL_STORE_close() work for specific storage schemes. 💅

Meet the provider-side functions:

  • OSSL_STORE_LOADER_fetch() — looks for an implementation for a storage scheme within the providers that has been loaded into the OSSL_LIB_CTX given by libctx, and with the properties given by properties. ✨
  • OSSL_STORE_LOADER_up_ref() — increments the reference count for the given loader. 🫶
  • OSSL_STORE_LOADER_free() — decrements the reference count for the given loader, and when the count reaches zero, frees it. If the argument is NULL, nothing is done. 💀
  • OSSL_STORE_LOADER_get0_provider() — returns the provider of the given loader. 👑
  • 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. 🔥
  • OSSL_STORE_LOADER_get0_description() — returns a description of the loader, meant for display and human consumption. The description is at the discretion of the loader implementation. 🌸
  • 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. 🦋
  • 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) 🧸

These functions help applications and engines to create loaders for schemes they support. These are all deprecated and discouraged in favour of provider implementations, see provider-storemgmt(7). periodt — the provider route is the main character here. 👑

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

🪄 The legacy function-pointer squad

  • 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, 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. 🫶

  • OSSL_STORE_attach_fn — this function takes a BIO, otherwise works like OSSL_STORE_open_ex_fn. 🎀
  • 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.

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

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

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

Note that this function retrieves one data item only. ☝️

  • 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. 🏁
  • 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. 💀
  • 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. 🫶

🛠️ Legacy loader-building bits

  • 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. 🔥
  • 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. 💀
  • 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(). 🌟
  • OSSL_STORE_unregister_loader() — unregister the store loader for the given scheme. 🙈

🔁 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. 💀
  • 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. 🌸

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

  • OSSL_STORE_LOADER_new() — returns a pointer to a 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 👀

🕰️ 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. ✨
  • 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. 😭

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

💅 that’s the whole page, bestie — it’s from OpenSSL 3.5.0, dated 2026-09-25, and yes the page is OSSL_STORE_LOADER(3ossl). stay slay, and may your loaders always up_ref() correctly. 🎀✨

📦 where this page comes from