OSSL_LIB_CTX(3SSL)

📦

version 4.0.3 · 6 versions

💖 OSSL_LIB_CTX 💖

okay bestie, sit down, hydrate, because we're talking about the OpenSSL library context — this is OSSL_LIB_CTX(3SSL) and it's giving main-character infrastructure energy. ✨

Here's the whole girl group, one sec:

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
OSSL_LIB_CTX_set0_default

✨ 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 🌸

So OSSL_LIB_CTX is an internal OpenSSL library context type. Apps can totally allocate their own if they want, but you can also just pass NULL and get the default context — that works for any function that takes an OSSL_LIB_CTX argument. lowkey convenient fr fr 🫶

⚠️ When you're using a non-default library context, pleaaase be careful with multi-threaded apps: clean up your thread local resources properly before the OSSL_LIB_CTX gets freed. Check OPENSSL_thread_stop_ex(3) for the deets. don't skip this one bestie, it's not a vibe.

Now the lineup, one by one 💅

OSSL_LIB_CTX_new() — makes you a brand new OpenSSL library context. fresh out the box, glowing ✨
OSSL_LIB_CTX_new_from_dispatch() — creates a new OpenSSL library context that's initialised to use callbacks from the OSSL_DISPATCH structure. This is mostly for provider authors. The handle and dispatch structure args you pass in should be the same ones that got 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 or they just won't work. periodt.
OSSL_LIB_CTX_new_child() — only useful to provider authors, and it does the same thing as OSSL_LIB_CTX_new_from_dispatch(), except it also 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 will have all the same providers available to it that are available in the application library context — and it does not have to reload them. If the application loads or unloads providers from the application library context, that automatically gets mirrored in the child library context. it's giving inheritance but make it provider-y 🌈

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 in this way will not be mirrored in the parent library context, and they won't be affected if the parent library context later loads the same provider. no take-backs, no drama 💅

A provider may call the function 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 stays available and its reference count gets increased. And if OSSL_PROVIDER_load(3) was called in this way, then OSSL_PROVIDER_unload(3) should be called afterwards to decrement that reference count. Important: 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. like, unmatched unloads are NOT the move 😭

And it's not just providers — a child library context also mirrors the default properties (set via EVP_set_default_properties(3)) from the parent library context. But if EVP_set_default_properties(3) gets called directly on a child library context, then the new properties override anything from the parent library context, and the mirroring of the properties stops. she said "my rules now" 💅

One more lil gotcha: 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 — so it similarly won't be available yet in the newly constructed child library context. As soon as the OSSL_provider_init function returns, the new provider is available in the application's library context and gets mirrored in the child library context too. timing is everything, iykyk 🦋

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

🚨 This function must not be called concurrently from multiple threads on a single ctx. one at a time, bestie. take turns.

OSSL_LIB_CTX_free() — frees the given ctx, unless it happens to be the default OpenSSL library context. If the argument is NULL, nothing is done, we simply move on. ✌️ Any providers loaded into ctx are automatically deactivated and freed as part of the library context cleanup. And heads up: any OSSL_PROVIDER pointers you got from ctx must not be used after this call. they're gone, don't text them 😭
OSSL_LIB_CTX_get0_global_default() — returns a concrete (non-NULL) reference to the global default library context. reliable queen 👑
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 be careful 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. put it back when you're done, it's basic manners 🫶

⚠️ Care should be taken when changing the default library context and starting async jobs (see ASYNC_start_job(3)), because the default library context at the time the job is started will be used throughout the lifetime of that async job — no matter how the calling thread makes further default library context changes in the meantime. Which 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. do not do it. it WILL be a problem. 💀

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, so applications should not typically call this function. If ctx is NULL, then the function operates on the default library context. And yes — OSSL_LIB_CTX_get_data() returns a memory address whose interpretation depends on the index. (said it twice, meant it twice 💜)

⭐ 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. 🙈
OSSL_LIB_CTX_free() — doesn't return any value. (she gives nothing and that's fine)
OSSL_LIB_CTX_load_config() — returns 1 on success, 0 on error.
OSSL_LIB_CTX_get_data() — returns a memory address whose interpretation depends on the index.

🦋 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. she's the baby of the family 🍓

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

and that's the whole page bestie!! 💖✨🎀 you ate. go forth and context responsibly 🫶

signing off from OpenSSL 4.0.3, dated 2026-09-29 — 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