OPENSSL_INIT_CRYPTO(3SSL)

📦

version 3.5.7 · 11 versions

okay so bestie, this is the OPENSSL_INIT_CRYPTO(3SSL) page, and the way that it kicks off with the whole initialisation/deinitialisation roster is lowkey iconic. no cap, every name here is main character energy, so let’s do the roll call without skipping a single one 💅✨

💖 NAME 💖

the whole squad — literally every function in the title — is:

OPENSSL_INIT_new
OPENSSL_INIT_set_config_filename
OPENSSL_INIT_set_config_appname
OPENSSL_INIT_set_config_file_flags
OPENSSL_INIT_free
OPENSSL_init_crypto
OPENSSL_cleanup
OPENSSL_atexit
OPENSSL_thread_stop_ex
OPENSSL_thread_stop

and what are they? the OpenSSL initialisation and deinitialisation functions — periodt. that’s the whole vibe of this NAME section, bestie 🫶

✨ SYNOPSIS ✨

okay, here’s the exact lineup, and yes you’re gonna wanna keep every character:

#include <openssl/crypto.h>

void OPENSSL_cleanup(void);
int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
int OPENSSL_atexit(void (*handler)(void));
void OPENSSL_thread_stop_ex(OSSL_LIB_CTX *ctx);
void OPENSSL_thread_stop(void);

OPENSSL_INIT_SETTINGS *OPENSSL_INIT_new(void);
int OPENSSL_INIT_set_config_filename(OPENSSL_INIT_SETTINGS *init,
                                     const char* filename);
int OPENSSL_INIT_set_config_file_flags(OPENSSL_INIT_SETTINGS *init,
                                       unsigned long flags);
int OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init,
                                    const char* name);
void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init);

that’s the synopsis, bestie, and it’s giving copy me exactly energy 🔥 no renaming, no merging, no invented anything — we don’t do that here 🙈

✨ DESCRIPTION ✨

okay so bestie, here's the tea 🫖 — when OpenSSL (that's libcrypto) is just doing its normal thing, it grabs a bunch of resources at start up, and those have to get freed when the library closes down. and like, also, some of those resources are per-thread (if your app is multi-threaded, which, respect), and those little guys gotta be freed before the thread closes. no cap. 💅

as of version 1.1.0 OpenSSL just... handles it? it automatically allocates all the resources it needs, so no explicit initialisation is required. and yeah, it deinitialises automatically too. she's self-sufficient, she's got main character energy. 👑

but — there are situations where explicit initialisation is desirable or needed, for example when you need some nondefault initialisation. and that's literally what the OPENSSL_init_crypto() function is for, for libcrypto (also peep OPENSSL_init_ssl(3) for the libssl equivalent, iykyk).

here's the important bit 🔥 — numerous internal OpenSSL functions call OPENSSL_init_crypto(). so if you want nondefault initialisation, OPENSSL_init_crypto() MUST be called by application code prior to any other OpenSSL function calls. like, before anything else. first in line. periodt.

the opts parameter specifies which aspects of libcrypto should be initialised. valid options are:

🎀 the options, in all their glory 🎀

OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS — suppresses the automatic loading of the libcrypto error strings. this one is not a default option. and once you select it, subsequent calls to OPENSSL_init_crypto() with the option OPENSSL_INIT_LOAD_CRYPTO_STRINGS will be ignored. she said what she said. 💀
OPENSSL_INIT_LOAD_CRYPTO_STRINGS — automatic loading of the libcrypto error strings. with this option the library will automatically load the libcrypto error strings. this one is a default option. once selected, subsequent calls to OPENSSL_init_crypto() with the option OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS will be ignored.
OPENSSL_INIT_ADD_ALL_CIPHERS — with this option the library will automatically load and make available all libcrypto ciphers. this is a default option. once selected, subsequent calls to OPENSSL_init_crypto() with the option OPENSSL_INIT_NO_ADD_ALL_CIPHERS will be ignored.
OPENSSL_INIT_ADD_ALL_DIGESTS — with this option the library will automatically load and make available all libcrypto digests. this is a default option. once selected, subsequent calls to OPENSSL_init_crypto() with the option OPENSSL_INIT_NO_ADD_ALL_DIGESTS will be ignored.
OPENSSL_INIT_NO_ADD_ALL_CIPHERS — with this option the library will suppress automatic loading of libcrypto ciphers. this is not a default option. once selected, subsequent calls to OPENSSL_init_crypto() with the option OPENSSL_INIT_ADD_ALL_CIPHERS will be ignored.
OPENSSL_INIT_NO_ADD_ALL_DIGESTS — with this option the library will suppress automatic loading of libcrypto digests. this is not a default option. once selected, subsequent calls to OPENSSL_init_crypto() with the option OPENSSL_INIT_ADD_ALL_DIGESTS will be ignored.
OPENSSL_INIT_LOAD_CONFIG — with this option an OpenSSL configuration file will be automatically loaded and used by calling OPENSSL_config(). this is a default option. ⚠️ note that in OpenSSL 1.1.1 this was the default for libssl but not for libcrypto (see OPENSSL_init_ssl(3) for further details about libssl initialisation). in OpenSSL 1.1.0 this was a nondefault option for both libssl and libcrypto. see the description of OPENSSL_INIT_new(), below. 👀
OPENSSL_INIT_NO_LOAD_CONFIG — with this option the loading of OpenSSL configuration files will be suppressed. it is the equivalent of calling OPENSSL_no_config(). this is not a default option.
OPENSSL_INIT_ASYNC — with this option the library will automatically initialise the libcrypto async sub-library (see ASYNC_start_job(3)). this is a default option. ⚡
OPENSSL_INIT_ENGINE_RDRAND — with this option the library will automatically load and initialise the RDRAND engine (if available). this is not a default option and is deprecated in OpenSSL 3.0. 👵
OPENSSL_INIT_ENGINE_DYNAMIC — with this option the library will automatically load and initialise the dynamic engine. this is not a default option and is deprecated in OpenSSL 3.0.
OPENSSL_INIT_ENGINE_OPENSSL — with this option the library will automatically load and initialise the openssl engine. this is not a default option and is deprecated in OpenSSL 3.0.
OPENSSL_INIT_ENGINE_CRYPTODEV — with this option the library will automatically load and initialise the cryptodev engine (if available). this is not a default option and is deprecated in OpenSSL 3.0.
OPENSSL_INIT_ENGINE_CAPI — with this option the library will automatically load and initialise the CAPI engine (if available). this is not a default option and is deprecated in OpenSSL 3.0.
OPENSSL_INIT_ENGINE_PADLOCK — with this option the library will automatically load and initialise the padlock engine (if available). this is not a default option and is deprecated in OpenSSL 3.0.
OPENSSL_INIT_ENGINE_AFALG — with this option the library will automatically load and initialise the AFALG engine. this is not a default option and is deprecated in OpenSSL 3.0.
OPENSSL_INIT_ENGINE_ALL_BUILTIN — with this option the library will automatically load and initialise all the built in engines listed above, with the exception of the openssl and afalg engines. this is not a default option and is deprecated in OpenSSL 3.0.
OPENSSL_INIT_ATFORK — with this option the library will register its fork handlers. see OPENSSL_fork_prepare(3) for details. 🍴
OPENSSL_INIT_NO_ATEXIT — by default OpenSSL will attempt to clean itself up when the process exits via an "atexit" handler. using this option suppresses that behaviour. this means the application will have to clean up OpenSSL explicitly using OPENSSL_cleanup(). you're on your own, bestie 🫡

multiple options may be combined together in a single call to OPENSSL_init_crypto(). for example:

OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS
                    | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL);

the OPENSSL_cleanup() function deinitialises OpenSSL (both libcrypto and libssl). all resources allocated by OpenSSL are freed. typically there should be no need to call this function directly, as it is initiated automatically on application exit — this is done via the standard C library atexit() function. but in the event that the application will close in a manner that will not call the registered atexit() handlers, then the application should call OPENSSL_cleanup() directly. 🧹

💜 developers of libraries using OpenSSL are discouraged from calling this function and should instead, typically, rely on auto-deinitialisation. this is to avoid error conditions where both an application and a library it depends on both use OpenSSL, and the library deinitialises it before the application has finished using it. messy. we don't do messy.

once OPENSSL_cleanup() has been called, the library cannot be reinitialised. attempts to call OPENSSL_init_crypto() will fail and an ERR_R_INIT_FAIL error will be added to the error stack. 😭 and here's the kicker — because initialisation has failed, OpenSSL error strings will not be available, only an error code. this code can be put through the openssl errstr command line application to produce a human readable error (see openssl-errstr(1)). the more you know ✨

the OPENSSL_atexit() function enables the registration of a function to be called during OPENSSL_cleanup(). stop handlers are called after deinitialisation of resources local to a thread, but before other process wide resources are freed. and in the event that multiple stop handlers are registered — no guarantees are made about the order of execution. so like, don't count on a specific order. 🙈

the OPENSSL_thread_stop_ex() function deallocates resources associated with the current thread for the given OSSL_LIB_CTX ctx. the ctx parameter can be NULL, in which case the default OSSL_LIB_CTX is used. 🧵

typically, this function will be called automatically by the library when the thread exits — as long as the OSSL_LIB_CTX has not been freed before the thread exits. if OSSL_LIB_CTX_free() is called, OPENSSL_thread_stop_ex will be called automatically for the current thread (but not any other threads that may have used this OSSL_LIB_CTX).

