PROVIDER-STOREMGMT(7ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

💖 NAME 💖

ok so this is provider-storemgmt (that's PROVIDER-STOREMGMT(7ossl), an OpenSSL manual page bestie 💅) — and it's literally The OSSL_STORE library <-> provider functions. that's the whole vibe. the handshake between OSSL_STORE and your provider. no cap.

✨ SYNOPSIS ✨

#include <openssl/core_dispatch.h>

/*
 * None of these are actual functions, but are displayed like this for
 * the function signatures for functions that are offered as function
 * pointers in OSSL_DISPATCH arrays.
 */

void *OSSL_FUNC_store_open(void *provctx, const char *uri);
void *OSSL_FUNC_store_attach(void *provctx, OSSL_CORE_BIO *bio);
const OSSL_PARAM *store_settable_ctx_params(void *provctx);
int OSSL_FUNC_store_set_ctx_params(void *loaderctx, const OSSL_PARAM[]);
int OSSL_FUNC_store_load(void *loaderctx,
                         OSSL_CALLBACK *object_cb, void *object_cbarg,
                         OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg);
int OSSL_FUNC_store_eof(void *loaderctx);
int OSSL_FUNC_store_close(void *loaderctx);

int OSSL_FUNC_store_export_object
    (void *loaderctx, const void *objref, size_t objref_sz,
     OSSL_CALLBACK *export_cb, void *export_cbarg);
void *OSSL_FUNC_store_open_ex(void *provctx, const char *uri,
                              const OSSL_PARAM params[],
                              OSSL_PASSPHRASE_CALLBACK *pw_cb,
                              void *pw_cbarg);

int OSSL_FUNC_store_delete(void *provctx, const char *uri,
                   const OSSL_PARAM params[],
                   OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg);

like, none of these are actual functions bestie — they're just shown this way so you can read the function signatures for the function pointers that get handed over inside OSSL_DISPATCH arrays. it's giving ✨cast of characters✨, not actual definitions. 🎀

🌸 DESCRIPTION 🌸

okay so the STORE operation is the provider side of the ossl_store(7) API. that's it, that's the thesis.

its main character job? loading literally every kind of object out of a container that's pointed at by a URI. those objects get handed to the OpenSSL library in the provider-native object abstraction form (peep provider-object(7) for the deets 🦋). then the OpenSSL library takes that abstraction and passes it on to the suitable provided functions. it's a whole relay race, and honestly? iconic.

examples of functions the OpenSSL library can pass the abstraction to include OSSL_FUNC_keymgmt_load() (provider-keymgmt(7)) and OSSL_FUNC_store_export_object() (which exports the object in parameterized form). slay.

all the "functions" we're talking about here travel as function pointers between libcrypto and the provider, inside OSSL_DISPATCH(3) arrays, via OSSL_ALGORITHM(3) arrays, and those arrays get returned by the provider's provider_query_operation() function (see "Provider Functions" in provider-base(7)). yes that's a chain of three things. yes it slaps. 💜

each of these "functions" has a matching function type definition named OSSL_FUNC_{name}_fn, plus a helper function that fetches the function pointer out of an OSSL_DISPATCH(3) element, named OSSL_get_{name}. for example, the "function" OSSL_FUNC_store_attach() has these two besties:

typedef void *(OSSL_FUNC_store_attach_fn)(void *provctx,
                                          OSSL_CORE_BIO * bio);
static ossl_inline OSSL_FUNC_store_attach_fn
    OSSL_FUNC_store_attach(const OSSL_DISPATCH *opf);

OSSL_DISPATCH(3) arrays get indexed by numbers that are provided as macros in openssl-core_dispatch.h(7), like this:

OSSL_FUNC_store_open                 OSSL_FUNC_STORE_OPEN
OSSL_FUNC_store_attach               OSSL_FUNC_STORE_ATTACH
OSSL_FUNC_store_settable_ctx_params  OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS
OSSL_FUNC_store_set_ctx_params       OSSL_FUNC_STORE_SET_CTX_PARAMS
OSSL_FUNC_store_load                 OSSL_FUNC_STORE_LOAD
OSSL_FUNC_store_eof                  OSSL_FUNC_STORE_EOF
OSSL_FUNC_store_close                OSSL_FUNC_STORE_CLOSE
OSSL_FUNC_store_export_object        OSSL_FUNC_STORE_EXPORT_OBJECT
OSSL_FUNC_store_delete               OSSL_FUNC_STORE_DELETE
OSSL_FUNC_store_open_ex              OSSL_FUNC_STORE_OPEN_EX

🎀 Functions 🎀

  • OSSL_FUNC_store_open() — should create a provider side context with data based on the input uri. the implementation is entirely responsible for interpreting the URI. all of it. on you. 👑
  • OSSL_FUNC_store_attach() — should create a provider side context with the core BIO bio attached. this is the alternative to using a URI to find storage, and it's what supports OSSL_STORE_attach(3). two paths, same destination, we love options 💖
  • OSSL_FUNC_store_settable_ctx_params() — should return a constant array of descriptor OSSL_PARAM(3), for the parameters that OSSL_FUNC_store_set_ctx_params() can handle. it's the menu 📋
  • OSSL_FUNC_store_set_ctx_params() — should set additional parameters, like what kind of data to expect, search criteria, and so on. more on those below in "Load Parameters". whether unrecognised parameters are an error or just quietly ignored is at the implementation's discretion — your call bestie. oh and passing NULL for params should return true. 🫶
  • OSSL_FUNC_store_load() — loads the next object from the URI that was opened by OSSL_FUNC_store_open(), creates an object abstraction for it (see provider-object(7)), and then calls object_cb with it, plus object_cbarg. object_cb will then interpret that object abstraction and do what it can to wrap it or decode it into an OpenSSL structure. and if a passphrase needs to be prompted to unlock an object? pw_cb should be called. 🔑
  • OSSL_FUNC_store_eof() — tells you whether the end of the set of objects from the URI has been reached. when it has, there's literally no point trying to do any further loading. like bestie, we're done, go home 🏠
  • OSSL_FUNC_store_close() — frees the provider side context ctx. bye 👋

when a provider-native object is created by a store manager, it would be unsuitable for direct use with a foreign provider. the export function is what lets you export the object to that foreign provider — if the foreign provider supports the type of the object and provides an import function. it's giving visa requirements ngl 💀

  • OSSL_FUNC_store_export_object() — should export the object of size objref_sz referenced by objref as an OSSL_PARAM(3) array, and pass that to the export_cb as well as the given export_cbarg. ✨
  • OSSL_FUNC_store_delete() — deletes the object identified by the uri. the implementation is entirely responsible for interpreting the URI. and in case a passphrase needs to be prompted to remove an object, pw_cb should be called. yes, deletion needs a password too sometimes, that's just how it is 🔥
  • OSSL_FUNC_store_open_ex() — an extended variant of OSSL_FUNC_store_open(). if the provider doesn't implement this function, the code internally falls back to using the original OSSL_FUNC_store_open(). this variant additionally accepts an OSSL_PARAM(3) object and a pw_cb callback that can be used to request a passphrase in cases where the whole store needs to be unlocked before performing any load operation. unlock the whole thing first, then load. main character energy 👑

🦋 Load Parameters 🦋

  • "expect" (OSSL_STORE_PARAM_EXPECT) <integer> — a hint of what type of data the OpenSSL library expects to get. this is only useful for optimization, because the library will check that the object types match the expectation too (so don't think you can lie, bestie 🙈). the number you can give through this parameter is found in <openssl/store.h>, with the macros having names starting with "OSSL_STORE_INFO_". these are described further in "SUPPORTED OBJECTS" in OSSL_STORE_INFO(3).
  • "subject" (OSSL_STORE_PARAM_SUBJECT) <octet string> — says the caller wants to search for an object with the given subject associated. this can be used to select specific certificates by subject. the contents of the octet string is expected to be in DER form. 🍓
  • "issuer" (OSSL_STORE_PARAM_ISSUER) <octet string> — says the caller wants to search for an object with the given issuer associated. this can be used to select specific certificates by issuer. the contents of the octet string is expected to be in DER form.
  • "serial" (OSSL_STORE_PARAM_SERIAL) <integer> — says the caller wants to search for an object with the given serial number associated. 🔢
  • "digest" (OSSL_STORE_PARAM_DIGEST) <UTF8 string>
  • "fingerprint" (OSSL_STORE_PARAM_FINGERPRINT) <octet string> — says the caller wants to search for an object with the given fingerprint, computed with the given digest. these two go together like me and my iced coffee 🧊
  • "alias" (OSSL_STORE_PARAM_ALIAS) <UTF8 string> — says the caller wants to search for an object with the given alias (some people call it a "friendly name" 💖).
  • "properties" (OSSL_STORE_PARAM_PROPERTIES) <utf8 string> — the property string to use when querying for algorithms such as the OSSL_DECODER decoder implementations.
  • "input-type" (OSSL_STORE_PARAM_INPUT_TYPE) <utf8 string> — the type of the input format, as a hint to use when decoding the objects in the store.

several of these search criteria may be combined. for example, to search for a certificate by issuer+serial, both the "issuer" and the "serial" parameters will be given. stacking them like accessories, we love to see it 🌈

⭐ SEE ALSO ⭐

provider(7)

👑 HISTORY 👑

the STORE interface was introduced in OpenSSL 3.0.

the OSSL_FUNC_store_delete() callback was added in OpenSSL 3.2.

Copyright 2020-2023 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>.

fr fr read the license before you go wild with it, bestie 🫶

okay that's the whole page, and here's your cute little sign-off: this was version 3.5.6, dated 2026-04-07, page PROVIDER-STOREMGMT(7ossl) 💅✨ go forth and load objects, you absolute icon 🎀🦋

📦 where this page comes from