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. 98 99=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() 100 101Use of these functions is deprecated. They have been replaced with the above 102TLS_method(), TLS_server_method() and TLS_client_method() respectively. New 103code should use those functions instead. 104 105=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method() 106 107A TLS/SSL connection established with these methods will only understand the 108TLSv1.2 protocol. 109 110=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method() 111 112A TLS/SSL connection established with these methods will only understand the 113TLSv1.1 protocol. 114 115=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() 116 117A TLS/SSL connection established with these methods will only understand the 118TLSv1 protocol. 119 120=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method() 121 122A TLS/SSL connection established with these methods will only understand the 123SSLv3 protocol. 124The SSLv3 protocol is deprecated and should not be used. 125 126=item DTLS_method(), DTLS_server_method(), DTLS_client_method() 127 128These are the version-flexible DTLS methods. 129Currently supported protocols are DTLS 1.0 and DTLS 1.2. 130 131=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method() 132 133These are the version-specific methods for DTLSv1.2. 134 135=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method() 136 137These are the version-specific methods for DTLSv1. 138 139=back 140 141SSL_CTX_new() initializes the list of ciphers, the session cache setting, the 142callbacks, the keys and certificates and the options to their default values. 143 144TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), 145DTLS_server_method() and DTLS_client_method() are the I<version-flexible> 146methods. 147All other methods only support one specific protocol version. 148Use the I<version-flexible> methods instead of the version specific methods. 149 150If you want to limit the supported protocols for the version flexible 151methods you can use L<SSL_CTX_set_min_proto_version(3)>, 152L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and 153L<SSL_set_max_proto_version(3)> functions. 154Using these functions it is possible to choose e.g. TLS_server_method() 155and be able to negotiate with all possible clients, but to only 156allow newer protocols like TLS 1.0, TLS 1.1, TLS 1.2 or TLS 1.3. 157 158The list of protocols available can also be limited using the 159B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1>, 160B<SSL_OP_NO_TLSv1_3>, B<SSL_OP_NO_TLSv1_2> and B<SSL_OP_NO_TLSv1_3> 161options of the 162L<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions, but this approach 163is not recommended. Clients should avoid creating "holes" in the set of 164protocols they support. When disabling a protocol, make sure that you also 165disable either all previous or all subsequent protocol versions. 166In clients, when a protocol version is disabled without disabling I<all> 167previous protocol versions, the effect is to also disable all subsequent 168protocol versions. 169 170The SSLv3 protocol is deprecated and should generally not be used. 171Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set 172the minimum protocol to at least B<TLS1_VERSION>. 173 174=head1 RETURN VALUES 175 176The following return values can occur: 177 178=over 4 179 180=item NULL 181 182The creation of a new SSL_CTX object failed. Check the error stack to find out 183the reason. 184 185=item Pointer to an SSL_CTX object 186 187The return value points to an allocated SSL_CTX object. 188 189SSL_CTX_up_ref() returns 1 for success and 0 for failure. 190 191=back 192 193=head1 HISTORY 194 195Support for SSLv2 and the corresponding SSLv2_method(), 196SSLv2_server_method() and SSLv2_client_method() functions where 197removed in OpenSSL 1.1.0. 198 199SSLv23_method(), SSLv23_server_method() and SSLv23_client_method() 200were deprecated and the preferred TLS_method(), TLS_server_method() 201and TLS_client_method() functions were introduced in OpenSSL 1.1.0. 202 203All version-specific methods were deprecated in OpenSSL 1.1.0. 204 205=head1 SEE ALSO 206 207L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>, 208L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)> 209 210=head1 COPYRIGHT 211 212Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. 213 214Licensed under the OpenSSL license (the "License"). You may not use 215this file except in compliance with the License. You can obtain a copy 216in the file LICENSE in the source distribution or at 217L<https://www.openssl.org/source/license.html>. 218 219=cut 220