OSSL_STORE_OPEN(3SSL)

📦

version 4.0.3 · 13 versions

🌸 OSSL_STORE_OPEN 💖

okay bestie, this is the OpenSSL manual page for OSSL_STORE_OPEN(3SSL) — the one about the types and functions you use to read objects from a URI. yes it's a lot of functions. no you're not going to memorize them in one sitting. we got this 💅

✨ NAME ✨

Here's the whole cast, in one big glow-up list:

OSSL_STORE_CTX
OSSL_STORE_post_process_info_fn
OSSL_STORE_open
OSSL_STORE_open_ex
OSSL_STORE_ctrl
OSSL_STORE_load
OSSL_STORE_eof
OSSL_STORE_delete
OSSL_STORE_error
OSSL_STORE_close

and collectively they're the types and functions to read objects from a URI. that's the whole vibe 🦋

🌈 SYNOPSIS 🌈

first, the include, obviously:

#include <openssl/store.h>

the context type, our main character:

typedef struct ossl_store_ctx_st OSSL_STORE_CTX;

the callback typedef — this is the one that gets to yeet values back:

typedef OSSL_STORE_INFO *(*OSSL_STORE_post_process_info_fn)(OSSL_STORE_INFO *,
                                                            void *);

and now the functions themselves, verbatim so you can copy-paste with zero fear:

OSSL_STORE_CTX *OSSL_STORE_open(const char *uri, const UI_METHOD *ui_method,
                                void *ui_data,
                                OSSL_STORE_post_process_info_fn post_process,
                                void *post_process_data);

OSSL_STORE_CTX *
OSSL_STORE_open_ex(const char *uri, OSSL_LIB_CTX *libctx, const char *propq,
                   const UI_METHOD *ui_method, void *ui_data,
                   const OSSL_PARAM params[],
                   OSSL_STORE_post_process_info_fn post_process,
                   void *post_process_data);

OSSL_STORE_INFO *OSSL_STORE_load(OSSL_STORE_CTX *ctx);
int OSSL_STORE_eof(OSSL_STORE_CTX *ctx);
int OSSL_STORE_delete(const char *uri, OSSL_LIB_CTX *libctx, const char *propq,
                      const UI_METHOD *ui_method, void *ui_data,
                      const OSSL_PARAM params[]);
int OSSL_STORE_error(OSSL_STORE_CTX *ctx);
int OSSL_STORE_close(OSSL_STORE_CTX *ctx);

🚨 deprecated alert 🚨 the function below has been deprecated since OpenSSL 3.0, and you can hide it entirely by defining OPENSSL_API_COMPAT with a suitable version value. check openssl_user_macros(7) for the deets.

int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */);

💖 DESCRIPTION 💖

so basically: these functions help your application fetch supported objects — and if you want the tea on which objects count as supported, go look at "SUPPORTED OBJECTS" in OSSL_STORE_INFO(3) — from a given URI.

the general method, step by step, is giving very much a routine:

"open" the URI using OSSL_STORE_open()
read each available and supported object using OSSL_STORE_load(), and keep going as long as OSSL_STORE_eof() hasn't been reached
finish it off with OSSL_STORE_close()

the retrieved information gets stored in an OSSL_STORE_INFO, which is described in more detail in OSSL_STORE_INFO(3). ✨

🎀 Types

OSSL_STORE_CTX is a context variable 📦 — it holds all the internal information so that OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close() can work together. it's the group chat all of them share, essentially.

🦋 Functions

OSSL_STORE_open_ex() takes a uri or path uri, a password UI method ui_method with associated data ui_data, and a post processing callback post_process with associated data post_process_data, plus a library context libctx with an associated property query propq. it opens a channel to the data located at the URI and returns an OSSL_STORE_CTX with all the necessary internal information. the ui_method and ui_data you gave get reused by every function that uses OSSL_STORE_CTX when interaction is needed — like when something needs a password 🔐. the auxiliary OSSL_PARAM(3) parameters in params can be set to further modify the store operation. and the post_process and post_process_data you gave get reused by OSSL_STORE_load() to manipulate or drop the value that's about to be returned. the post_process function drops values by returning NULL, which makes OSSL_STORE_load() start its whole process over again and load the next object — and it keeps doing that until post_process returns something that is not NULL, or the end of data is reached, as indicated by OSSL_STORE_eof().

