SSL_CTX_NEW(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

💖 SSL_CTX_NEW 💖

okay bestie, welcome to the OpenSSL manual page for the whole SSL_CTX_new friend group — section 3SSL, the place where you stand up an SSL_CTX (that's the main-character config object everything TLS/SSL and DTLS hangs off of). it's giving "framework for TLS/SSL or DTLS enabled functions" and honestly? iconic. let's get into it 💅

🌸 NAME 🌸

the squad, all of them, no one left out:

  • SSL_CTX_new
  • SSL_CTX_new_ex
  • SSL_CTX_up_ref
  • TLS_method
  • TLS_server_method
  • TLS_client_method
  • SSLv23_method
  • SSLv23_server_method
  • SSLv23_client_method
  • DTLS_method
  • DTLS_server_method
  • DTLS_client_method

they're all here to create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled functions. that's the assignment 💖

🎀 SYNOPSIS 🎀

#include <openssl/ssl.h>

SSL_CTX *SSL_CTX_new_ex(OSSL_LIB_CTX *libctx, const char *propq,
                        const SSL_METHOD *method);
SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
int SSL_CTX_up_ref(SSL_CTX *ctx);

const SSL_METHOD *TLS_method(void);
const SSL_METHOD *TLS_server_method(void);
const SSL_METHOD *TLS_client_method(void);

const SSL_METHOD *SSLv23_method(void);
const SSL_METHOD *SSLv23_server_method(void);
const SSL_METHOD *SSLv23_client_method(void);

const SSL_METHOD *DTLS_method(void);
const SSL_METHOD *DTLS_server_method(void);
const SSL_METHOD *DTLS_client_method(void);

bestie that's the whole cast, copy the signatures exactly, don't freestyle ✨

🦋 DESCRIPTION 🦋

SSL_CTX_new_ex() creates a brand new SSL_CTX object — that's the thing that holds all the various configuration and data relevant to SSL/TLS or DTLS session establishment. later on, all of that gets inherited by the SSL object that represents an active session. the method parameter says whether the context is gonna be used for the client side, the server side, or both — details are down in NOTES. the library context libctx (peep OSSL_LIB_CTX(3)) is what provides the cryptographic algorithms needed for the session. any cryptographic algorithms used by any SSL objects created from this SSL_CTX get fetched from that libctx using the property query string propq (see "ALGORITHM FETCHING" in crypto(7)). either libctx, propq, or both, may be NULL. no cap.

SSL_CTX_new() does the exact same thing as SSL_CTX_new_ex() except it uses the default library context and doesn't specify a property query string. periodt.

an SSL_CTX object is reference counted. creating one for the first time increments the reference count. freeing it (with SSL_CTX_free) decrements it. when the reference count drops to zero, any memory or resources allocated to the SSL_CTX object get freed. SSL_CTX_up_ref() increments the reference count for an existing SSL_CTX structure.

⚠️ an SSL_CTX object should not be changed after it is used to create any SSL objects, or from multiple threads concurrently, because the implementation does not provide serialization of access for these cases. literally, don't do it. it's not that girl 🙈

🌈 NOTES 🌈

on session establishment, by default, no peer credentials verification is done. you have to explicitly ask for it, typically with SSL_CTX_set_verify(3). and for verifying peer certificates there are so many options you can set using various functions like SSL_CTX_load_verify_locations(3) and SSL_CTX_set1_param(3). the menu is long, babe.

the SSL/(D)TLS implementation uses the X509_STORE_CTX_set_default(3) function to prepare checks for X509_PURPOSE_SSL_SERVER on the client side and X509_PURPOSE_SSL_CLIENT on the server side. the X509_VERIFY_PARAM_set_purpose(3) function can be used — also in conjunction with SSL_CTX_get0_param(3) — to override the default purpose of the session.

the SSL_CTX object uses method as the connection method. three method variants are available: a generic method (for either client or server use), a server-only method, and a client-only method. pick your fighter 💅

👑 the method menu 👑

the method parameter of SSL_CTX_new_ex() and SSL_CTX_new() can be one of the following:

  • SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() — okay so these functions do not exist anymore, they have been renamed to TLS_method(), TLS_server_method() and TLS_client_method() respectively. currently, the old function calls are renamed to the corresponding new ones by preprocessor macros, to ensure that existing code which uses the old function names still compiles. however, using the old function names is deprecated and new code should call the new functions instead. iykyk.
  • TLS_method(), TLS_server_method(), TLS_client_method() — these are the general-purpose, version-flexible SSL/TLS methods. the actual protocol version used will be negotiated to the highest version mutually supported by the client and the server. the supported protocols are TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3. slay.
  • DTLS_method(), DTLS_server_method(), DTLS_client_method() — these are the version-flexible DTLS methods. the supported protocols are DTLS 1.0 and DTLS 1.2.

SSL_CTX_new() initializes the list of ciphers, the session cache setting, the callbacks, the keys and certificates and the options to their default values. a whole glow-up, all at once ✨

TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), DTLS_server_method() and DTLS_client_method() are the version-flexible methods.

if you wanna limit the supported protocols for the version-flexible methods, you can use the SSL_CTX_set_min_proto_version(3), SSL_set_min_proto_version(3), SSL_CTX_set_max_proto_version(3) and SSL_set_max_proto_version(3) functions. using these functions it's possible to choose, like, TLS_server_method() and be able to negotiate with all possible clients, but only allow newer protocols like TLS 1.0, TLS 1.1, TLS 1.2 or TLS 1.3. very demure, very mindful.

the list of protocols available can also be limited using the SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_3, SSL_OP_NO_TLSv1_2 and SSL_OP_NO_TLSv1_3 options of the SSL_CTX_set_options(3) or SSL_set_options(3) functions — but this approach is not recommended. clients should avoid creating "holes" in the set of protocols they support. when disabling a protocol, make sure that you also disable either all previous or all subsequent protocol versions. in clients, when a protocol version is disabled without disabling all previous protocol versions, the effect is to also disable all subsequent protocol versions. so like… be careful bestie 😭

💀 the SSLv3 protocol is deprecated and should generally not be used. applications should typically use SSL_CTX_set_min_proto_version(3) to set the minimum protocol to at least TLS1_VERSION.

🫶 RETURN VALUES 🫶

the following return values can occur:

  • NULL — the creation of a new SSL_CTX object failed. check the error stack to find out the reason. sad girl hours 😭
  • Pointer to an SSL_CTX object — the return value points to an allocated SSL_CTX object.
    • SSL_CTX_up_ref() returns 1 for success and 0 for failure.

💜 SEE ALSO 💜

the required reading list, bestie, don't skip it 📚

💀 HISTORY 💀

  • support for SSLv2 and the corresponding SSLv2_method(), SSLv2_server_method() and SSLv2_client_method() functions were removed in OpenSSL 1.1.0.
  • SSLv23_method(), SSLv23_server_method() and SSLv23_client_method() were deprecated and the preferred TLS_method(), TLS_server_method() and TLS_client_method() functions were added in OpenSSL 1.1.0.
  • all version-specific methods were deprecated in OpenSSL 1.1.0.
  • SSL_CTX_new_ex() was added in OpenSSL 3.0.
  • all version-specific methods were removed in OpenSSL 4.0.

rip to the fallen methods 🕯️

Copyright 2000-2026 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 thing, bestie 🎀 this was the OpenSSL 4.0.3 version of the page, dated 2026-09-29. go forth and make your SSL_CTX responsibly 💖✨

📦 where this page comes from