1=pod 2 3=head1 NAME 4 5TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method, 6SSL_CTX_new, SSL_CTX_new_ex, SSL_CTX_up_ref, SSLv3_method, 7SSLv3_server_method, SSLv3_client_method, TLSv1_method, TLSv1_server_method, 8TLSv1_client_method, TLSv1_1_method, TLSv1_1_server_method, 9TLSv1_1_client_method, TLS_method, TLS_server_method, TLS_client_method, 10SSLv23_method, SSLv23_server_method, SSLv23_client_method, DTLS_method, 11DTLS_server_method, DTLS_client_method, DTLSv1_method, DTLSv1_server_method, 12DTLSv1_client_method, DTLSv1_2_method, DTLSv1_2_server_method, 13DTLSv1_2_client_method 14- create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled 15functions 16 17=head1 SYNOPSIS 18 19 #include <openssl/ssl.h> 20 21 SSL_CTX *SSL_CTX_new_ex(OSSL_LIB_CTX *libctx, const char *propq, 22 const SSL_METHOD *method); 23 SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); 24 int SSL_CTX_up_ref(SSL_CTX *ctx); 25 26 const SSL_METHOD *TLS_method(void); 27 const SSL_METHOD *TLS_server_method(void); 28 const SSL_METHOD *TLS_client_method(void); 29 30 const SSL_METHOD *SSLv23_method(void); 31 const SSL_METHOD *SSLv23_server_method(void); 32 const SSL_METHOD *SSLv23_client_method(void); 33 34 #ifndef OPENSSL_NO_SSL3_METHOD 35 const SSL_METHOD *SSLv3_method(void); 36 const SSL_METHOD *SSLv3_server_method(void); 37 const SSL_METHOD *SSLv3_client_method(void); 38 #endif 39 40 #ifndef OPENSSL_NO_TLS1_METHOD 41 const SSL_METHOD *TLSv1_method(void); 42 const SSL_METHOD *TLSv1_server_method(void); 43 const SSL_METHOD *TLSv1_client_method(void); 44 #endif 45 46 #ifndef OPENSSL_NO_TLS1_1_METHOD 47 const SSL_METHOD *TLSv1_1_method(void); 48 const SSL_METHOD *TLSv1_1_server_method(void); 49 const SSL_METHOD *TLSv1_1_client_method(void); 50 #endif 51 52 #ifndef OPENSSL_NO_TLS1_2_METHOD 53 const SSL_METHOD *TLSv1_2_method(void); 54 const SSL_METHOD *TLSv1_2_server_method(void); 55 const SSL_METHOD *TLSv1_2_client_method(void); 56 #endif 57 58 const SSL_METHOD *DTLS_method(void); 59 const SSL_METHOD *DTLS_server_method(void); 60 const SSL_METHOD *DTLS_client_method(void); 61 62 #ifndef OPENSSL_NO_DTLS1_METHOD 63 const SSL_METHOD *DTLSv1_method(void); 64 const SSL_METHOD *DTLSv1_server_method(void); 65 const SSL_METHOD *DTLSv1_client_method(void); 66 #endif 67 68 #ifndef OPENSSL_NO_DTLS1_2_METHOD 69 const SSL_METHOD *DTLSv1_2_method(void); 70 const SSL_METHOD *DTLSv1_2_server_method(void); 71 const SSL_METHOD *DTLSv1_2_client_method(void); 72 #endif 73 74=head1 DESCRIPTION 75 76SSL_CTX_new_ex() creates a new B<SSL_CTX> object, which holds various 77configuration and data relevant to SSL/TLS or DTLS session establishment. 78These are later inherited by the B<SSL> object representing an active session. 79The I<method> parameter specifies whether the context will be used for the 80client or server side or both - for details see the L</NOTES> below. 81The library context I<libctx> (see L<OSSL_LIB_CTX(3)>) is used to provide the 82cryptographic algorithms needed for the session. Any cryptographic algorithms 83that are used by any B<SSL> objects created from this B<SSL_CTX> will be fetched 84from the I<libctx> using the property query string I<propq> (see 85L<crypto(7)/ALGORITHM FETCHING>. Either or both the I<libctx> or I<propq> 86parameters may be NULL. 87 88SSL_CTX_new() does the same as SSL_CTX_new_ex() except that the default 89library context is used and no property query string is specified. 90 91An B<SSL_CTX> object is reference counted. Creating an B<SSL_CTX> object for the 92first time increments the reference count. Freeing the B<SSL_CTX> (using 93SSL_CTX_free) decrements it. When the reference count drops to zero, any memory 94or resources allocated to the B<SSL_CTX> object are freed. SSL_CTX_up_ref() 95increments the reference count for an existing B<SSL_CTX> structure. 96 97An B<SSL_CTX> object should not be changed after it is used to create any B<SSL> 98objects or from multiple threads concurrently, since the implementation does not 99provide serialization of access for these cases. 100 101=head1 NOTES 102 103On session establishment, by default, no peer credentials verification is done. 104This must be explicitly requested, typically using L<SSL_CTX_set_verify(3)>. 105For verifying peer certificates many options can be set using various functions 106such as L<SSL_CTX_load_verify_locations(3)> and L<SSL_CTX_set1_param(3)>. 107 108The SSL/(D)TLS implementation uses the L<X509_STORE_CTX_set_default(3)> 109function to prepare checks for B<X509_PURPOSE_SSL_SERVER> on the client side 110and B<X509_PURPOSE_SSL_CLIENT> on the server side. 111The L<X509_VERIFY_PARAM_set_purpose(3)> function can be used, also in conjunction 112with L<SSL_CTX_get0_param(3)>, to override the default purpose of the session. 113 114The SSL_CTX object uses I<method> as the connection method. 115Three method variants are available: a generic method (for either client or 116server use), a server-only method, and a client-only method. 117 118The I<method> parameter of SSL_CTX_new_ex() and SSL_CTX_new() 119can be one of the following: 120 121=over 4 122 123=item TLS_method(), TLS_server_method(), TLS_client_method() 124 125These are the general-purpose I<version-flexible> SSL/TLS methods. 126The actual protocol version used will be negotiated to the highest version 127mutually supported by the client and the server. 128The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3. 129Applications should use these methods, and avoid the version-specific 130methods described below, which are deprecated. 131 132=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() 133 134These functions do not exist anymore, they have been renamed to 135TLS_method(), TLS_server_method() and TLS_client_method() respectively. 136Currently, the old function calls are renamed to the corresponding new 137ones by preprocessor macros, to ensure that existing code which uses the 138old function names still compiles. However, using the old function names 139is deprecated and new code should call the new functions instead. 140 141=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method() 142 143A TLS/SSL connection established with these methods will only understand the 144TLSv1.2 protocol. These methods are deprecated. 145 146=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method() 147 148A TLS/SSL connection established with these methods will only understand the 149TLSv1.1 protocol. These methods are deprecated. 150 151=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() 152 153A TLS/SSL connection established with these methods will only understand the 154TLSv1 protocol. These methods are deprecated. 155 156=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method() 157 158A TLS/SSL connection established with these methods will only understand the 159SSLv3 protocol. 160The SSLv3 protocol is deprecated and should not be used. 161 162=item DTLS_method(), DTLS_server_method(), DTLS_client_method() 163 164These are the version-flexible DTLS methods. 165Currently supported protocols are DTLS 1.0 and DTLS 1.2. 166 167=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method() 168 169These are the version-specific methods for DTLSv1.2. 170These methods are deprecated. 171 172=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method() 173 174These are the version-specific methods for DTLSv1. 175These methods are deprecated. 176 177=back 178 179SSL_CTX_new() initializes the list of ciphers, the session cache setting, the 180callbacks, the keys and certificates and the options to their default values. 181 182TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), 183DTLS_server_method() and DTLS_client_method() are the I<version-flexible> 184methods. 185All other methods only support one specific protocol version. 186Use the I<version-flexible> methods instead of the version specific methods. 187 188If you want to limit the supported protocols for the version flexible 189methods you can use L<SSL_CTX_set_min_proto_version(3)>, 190L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and 191L<SSL_set_max_proto_version(3)> functions. 192Using these functions it is possible to choose e.g. TLS_server_method() 193and be able to negotiate with all possible clients, but to only 194allow newer protocols like TLS 1.0, TLS 1.1, TLS 1.2 or TLS 1.3. 195 196The list of protocols available can also be limited using the 197B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1>, 198B<SSL_OP_NO_TLSv1_3>, B<SSL_OP_NO_TLSv1_2> and B<SSL_OP_NO_TLSv1_3> 199options of the 200L<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions, but this approach 201is not recommended. Clients should avoid creating "holes" in the set of 202protocols they support. When disabling a protocol, make sure that you also 203disable either all previous or all subsequent protocol versions. 204In clients, when a protocol version is disabled without disabling I<all> 205previous protocol versions, the effect is to also disable all subsequent 206protocol versions. 207 208The SSLv3 protocol is deprecated and should generally not be used. 209Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set 210the minimum protocol to at least B<TLS1_VERSION>. 211 212=head1 RETURN VALUES 213 214The following return values can occur: 215 216=over 4 217 218=item NULL 219 220The creation of a new SSL_CTX object failed. Check the error stack to find out 221the reason. 222 223=item Pointer to an SSL_CTX object 224 225The return value points to an allocated SSL_CTX object. 226 227SSL_CTX_up_ref() returns 1 for success and 0 for failure. 228 229=back 230 231=head1 SEE ALSO 232 233L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<X509_STORE_CTX_set_default(3)>, 234SSL_CTX_set_verify(3), L<SSL_CTX_set1_param(3)>, L<SSL_CTX_get0_param(3)>, 235L<SSL_connect(3)>, L<SSL_accept(3)>, 236L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)> 237 238=head1 HISTORY 239 240Support for SSLv2 and the corresponding SSLv2_method(), 241SSLv2_server_method() and SSLv2_client_method() functions where 242removed in OpenSSL 1.1.0. 243 244SSLv23_method(), SSLv23_server_method() and SSLv23_client_method() 245were deprecated and the preferred TLS_method(), TLS_server_method() 246and TLS_client_method() functions were added in OpenSSL 1.1.0. 247 248All version-specific methods were deprecated in OpenSSL 1.1.0. 249 250SSL_CTX_new_ex() was added in OpenSSL 3.0. 251 252=head1 COPYRIGHT 253 254Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. 255 256Licensed under the Apache License 2.0 (the "License"). You may not use 257this file except in compliance with the License. You can obtain a copy 258in the file LICENSE in the source distribution or at 259L<https://www.openssl.org/source/license.html>. 260 261=cut 262
