1.\" $OpenBSD: SSL_CTX_new.3,v 1.11 2019/03/18 06:23:38 schwarze Exp $ 2.\" full merge up to: OpenSSL 21cd6e00 Oct 21 14:40:15 2015 +0100 3.\" selective merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +0100 4.\" 5.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>. 6.\" Copyright (c) 2000, 2005, 2012, 2013, 2015, 2016 The OpenSSL Project. 7.\" All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" 3. All advertising materials mentioning features or use of this 22.\" software must display the following acknowledgment: 23.\" "This product includes software developed by the OpenSSL Project 24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 25.\" 26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 27.\" endorse or promote products derived from this software without 28.\" prior written permission. For written permission, please contact 29.\" openssl-core@openssl.org. 30.\" 31.\" 5. Products derived from this software may not be called "OpenSSL" 32.\" nor may "OpenSSL" appear in their names without prior written 33.\" permission of the OpenSSL Project. 34.\" 35.\" 6. Redistributions of any form whatsoever must retain the following 36.\" acknowledgment: 37.\" "This product includes software developed by the OpenSSL Project 38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51.\" OF THE POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd $Mdocdate: March 18 2019 $ 54.Dt SSL_CTX_NEW 3 55.Os 56.Sh NAME 57.Nm SSL_CTX_new , 58.Nm SSL_CTX_up_ref , 59.Nm TLS_method , 60.Nm TLS_server_method , 61.Nm TLS_client_method , 62.Nm SSLv23_method , 63.Nm SSLv23_server_method , 64.Nm SSLv23_client_method , 65.Nm TLSv1_method , 66.Nm TLSv1_server_method , 67.Nm TLSv1_client_method , 68.Nm TLSv1_1_method , 69.Nm TLSv1_1_server_method , 70.Nm TLSv1_1_client_method , 71.Nm TLSv1_2_method , 72.Nm TLSv1_2_server_method , 73.Nm TLSv1_2_client_method , 74.Nm DTLS_method , 75.Nm DTLS_server_method , 76.Nm DTLS_client_method , 77.Nm DTLSv1_method , 78.Nm DTLSv1_server_method , 79.Nm DTLSv1_client_method 80.Nd create a new SSL_CTX object as framework for TLS/SSL enabled functions 81.Sh SYNOPSIS 82.In openssl/ssl.h 83.Ft SSL_CTX * 84.Fn SSL_CTX_new "const SSL_METHOD *method" 85.Ft int 86.Fn SSL_CTX_up_ref "SSL_CTX *ctx" 87.Ft const SSL_METHOD * 88.Fn TLS_method void 89.Ft const SSL_METHOD * 90.Fn TLS_server_method void 91.Ft const SSL_METHOD * 92.Fn TLS_client_method void 93.Ft const SSL_METHOD * 94.Fn SSLv23_method void 95.Ft const SSL_METHOD * 96.Fn SSLv23_server_method void 97.Ft const SSL_METHOD * 98.Fn SSLv23_client_method void 99.Ft const SSL_METHOD * 100.Fn TLSv1_method void 101.Ft const SSL_METHOD * 102.Fn TLSv1_server_method void 103.Ft const SSL_METHOD * 104.Fn TLSv1_client_method void 105.Ft const SSL_METHOD * 106.Fn TLSv1_1_method void 107.Ft const SSL_METHOD * 108.Fn TLSv1_1_server_method void 109.Ft const SSL_METHOD * 110.Fn TLSv1_1_client_method void 111.Ft const SSL_METHOD * 112.Fn TLSv1_2_method void 113.Ft const SSL_METHOD * 114.Fn TLSv1_2_server_method void 115.Ft const SSL_METHOD * 116.Fn TLSv1_2_client_method void 117.Ft const SSL_METHOD * 118.Fn DTLS_method void 119.Ft const SSL_METHOD * 120.Fn DTLS_server_method void 121.Ft const SSL_METHOD * 122.Fn DTLS_client_method void 123.Ft const SSL_METHOD * 124.Fn DTLSv1_method void 125.Ft const SSL_METHOD * 126.Fn DTLSv1_server_method void 127.Ft const SSL_METHOD * 128.Fn DTLSv1_client_method void 129.Sh DESCRIPTION 130.Fn SSL_CTX_new 131creates a new 132.Vt SSL_CTX 133object as framework to establish TLS/SSL or DTLS enabled connections. 134It initializes the list of ciphers, the session cache setting, the 135callbacks, the keys and certificates, and the options to its default 136values. 137.Pp 138An 139.Vt SSL_CTX 140object is reference counted. 141Creating a new 142.Vt SSL_CTX 143object sets its reference count to 1. 144Calling 145.Fn SSL_CTX_up_ref 146on it increments the reference count by 1. 147Calling 148.Xr SSL_CTX_free 3 149on it decrements the reference count by 1. 150When the reference count drops to zero, 151any memory or resources allocated to the 152.Vt SSL_CTX 153object are freed. 154.Pp 155The 156.Vt SSL_CTX 157object uses 158.Fa method 159as its connection method. 160The methods exist in a generic type (for client and server use), 161a server only type, and a client only type. 162.Fa method 163can be of the following types: 164.Bl -tag -width Ds 165.It Xo 166.Fn TLS_method , 167.Fn TLS_server_method , 168.Fn TLS_client_method 169.Xc 170These are the general-purpose version-flexible SSL/TLS methods. 171The actual protocol version used will be negotiated to the highest 172version mutually supported by the client and the server. 173The supported protocols are TLSv1, TLSv1.1 and TLSv1.2. 174Applications should use these methods and avoid the version-specific 175methods described below. 176.It Xo 177.Fn SSLv23_method , 178.Fn SSLv23_server_method , 179.Fn SSLv23_client_method 180.Xc 181Use of these functions is deprecated. 182They have been replaced with the above 183.Fn TLS_method , 184.Fn TLS_server_method , 185and 186.Fn TLS_client_method , 187respectively. 188New code should use those functions instead. 189.It Xo 190.Fn TLSv1_method , 191.Fn TLSv1_server_method , 192.Fn TLSv1_client_method 193.Xc 194A TLS/SSL connection established with these methods will only 195understand the TLSv1 protocol. 196.It Xo 197.Fn TLSv1_1_method , 198.Fn TLSv1_1_server_method , 199.Fn TLSv1_1_client_method 200.Xc 201A TLS/SSL connection established with these methods will only 202understand the TLSv1.1 protocol. 203.It Xo 204.Fn TLSv1_2_method , 205.Fn TLSv1_2_server_method , 206.Fn TLSv1_2_client_method 207.Xc 208A TLS/SSL connection established with these methods will only 209understand the TLSv1.2 protocol. 210.It Xo 211.Fn DTLS_method , 212.Fn DTLS_server_method , 213.Fn DTLS_client_method 214.Xc 215These are the version-flexible DTLS methods. 216The currently supported protocol is DTLS 1.0. 217.It Xo 218.Fn DTLSv1_method , 219.Fn DTLSv1_server_method , 220.Fn DTLSv1_client_method 221.Xc 222These are the version-specific methods for DTLSv1. 223.El 224.Pp 225The list of protocols available can also be limited using the 226.Dv SSL_OP_NO_TLSv1 , 227.Dv SSL_OP_NO_TLSv1_1 , 228and 229.Dv SSL_OP_NO_TLSv1_2 230options of the 231.Xr SSL_CTX_set_options 3 232or 233.Xr SSL_set_options 3 234functions, but this approach is not recommended. 235Clients should avoid creating "holes" in the set of protocols they support. 236When disabling a protocol, make sure that you also disable either 237all previous or all subsequent protocol versions. 238In clients, when a protocol version is disabled without disabling 239all previous protocol versions, the effect is to also disable all 240subsequent protocol versions. 241.Sh RETURN VALUES 242.Fn SSL_CTX_new 243returns a pointer to the newly allocated object or 244.Dv NULL 245on failure. 246Check the error stack to find out the reason for failure. 247.Pp 248.Fn SSL_CTX_up_ref 249returns 1 for success or 0 for failure. 250.Sh SEE ALSO 251.Xr ssl 3 , 252.Xr SSL_accept 3 , 253.Xr SSL_CTX_free 3 , 254.Xr SSL_CTX_set_min_proto_version 3 , 255.Xr SSL_CTX_set_options 3 , 256.Xr SSL_set_connect_state 3 257.Sh HISTORY 258.Fn SSL_CTX_new 259first appeared in SSLeay 0.5.1. 260.Fn SSLv23_method , 261.Fn SSLv23_server_method , 262and 263.Fn SSLv23_client_method 264first appeared in SSLeay 0.8.0. 265.Fn TLSv1_method , 266.Fn TLSv1_server_method , 267and 268.Fn TLSv1_client_method 269first appeared in SSLeay 0.9.0. 270All these functions have been available since 271.Ox 2.4 . 272.Pp 273.Fn DTLSv1_method , 274.Fn DTLSv1_server_method , 275and 276.Fn DTLSv1_client_method 277first appeared in OpenSSL 0.9.8 and have been available since 278.Ox 4.5 . 279.Pp 280.Fn TLSv1_1_method , 281.Fn TLSv1_1_server_method , 282.Fn TLSv1_1_client_method , 283.Fn TLSv1_2_method , 284.Fn TLSv1_2_server_method , 285and 286.Fn TLSv1_2_client_method 287first appeared in OpenSSL 1.0.1 and have been available since 288.Ox 5.3 . 289.Pp 290.Fn DTLS_method , 291.Fn DTLS_server_method , 292and 293.Fn DTLS_client_method 294first appeared in OpenSSL 1.0.2 and have been available since 295.Ox 6.5 . 296.Pp 297.Fn TLS_method , 298.Fn TLS_server_method , 299and 300.Fn TLS_client_method 301first appeared in OpenSSL 1.1.0 and have been available since 302.Ox 5.8 . 303.Pp 304.Fn SSL_CTX_up_ref 305first appeared in OpenSSL 1.1.0 and has been available since 306.Ox 6.3 . 307