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)>. 107The L<X509_VERIFY_PARAM_set_purpose(3)> function can be used, also in conjunction 108with L<SSL_CTX_get0_param(3)>, to set the intended purpose of the session. 109The default is B<X509_PURPOSE_SSL_SERVER> on the client side 110and B<X509_PURPOSE_SSL_CLIENT> on the server side. 111 112The SSL_CTX object uses I<method> as the connection method. 113Three method variants are available: a generic method (for either client or 114server use), a server-only method, and a client-only method. 115 116The I<method> parameter of SSL_CTX_new_ex() and SSL_CTX_new() 117can be one of the following: 118 119=over 4 120 121=item TLS_method(), TLS_server_method(), TLS_client_method() 122 123These are the general-purpose I<version-flexible> SSL/TLS methods. 124The actual protocol version used will be negotiated to the highest version 125mutually supported by the client and the server. 126The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3. 127Applications should use these methods, and avoid the version-specific 128methods described below, which are deprecated. 129 130=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() 131 132These functions do not exist anymore, they have been renamed to 133TLS_method(), TLS_server_method() and TLS_client_method() respectively. 134Currently, the old function calls are renamed to the corresponding new 135ones by preprocessor macros, to ensure that existing code which uses the 136old function names still compiles. However, using the old function names 137is deprecated and new code should call the new functions instead. 138 139=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method() 140 141A TLS/SSL connection established with these methods will only understand the 142TLSv1.2 protocol. These methods are deprecated. 143 144=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method() 145 146A TLS/SSL connection established with these methods will only understand the 147TLSv1.1 protocol. These methods are deprecated. 148 149=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() 150 151A TLS/SSL connection established with these methods will only understand the 152TLSv1 protocol. These methods are deprecated. 153 154=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method() 155 156A TLS/SSL connection established with these methods will only understand the 157SSLv3 protocol. 158The SSLv3 protocol is deprecated and should not be used. 159 160=item DTLS_method(), DTLS_server_method(), DTLS_client_method() 161 162These are the version-flexible DTLS methods. 163Currently supported protocols are DTLS 1.0 and DTLS 1.2. 164 165=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method() 166 167These are the version-specific methods for DTLSv1.2. 168These methods are deprecated. 169 170=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method() 171 172These are the version-specific methods for DTLSv1. 173These methods are deprecated. 174 175=back 176 177SSL_CTX_new() initializes the list of ciphers, the session cache setting, the 178callbacks, the keys and certificates and the options to their default values. 179 180TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), 181DTLS_server_method() and DTLS_client_method() are the I<version-flexible> 182methods. 183All other methods only support one specific protocol version. 184Use the I<version-flexible> methods instead of the version specific methods. 185 186If you want to limit the supported protocols for the version flexible 187methods you can use L<SSL_CTX_set_min_proto_version(3)>, 188L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and 189L<SSL_set_max_proto_version(3)> functions. 190Using these functions it is possible to choose e.g. TLS_server_method() 191and be able to negotiate with all possible clients, but to only 192allow newer protocols like TLS 1.0, TLS 1.1, TLS 1.2 or TLS 1.3. 193 194The list of protocols available can also be limited using the 195B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1>, 196B<SSL_OP_NO_TLSv1_3>, B<SSL_OP_NO_TLSv1_2> and B<SSL_OP_NO_TLSv1_3> 197options of the 198L<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions, but this approach 199is not recommended. Clients should avoid creating "holes" in the set of 200protocols they support. When disabling a protocol, make sure that you also 201disable either all previous or all subsequent protocol versions. 202In clients, when a protocol version is disabled without disabling I<all> 203previous protocol versions, the effect is to also disable all subsequent 204protocol versions. 205 206The SSLv3 protocol is deprecated and should generally not be used. 207Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set 208the minimum protocol to at least B<TLS1_VERSION>. 209 210=head1 RETURN VALUES 211 212The following return values can occur: 213 214=over 4 215 216=item NULL 217 218The creation of a new SSL_CTX object failed. Check the error stack to find out 219the reason. 220 221=item Pointer to an SSL_CTX object 222 223The return value points to an allocated SSL_CTX object. 224 225SSL_CTX_up_ref() returns 1 for success and 0 for failure. 226 227=back 228 229=head1 SEE ALSO 230 231L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, 232SSL_CTX_set_verify(3), L<SSL_CTX_set1_param(3)>, L<SSL_CTX_get0_param(3)>, 233L<SSL_connect(3)>, L<SSL_accept(3)>, 234L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)> 235 236=head1 HISTORY 237 238Support for SSLv2 and the corresponding SSLv2_method(), 239SSLv2_server_method() and SSLv2_client_method() functions where 240removed in OpenSSL 1.1.0. 241 242SSLv23_method(), SSLv23_server_method() and SSLv23_client_method() 243were deprecated and the preferred TLS_method(), TLS_server_method() 244and TLS_client_method() functions were added in OpenSSL 1.1.0. 245 246All version-specific methods were deprecated in OpenSSL 1.1.0. 247 248SSL_CTX_new_ex() was added in OpenSSL 3.0. 249 250=head1 COPYRIGHT 251 252Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. 253 254Licensed under the Apache License 2.0 (the "License"). You may not use 255this file except in compliance with the License. You can obtain a copy 256in the file LICENSE in the source distribution or at 257L<https://www.openssl.org/source/license.html>. 258 259=cut 260
