.\" $OpenBSD: SSL_CTX_new.3,v 1.3 2017/08/19 23:45:10 schwarze Exp $ .\" OpenSSL 21cd6e00 Aug 17 15:21:33 2015 -0400 .\" .\" This file was written by Lutz Jaenicke . .\" Copyright (c) 2000, 2005, 2012, 2013, 2015, 2016 The OpenSSL Project. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" 3. All advertising materials mentioning features or use of this .\" software must display the following acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" .\" .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to .\" endorse or promote products derived from this software without .\" prior written permission. For written permission, please contact .\" openssl-core@openssl.org. .\" .\" 5. Products derived from this software may not be called "OpenSSL" .\" nor may "OpenSSL" appear in their names without prior written .\" permission of the OpenSSL Project. .\" .\" 6. Redistributions of any form whatsoever must retain the following .\" acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" .\" .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: August 19 2017 $ .Dt SSL_CTX_NEW 3 .Os .Sh NAME .Nm SSL_CTX_new , .Nm TLS_method , .Nm TLS_server_method , .Nm TLS_client_method , .Nm SSLv23_method , .Nm SSLv23_server_method , .Nm SSLv23_client_method , .Nm TLSv1_method , .Nm TLSv1_server_method , .Nm TLSv1_client_method , .Nm TLSv1_1_method , .Nm TLSv1_1_server_method , .Nm TLSv1_1_client_method , .Nm TLSv1_2_method , .Nm TLSv1_2_server_method , .Nm TLSv1_2_client_method , .Nm DTLSv1_method , .Nm DTLSv1_server_method , .Nm DTLSv1_client_method .Nd create a new SSL_CTX object as framework for TLS/SSL enabled functions .Sh SYNOPSIS .In openssl/ssl.h .Ft SSL_CTX * .Fn SSL_CTX_new "const SSL_METHOD *method" .Ft const SSL_METHOD * .Fn TLS_method void .Ft const SSL_METHOD * .Fn TLS_server_method void .Ft const SSL_METHOD * .Fn TLS_client_method void .Ft const SSL_METHOD * .Fn SSLv23_method void .Ft const SSL_METHOD * .Fn SSLv23_server_method void .Ft const SSL_METHOD * .Fn SSLv23_client_method void .Ft const SSL_METHOD * .Fn TLSv1_method void .Ft const SSL_METHOD * .Fn TLSv1_server_method void .Ft const SSL_METHOD * .Fn TLSv1_client_method void .Ft const SSL_METHOD * .Fn TLSv1_1_method void .Ft const SSL_METHOD * .Fn TLSv1_1_server_method void .Ft const SSL_METHOD * .Fn TLSv1_1_client_method void .Ft const SSL_METHOD * .Fn TLSv1_2_method void .Ft const SSL_METHOD * .Fn TLSv1_2_server_method void .Ft const SSL_METHOD * .Fn TLSv1_2_client_method void .Ft const SSL_METHOD * .Fn DTLSv1_method void .Ft const SSL_METHOD * .Fn DTLSv1_server_method void .Ft const SSL_METHOD * .Fn DTLSv1_client_method void .Sh DESCRIPTION .Fn SSL_CTX_new creates a new .Vt SSL_CTX object as framework to establish TLS/SSL or DTLS enabled connections. It initializes the list of ciphers, the session cache setting, the callbacks, the keys and certificates, and the options to its default values. .Pp The .Vt SSL_CTX object uses .Fa method as its connection method. The methods exist in a generic type (for client and server use), a server only type, and a client only type. .Fa method can be of the following types: .Bl -tag -width Ds .It Xo .Fn TLS_method , .Fn TLS_server_method , .Fn TLS_client_method .Xc 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 and TLSv1.2. Applications should use these methods and avoid the version-specific methods described below. .It Xo .Fn SSLv23_method , .Fn SSLv23_server_method , .Fn SSLv23_client_method .Xc Use of these functions is deprecated. They have been replaced with the above .Fn TLS_method , .Fn TLS_server_method , and .Fn TLS_client_method , respectively. New code should use those functions instead. .It Xo .Fn TLSv1_method , .Fn TLSv1_server_method , .Fn TLSv1_client_method .Xc A TLS/SSL connection established with these methods will only understand the TLSv1 protocol. .It Xo .Fn TLSv1_1_method , .Fn TLSv1_1_server_method , .Fn TLSv1_1_client_method .Xc A TLS/SSL connection established with these methods will only understand the TLSv1.1 protocol. .It Xo .Fn TLSv1_2_method , .Fn TLSv1_2_server_method , .Fn TLSv1_2_client_method .Xc A TLS/SSL connection established with these methods will only understand the TLSv1.2 protocol. .It Xo .Fn DTLSv1_method , .Fn DTLSv1_server_method , .Fn DTLSv1_client_method .Xc These are the version-specific methods for DTLSv1. .El .Pp The list of protocols available can also be limited using the .Dv SSL_OP_NO_TLSv1 , .Dv SSL_OP_NO_TLSv1_1 , and .Dv SSL_OP_NO_TLSv1_2 options of the .Xr SSL_CTX_set_options 3 or .Xr 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. .Sh RETURN VALUES The following return values can occur: .Bl -tag -width Ds .It Dv NULL The creation of a new .Vt SSL_CTX object failed. Check the error stack to find out the reason. .It Pointer to an SSL_CTX object The return value points to an allocated .Vt SSL_CTX object. .El .Sh SEE ALSO .Xr ssl 3 , .Xr SSL_accept 3 , .Xr SSL_CTX_free 3 , .Xr SSL_CTX_set_min_proto_version 3 , .Xr SSL_CTX_set_options 3 , .Xr SSL_set_connect_state 3