OSSL_STORE_open() is similar to OSSL_STORE_open_ex() but uses NULL for the params, the library context libctx and property query propq. lowkey the simpler sibling 💜

OSSL_STORE_ctrl() takes an OSSL_STORE_CTX, and a command number cmd, plus more arguments that are not specified here. the available loader specific command numbers, and the arguments each one takes, depend on the loader that's being used — and they're documented together with that loader. so, y'know, read that loader's page, not this one.

there are also global controls available:

OSSL_STORE_C_USE_SECMEM — controls whether the loader should attempt to use secure memory for any allocated OSSL_STORE_INFO and its contents. this control expects one argument: a pointer to an int that is expected to have the value 1 (yes) or 0 (no). any other value is an error. 🫠

OSSL_STORE_load() takes an OSSL_STORE_CTX and tries to load the next available object, returning it wrapped with OSSL_STORE_INFO.

OSSL_STORE_delete() deletes the object identified by uri. bye bye 👋

OSSL_STORE_eof() takes an OSSL_STORE_CTX and checks if we've reached the end of data.

OSSL_STORE_error() takes an OSSL_STORE_CTX and checks if an error occurred in the last OSSL_STORE_load() call. heads up though: it may still be meaningful to try and load more objects, unless OSSL_STORE_eof() shows that the end of data has been reached. iykyk 😭

OSSL_STORE_close() takes an OSSL_STORE_CTX, closes the channel that was opened by OSSL_STORE_open(), and frees all the other information that was stored in the OSSL_STORE_CTX — as well as the OSSL_STORE_CTX itself. if ctx is NULL it does nothing. iconic, no notes. 💅

💀 NOTES 💀

a string without a scheme prefix — that is, a non-URI string — is implicitly interpreted as using the file: scheme. surprise, bestie, it was a file the whole time 🍓

there are some tools you can use together with OSSL_STORE_open() to figure out whether a failure was caused by an unparsable URI, or whether it's a different error (like memory allocation failures). and here's the trick: if the URI was parsable but the scheme is unregistered, the top error will have the reason "OSSL_STORE_R_UNREGISTERED_SCHEME". write that down 📝

these functions make no direct assumption regarding the pass phrase received from the password callback. the loaders may make assumptions, though. for example, the file: scheme loader inherits the assumptions made by OpenSSL functionality that handles the different file types — this is mostly relevant for PKCS#12 objects. see passphrase-encoding(7) for further information.

👑 RETURN VALUES 👑

OSSL_STORE_open() returns a pointer to an OSSL_STORE_CTX on success, or NULL on failure.
OSSL_STORE_load() returns a pointer to an OSSL_STORE_INFO on success, or NULL on error or when the end of data is reached. use OSSL_STORE_error() and OSSL_STORE_eof() to determine the meaning of a returned NULL — don't just guess, bestie.
OSSL_STORE_eof() returns 1 if the end of data has been reached or an error occurred, 0 otherwise.
OSSL_STORE_error() returns 1 if an error occurred in an OSSL_STORE_load() call, otherwise 0.
OSSL_STORE_delete(), OSSL_STORE_ctrl() and OSSL_STORE_close() return 1 on success, or 0 on failure.

🌟 SEE ALSO 🌟

go read these next, they're the friend group:

🧚 HISTORY 🧚

the lore, in order:

OSSL_STORE_delete() was added in OpenSSL 3.2.
OSSL_STORE_open_ex() was added in OpenSSL 3.0.
OSSL_STORE_CTX, OSSL_STORE_post_process_info_fn(), OSSL_STORE_open(), OSSL_STORE_ctrl(), OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close() were added in OpenSSL 1.1.1.
Handling of the NULL ctx argument for OSSL_STORE_close() was introduced in OpenSSL 1.1.1h.
OSSL_STORE_ctrl() and OSSL_STORE_vctrl() were deprecated in OpenSSL 3.0.

📜 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 of the License in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the whole page, bestie 🫶 this was version 4.0.3, dated 2026-09-29 — go forth and OSSL_STORE_open() responsibly, 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