1.\" $OpenBSD: SSL_CTX_new.3,v 1.15 2020/10/12 09:26:57 schwarze Exp $ 2.\" full merge up to: OpenSSL 21cd6e00 Oct 21 14:40:15 2015 +0100 3.\" selective merge up to: OpenSSL 8f75443f May 24 14:04:26 2019 +0200 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: October 12 2020 $ 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 a framework for TLS 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 a framework to establish TLS 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, which can be: 160.Bl -tag -width Ds 161.It Fn TLS_method 162The general-purpose version-flexible TLS method. 163The protocol version used will be negotiated to the highest 164version mutually supported by the client and the server. 165The supported protocols are TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3. 166.It Fn DTLS_method 167The version-flexible DTLS method. 168The currently supported protocol is DTLS 1.0. 169.El 170.Pp 171The following 172.Fa method 173arguments are deprecated: 174.Bl -tag -width Ds 175.It Xo 176.Fn TLS_server_method , 177.Fn TLS_client_method , 178.Fn SSLv23_method , 179.Fn SSLv23_server_method , 180.Fn SSLv23_client_method 181.Xc 182Deprecated aliases for 183.Fn TLS_method . 184.It Xo 185.Fn DTLS_server_method , 186.Fn DTLS_client_method 187.Xc 188Deprecated aliases for 189.Fn DTLS_method . 190.It Xo 191.Fn TLSv1_method , 192.Fn TLSv1_server_method , 193.Fn TLSv1_client_method 194.Xc 195A connection established with these methods will only 196understand the TLSv1 protocol. 197.It Xo 198.Fn TLSv1_1_method , 199.Fn TLSv1_1_server_method , 200.Fn TLSv1_1_client_method 201.Xc 202A connection established with these methods will only 203understand the TLSv1.1 protocol. 204.It Xo 205.Fn TLSv1_2_method , 206.Fn TLSv1_2_server_method , 207.Fn TLSv1_2_client_method 208.Xc 209A connection established with these methods will only 210understand the TLSv1.2 protocol. 211.It Xo 212.Fn DTLSv1_method , 213.Fn DTLSv1_server_method , 214.Fn DTLSv1_client_method 215.Xc 216These are the version-specific methods for DTLSv1. 217.El 218.Pp 219In LibreSSL, the methods containing the substrings 220.Dq _server 221or 222.Dq _client 223in their names return the same objects 224as the methods without these substrings. 225.Pp 226The list of protocols available can also be limited using the 227.Dv SSL_OP_NO_TLSv1 , 228.Dv SSL_OP_NO_TLSv1_1 , 229and 230.Dv SSL_OP_NO_TLSv1_2 231options of the 232.Xr SSL_CTX_set_options 3 233or 234.Xr SSL_set_options 3 235functions, but this approach is not recommended. 236Clients should avoid creating "holes" in the set of protocols they support. 237When disabling a protocol, make sure that you also disable either 238all previous or all subsequent protocol versions. 239In clients, when a protocol version is disabled without disabling 240all previous protocol versions, the effect is to also disable all 241subsequent protocol versions. 242.Sh RETURN VALUES 243.Fn SSL_CTX_new 244returns a pointer to the newly allocated object or 245.Dv NULL 246on failure. 247Check the error stack to find out the reason for failure. 248.Pp 249.Fn SSL_CTX_up_ref 250returns 1 for success or 0 for failure. 251.Pp 252.Fn TLS_method 253and the other 254.Fn *_method 255functions return pointers to constant static objects. 256.Sh SEE ALSO 257.Xr ssl 3 , 258.Xr SSL_accept 3 , 259.Xr SSL_CTX_free 3 , 260.Xr SSL_CTX_set_min_proto_version 3 , 261.Xr SSL_CTX_set_options 3 , 262.Xr SSL_set_connect_state 3 263.Sh HISTORY 264.Fn SSL_CTX_new 265first appeared in SSLeay 0.5.1. 266.Fn SSLv23_method , 267.Fn SSLv23_server_method , 268and 269.Fn SSLv23_client_method 270first appeared in SSLeay 0.8.0. 271.Fn TLSv1_method , 272.Fn TLSv1_server_method , 273and 274.Fn TLSv1_client_method 275first appeared in SSLeay 0.9.0. 276All these functions have been available since 277.Ox 2.4 . 278.Pp 279.Fn DTLSv1_method , 280.Fn DTLSv1_server_method , 281and 282.Fn DTLSv1_client_method 283first appeared in OpenSSL 0.9.8 and have been available since 284.Ox 4.5 . 285.Pp 286.Fn TLSv1_1_method , 287.Fn TLSv1_1_server_method , 288.Fn TLSv1_1_client_method , 289.Fn TLSv1_2_method , 290.Fn TLSv1_2_server_method , 291and 292.Fn TLSv1_2_client_method 293first appeared in OpenSSL 1.0.1 and have been available since 294.Ox 5.3 . 295.Pp 296.Fn DTLS_method , 297.Fn DTLS_server_method , 298and 299.Fn DTLS_client_method 300first appeared in OpenSSL 1.0.2 and have been available since 301.Ox 6.5 . 302.Pp 303.Fn TLS_method , 304.Fn TLS_server_method , 305and 306.Fn TLS_client_method 307first appeared in OpenSSL 1.1.0 and have been available since 308.Ox 5.8 . 309.Pp 310.Fn SSL_CTX_up_ref 311first appeared in OpenSSL 1.1.0 and has been available since 312.Ox 6.3 . 313