OPENSSL_thread_stop_ex should be called on all threads that will exit after the OSSL_LIB_CTX is freed. typically this is not necessary for the default OSSL_LIB_CTX (because all resources are cleaned up on library exit) except if thread local resources should be freed before library exit, or under the circumstances described in the NOTES section below. 👑

OPENSSL_thread_stop() is the same as OPENSSL_thread_stop_ex() except that the default OSSL_LIB_CTX is always used.

the OPENSSL_INIT_LOAD_CONFIG flag will load a configuration file, as with CONF_modules_load_file(3) with NULL filename and application name, and the CONF_MFLAGS_IGNORE_MISSING_FILE, CONF_MFLAGS_IGNORE_RETURN_CODES and CONF_MFLAGS_DEFAULT_SECTION flags. 📄 the filename, application name, and flags can be customized by providing a non-null OPENSSL_INIT_SETTINGS object. the object can be allocated via OPENSSL_INIT_new(). the OPENSSL_INIT_set_config_filename() function can be used to specify a nondefault filename, which is copied and need not refer to persistent storage. similarly, OPENSSL_INIT_set_config_appname() can be used to specify a nondefault application name. finally, OPENSSL_INIT_set_file_flags can be used to specify nondefault flags. 🎀

⚠️ if the CONF_MFLAGS_IGNORE_RETURN_CODES flag is not included, any errors in the configuration file will cause an error return from OPENSSL_init_crypto or indirectly OPENSSL_init_ssl(3). so like, heads up fr fr.

the object can be released with OPENSSL_INIT_free() when done. and if the argument to OPENSSL_INIT_free() is NULL — nothing is done. iconic, honestly. 💅

🫶 NOTES (the fine print, bestie, pls read it)

So like… resources that are local to a thread get deallocated automatically when that thread exits — iconic, self-cleaning behaviour. In a pthreads environment that means when pthread_exit() is called, the cleanup just happens. On Windows platforms this is done in response to a DLL_THREAD_DETACH message being sent to the libcrypto32.dll entry point.

But — and this is the tea ☕ — some Windows functions may cause threads to exit without sending this message (for example ExitProcess()). Rude! If your app uses such functions, then the application must free up OpenSSL resources directly via a call to OPENSSL_thread_stop() on each thread. No cap.

Same energy for static linking: this message also won't be sent if OpenSSL is linked statically, and therefore applications using static linking should also call OPENSSL_thread_stop() on each thread. And one more: if OpenSSL is loaded dynamically via LoadLibrary() and the threads are not destroyed until after FreeLibrary() is called, then each thread should call OPENSSL_thread_stop() prior to the FreeLibrary() call. Look at you, doing your own cleanup, very main character 💅

Over on Linux/Unix: where OpenSSL has been loaded via dlopen() and the application is multi-threaded and dlclose() is subsequently called prior to the threads being destroyed, then OpenSSL will not be able to deallocate resources associated with those threads 😭 The application should either call OPENSSL_thread_stop() on each thread prior to the dlclose() call, or alternatively the original dlopen() call should use the RTLD_NODELETE flag (where available on the platform). Pick your fighter 🎀

⚠️ tl;dr: if the runtime can't tell you the thread died, you have to tell OpenSSL. Call OPENSSL_thread_stop(). Periodt.

✨ RETURN VALUES ✨

The functions OPENSSL_init_crypto, OPENSSL_atexit() and OPENSSL_INIT_set_config_appname() return 1 on success or 0 on error. That's it, that's the whole vibe check — 1 slay, 0 sad 💀

🌸 SEE ALSO 🌸

OPENSSL_init_ssl(3) — the sibling page, go read it too, bestie 🦋

👑 HISTORY 👑

The OPENSSL_init_crypto(), OPENSSL_cleanup(), OPENSSL_atexit(), OPENSSL_thread_stop(), OPENSSL_INIT_new(), OPENSSL_INIT_set_config_appname() and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0. So they're not new new, they're legacy-famous ⭐

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

📜 Real talk: that link and that LICENSE file are doing the legal heavy lifting — don't skip the compliance bit, it's giving "read the ToS before you click accept" energy.

💖 and that's the whole page, bestie! 💖 This little beauty is OpenSSL 3.5.7, dated 2026-06-09, and the manpage goes by OPENSSL_INIT_CRYPTO(3SSL). Go forth and initialise responsibly 🧚‍♀️🌸

📦 where this page comes from

debian trixie: libssl-doc 3.5.7-1~deb13u2 · Apache-2.0
debian trixie: libssl-doc 3.5.7-1~deb13u3 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms