OSSL_LIB_CTX(3ossl)

💖 OSSL_LIB_CTX — the OpenSSL library context, bestie edition 💖

okay so this is OSSL_LIB_CTX(3ossl) from the OpenSSL manuals, and we're gonna get you fluent in library contexts, no cap. Also living here: 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. ✨

---

🌸 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 allocate their own, but they can also just pass NULL and get a default context, as long as the function in question takes an OSSL_LIB_CTX argument. easy. 💅

⚠️ real talk: when a non-default library context is in use, you gotta be careful with multi-threaded apps and properly clean up thread-local resources before the OSSL_LIB_CTX gets freed. OPENSSL_thread_stop_ex(3) has the deets. don't skip this one bestie.

Here's the function-by-function rundown, mwah:

• OSSL_LIB_CTX_new() — makes you a brand new OpenSSL library context. iconic behavior.
• OSSL_LIB_CTX_new_from_dispatch() — creates a new OpenSSL library context that's initialised to use callbacks from the OSSL_DISPATCH structure. mainly for provider authors ngl. the handle and dispatch structure args you pass should be the same ones passed to a provider's OSSL_provider_init function. some OpenSSL functions — like BIO_new_from_core_bio(3) — require the library context to be created this way or they simply won't work. it's giving "no vibes, only structure" 💀
• 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 additionally links the new library context to the application library context. the new one is a full library context in its own right, but it'll have all the same providers available that exist in the application library context (no reloading needed, slay). 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. those independently-loaded providers will not be mirrored back into the parent, and they won't be affected if the parent later loads the same provider.

A provider may call OSSL_PROVIDER_load(3) with the child library context whenever it needs to. if the provider already exists because it got mirrored from the parent, it stays available and its reference count goes up. if you call OSSL_PROVIDER_load(3) like that, you should subsequently call OSSL_PROVIDER_unload(3) to decrement the reference count.

🚨 and 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. periodt.

And it's not just providers, bestie — 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 and the mirroring of properties stops. it's giving independence. 👑

One more thing: when OSSL_LIB_CTX_new_child() is called from within the scope of a provider's OSSL_provider_init function, the currently-initialising provider isn't yet available in the application's library context, so it likewise won't yet be available in the newly constructed child library context. the moment that OSSL_provider_init function returns, the new provider becomes available in the application's library context and gets mirrored in the child library context too. timing is everything 💫

• OSSL_LIB_CTX_load_config() — loads a configuration file using the given ctx. this is how you 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. no parallel chaos please.

• OSSL_LIB_CTX_free() — frees the given ctx, unless it happens to be the default OpenSSL library context (can't touch that one). if the argument is NULL, nothing happens. chill. 😌
• OSSL_LIB_CTX_get0_global_default() — returns a concrete (non-NULL) reference to the global default library context. solid. reliable. main character energy.
• OSSL_LIB_CTX_set0_default() — sets the default OpenSSL library context to be ctx in the current thread, and returns the previous default library context. caller better take care to restore that previous default with a subsequent call to this function, fr fr. if ctx is NULL then no change is made to the default library context, but a pointer to the current library context still gets returned. on a successful call of this function, the returned value will always be a concrete (non-NULL) library context. 💖

🌈 caution when changing the default library context and starting async jobs (peep ASYNC_start_job(3)): the default library context at the time the job is started gets used throughout the lifetime of that async job, no matter how the calling thread keeps changing defaults 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 finishes. do not do it. 🙈

• OSSL_LIB_CTX_get_data() — returns a memory address whose interpretation depends on the index. the index argument refers to a context member that's 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, 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. (yes we said it twice, it's that important 💅)

---

💜 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 a void. it just does its thing and leaves. ghosting, but productively. 🎀
• 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. (again. forever. it's a whole bit.)

---

⭐ HISTORY ⭐

Every single function on this page was added in OpenSSL 3.0.

OSSL_LIB_CTX_get_data() was introduced in OpenSSL 3.4. a little late to the party but she arrived. 🦋

---

👑 COPYRIGHT 👑

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 3.5.9, dated 2026-09-29, from the OSSL_LIB_CTX(3ossl) manual — go forth and manage your library contexts responsibly, ily 💖✨