OSSL_LIB_CTX(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💖 OSSL_LIB_CTX 💖 — the OpenSSL library context (3ossl, bestie)

okay so this is the 3ossl manual page for the OpenSSL library context and honestly it's a whole vibe. it covers OSSL_LIB_CTX, OSSL_LIB_CTX_get_data, OSSL_LIB_CTX_new, OSSL_LIB_CTX_new_from_dispatch, OSSL_LIB_CTX_new_child, OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config, OSSL_LIB_CTX_get0_global_default, and OSSL_LIB_CTX_set0_default. all of them. every single one. let's go 🫶

✨ SYNOPSIS ✨

#include <openssl/crypto.h>

typedef struct ossl_lib_ctx_st OSSL_LIB_CTX;

OSSL_LIB_CTX *OSSL_LIB_CTX_new(void);
OSSL_LIB_CTX *OSSL_LIB_CTX_new_from_dispatch(const OSSL_CORE_HANDLE *handle,
                                             const OSSL_DISPATCH *in);
OSSL_LIB_CTX *OSSL_LIB_CTX_new_child(const OSSL_CORE_HANDLE *handle,
                                     const OSSL_DISPATCH *in);
int OSSL_LIB_CTX_load_config(OSSL_LIB_CTX *ctx, const char *config_file);
void OSSL_LIB_CTX_free(OSSL_LIB_CTX *ctx);
OSSL_LIB_CTX *OSSL_LIB_CTX_get0_global_default(void);
OSSL_LIB_CTX *OSSL_LIB_CTX_set0_default(OSSL_LIB_CTX *ctx);
void *OSSL_LIB_CTX_get_data(OSSL_LIB_CTX *ctx, int index);

🌸 DESCRIPTION 🌸

okay so OSSL_LIB_CTX is an internal OpenSSL library context type. apps can allocate their own, but they can also just pass NULL to use a default context whenever a function takes an OSSL_LIB_CTX argument. lowkey convenient 💅

when a non default library context is in use, pls be careful with multi-threaded apps — you gotta properly clean up thread local resources before the OSSL_LIB_CTX is freed. like, actually. check out OPENSSL_thread_stop_ex(3) for the deets. don't skip this one bestie 😭

OSSL_LIB_CTX_new() creates a brand new OpenSSL library context. slay ✨

OSSL_LIB_CTX_new_from_dispatch() creates a new OpenSSL library context initialised to use callbacks from the OSSL_DISPATCH structure. this one's primarily useful for provider authors. the handle and dispatch structure arguments you pass should be the same ones as those passed to a provider's OSSL_provider_init function. some OpenSSL functions — like BIO_new_from_core_bio(3) — literally require the library context to be created this way in order to work. no cap, it's a whole requirement.

OSSL_LIB_CTX_new_child() is only useful to provider authors, and it does the same thing as OSSL_LIB_CTX_new_from_dispatch() except that it additionally links the new library context to the application library context. the new library context is a full library context in its own right, but it'll have all the same providers available to it that are available in the application library context (without having to reload them, iconic). if the application loads or unloads providers from the application library context, that gets automatically mirrored in the child library context. 👑

also, providers that are not loaded in the parent library context can be explicitly loaded into the child library context independently from the parent library context. providers loaded independently this way will not be mirrored in the parent library context, and they won't be affected if the parent library context subsequently loads the same provider. separate vibes, separate contexts, we respect it.

a provider may call OSSL_PROVIDER_load(3) with the child library context as required. if the provider already exists because it's being mirrored from the parent library context, then it will remain available and its reference count will be increased. if OSSL_PROVIDER_load(3) is called in this way, then OSSL_PROVIDER_unload(3) should be subsequently called to decrement the reference count.

🚨 but listen: OSSL_PROVIDER_unload(3) must not be called for a provider in the child library context that did not have an earlier OSSL_PROVIDER_load(3) call for that provider in that child library context. that's the rule. fr fr.

in addition to providers, a child library context will also mirror the default properties (set via EVP_set_default_properties(3)) from the parent library context. if EVP_set_default_properties(3) is called directly on a child library context, then the new properties will override anything from the parent library context, and mirroring of the properties will stop. it's giving ✨independence✨

when OSSL_LIB_CTX_new_child() is called from within the scope of a provider's OSSL_provider_init function, the currently initialising provider is not yet available in the application's library context — and therefore will similarly not yet be available in the newly constructed child library context. but as soon as the OSSL_provider_init function returns, then the new provider is available in the application's library context and will be similarly mirrored in the child library context. timing is everything 🕰️

OSSL_LIB_CTX_load_config() loads a configuration file using the given ctx. this can be used to associate a library context with providers that are loaded from a configuration. and important: this function must not be called concurrently from multiple threads on a single ctx. one thread at a time, bestie, we're not doing chaos today 🙈

OSSL_LIB_CTX_free() frees the given ctx — unless it happens to be the default OpenSSL library context. in that case, nope, not today. and if the argument is NULL, nothing is done. literally nothing. peaceful.

OSSL_LIB_CTX_get0_global_default() returns a concrete (non NULL) reference to the global default library context. a real one. an actual pointer. 🎀

OSSL_LIB_CTX_set0_default() sets the default OpenSSL library context to be ctx in the current thread. the previous default library context is returned. the caller should take care to restore the previous default library context with a subsequent call of this function. if ctx is NULL, then no change is made to the default library context, but a pointer to the current library context is still returned. on a successful call of this function, the returned value will always be a concrete (non NULL) library context. always. every time. 💯

⚠️ big caution energy: be careful when changing the default library context and starting async jobs (see ASYNC_start_job(3)), because the default library context when the job is started will be used throughout the lifetime of an async job — no matter how the calling thread makes further default library context changes in the mean time. this means the calling thread must not free the library context that was the default at the start of the async job before that job has finished. like, that's a use-after-free waiting to happen and we do NOT want it 😭💀

OSSL_LIB_CTX_get_data() returns a memory address whose interpretation depends on the index. the index argument refers to a context member which is to be retrieved. the values for index are all private to OpenSSL currently, and so applications should not typically call this function. if ctx is NULL, then the function operates on the default library context. and, one more time for the people in the back: OSSL_LIB_CTX_get_data() returns a memory address whose interpretation depends on the index. 🦋

🌈 RETURN VALUES 🌈

  • OSSL_LIB_CTX_new(), OSSL_LIB_CTX_get0_global_default() and OSSL_LIB_CTX_set0_default() return a library context pointer on success, or NULL on error. classic.
  • OSSL_LIB_CTX_free() doesn't return any value. it's void. it's free. it's unbothered.
  • OSSL_LIB_CTX_load_config() returns 1 on success, 0 on error. binary queen.
  • OSSL_LIB_CTX_get_data() returns a memory address whose interpretation depends on the index. (yes, again. it's consistent like that 💅)

🎀 HISTORY 🎀

all of the functions described on this page were added in OpenSSL 3.0.

OSSL_LIB_CTX_get_data() was introduced in OpenSSL 3.4. late to the party but we love her 🌸

Copyright 2019-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 🫶 this was version 3.5.0, dated 2026-09-25, filed under OSSL_LIB_CTX(3ossl) — go forth and context-ify responsibly 💖✨🧚

📦 where this page comes from