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