1.\" $OpenBSD: SSL_CTX_new.3,v 1.16 2021/04/15 16:30:14 tb 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: April 15 2021 $ 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.Nm DTLSv1_2_method , 81.Nm DTLSv1_2_server_method , 82.Nm DTLSv1_2_client_method 83.Nd create a new SSL_CTX object as a framework for TLS enabled functions 84.Sh SYNOPSIS 85.In openssl/ssl.h 86.Ft SSL_CTX * 87.Fn SSL_CTX_new "const SSL_METHOD *method" 88.Ft int 89.Fn SSL_CTX_up_ref "SSL_CTX *ctx" 90.Ft const SSL_METHOD * 91.Fn TLS_method void 92.Ft const SSL_METHOD * 93.Fn TLS_server_method void 94.Ft const SSL_METHOD * 95.Fn TLS_client_method void 96.Ft const SSL_METHOD * 97.Fn SSLv23_method void 98.Ft const SSL_METHOD * 99.Fn SSLv23_server_method void 100.Ft const SSL_METHOD * 101.Fn SSLv23_client_method void 102.Ft const SSL_METHOD * 103.Fn TLSv1_method void 104.Ft const SSL_METHOD * 105.Fn TLSv1_server_method void 106.Ft const SSL_METHOD * 107.Fn TLSv1_client_method void 108.Ft const SSL_METHOD * 109.Fn TLSv1_1_method void 110.Ft const SSL_METHOD * 111.Fn TLSv1_1_server_method void 112.Ft const SSL_METHOD * 113.Fn TLSv1_1_client_method void 114.Ft const SSL_METHOD * 115.Fn TLSv1_2_method void 116.Ft const SSL_METHOD * 117.Fn TLSv1_2_server_method void 118.Ft const SSL_METHOD * 119.Fn TLSv1_2_client_method void 120.Ft const SSL_METHOD * 121.Fn DTLS_method void 122.Ft const SSL_METHOD * 123.Fn DTLS_server_method void 124.Ft const SSL_METHOD * 125.Fn DTLS_client_method void 126.Ft const SSL_METHOD * 127.Fn DTLSv1_method void 128.Ft const SSL_METHOD * 129.Fn DTLSv1_server_method void 130.Ft const SSL_METHOD * 131.Fn DTLSv1_client_method void 132.Ft const SSL_METHOD * 133.Fn DTLSv1_2_method void 134.Ft const SSL_METHOD * 135.Fn DTLSv1_2_server_method void 136.Ft const SSL_METHOD * 137.Fn DTLSv1_2_client_method void 138.Sh DESCRIPTION 139.Fn SSL_CTX_new 140creates a new 141.Vt SSL_CTX 142object as a framework to establish TLS or DTLS enabled connections. 143It initializes the list of ciphers, the session cache setting, the 144callbacks, the keys and certificates, and the options to its default 145values. 146.Pp 147An 148.Vt SSL_CTX 149object is reference counted. 150Creating a new 151.Vt SSL_CTX 152object sets its reference count to 1. 153Calling 154.Fn SSL_CTX_up_ref 155on it increments the reference count by 1. 156Calling 157.Xr SSL_CTX_free 3 158on it decrements the reference count by 1. 159When the reference count drops to zero, 160any memory or resources allocated to the 161.Vt SSL_CTX 162object are freed. 163.Pp 164The 165.Vt SSL_CTX 166object uses 167.Fa method 168as its connection method, which can be: 169.Bl -tag -width Ds 170.It Fn TLS_method 171The general-purpose version-flexible TLS method. 172The protocol version used will be negotiated to the highest 173version mutually supported by the client and the server. 174The supported protocols are TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3. 175.It Fn DTLS_method 176The version-flexible DTLS method. 177The currently supported protocols are DTLSv1 and DTLSv1.2. 178.El 179.Pp 180The following 181.Fa method 182arguments are deprecated: 183.Bl -tag -width Ds 184.It Xo 185.Fn TLS_server_method , 186.Fn TLS_client_method , 187.Fn SSLv23_method , 188.Fn SSLv23_server_method , 189.Fn SSLv23_client_method 190.Xc 191Deprecated aliases for 192.Fn TLS_method . 193.It Xo 194.Fn DTLS_server_method , 195.Fn DTLS_client_method 196.Xc 197Deprecated aliases for 198.Fn DTLS_method . 199.It Xo 200.Fn TLSv1_method , 201.Fn TLSv1_server_method , 202.Fn TLSv1_client_method 203.Xc 204A connection established with these methods will only 205understand the TLSv1 protocol. 206.It Xo 207.Fn TLSv1_1_method , 208.Fn TLSv1_1_server_method , 209.Fn TLSv1_1_client_method 210.Xc 211A connection established with these methods will only 212understand the TLSv1.1 protocol. 213.It Xo 214.Fn TLSv1_2_method , 215.Fn TLSv1_2_server_method , 216.Fn TLSv1_2_client_method 217.Xc 218A connection established with these methods will only 219understand the TLSv1.2 protocol. 220.It Xo 221.Fn DTLSv1_method , 222.Fn DTLSv1_server_method , 223.Fn DTLSv1_client_method 224.Xc 225These are the version-specific methods for DTLSv1. 226.It Xo 227.Fn DTLSv1_2_method , 228.Fn DTLSv1_2_server_method , 229.Fn DTLSv1_2_client_method 230These are the version-specific methods for DTLSv1.2. 231.Xc 232.El 233.Pp 234In LibreSSL, the methods containing the substrings 235.Dq _server 236or 237.Dq _client 238in their names return the same objects 239as the methods without these substrings. 240.Pp 241The list of protocols available can also be limited using the 242.Dv SSL_OP_NO_TLSv1 , 243.Dv SSL_OP_NO_TLSv1_1 , 244and 245.Dv SSL_OP_NO_TLSv1_2 246options of the 247.Xr SSL_CTX_set_options 3 248or 249.Xr SSL_set_options 3 250functions, but this approach is not recommended. 251Clients should avoid creating "holes" in the set of protocols they support. 252When disabling a protocol, make sure that you also disable either 253all previous or all subsequent protocol versions. 254In clients, when a protocol version is disabled without disabling 255all previous protocol versions, the effect is to also disable all 256subsequent protocol versions. 257.Pp 258DTLSv1 and DTLSv1.2 can be disabled with 259.Xr SSL_CTX_set_options 3 260or 261.Xr SSL_set_options 3 262using the 263.Dv SSL_OP_NO_DTLSv1 264and 265.Dv SSL_OP_NO_DTLSv1_2 266options, respectively. 267.Sh RETURN VALUES 268.Fn SSL_CTX_new 269returns a pointer to the newly allocated object or 270.Dv NULL 271on failure. 272Check the error stack to find out the reason for failure. 273.Pp 274.Fn SSL_CTX_up_ref 275returns 1 for success or 0 for failure. 276.Pp 277.Fn TLS_method 278and the other 279.Fn *_method 280functions return pointers to constant static objects. 281.Sh SEE ALSO 282.Xr ssl 3 , 283.Xr SSL_accept 3 , 284.Xr SSL_CTX_free 3 , 285.Xr SSL_CTX_set_min_proto_version 3 , 286.Xr SSL_CTX_set_options 3 , 287.Xr SSL_set_connect_state 3 288.Sh HISTORY 289.Fn SSL_CTX_new 290first appeared in SSLeay 0.5.1. 291.Fn SSLv23_method , 292.Fn SSLv23_server_method , 293and 294.Fn SSLv23_client_method 295first appeared in SSLeay 0.8.0. 296.Fn TLSv1_method , 297.Fn TLSv1_server_method , 298and 299.Fn TLSv1_client_method 300first appeared in SSLeay 0.9.0. 301All these functions have been available since 302.Ox 2.4 . 303.Pp 304.Fn DTLSv1_method , 305.Fn DTLSv1_server_method , 306and 307.Fn DTLSv1_client_method 308first appeared in OpenSSL 0.9.8 and have been available since 309.Ox 4.5 . 310.Pp 311.Fn TLSv1_1_method , 312.Fn TLSv1_1_server_method , 313.Fn TLSv1_1_client_method , 314.Fn TLSv1_2_method , 315.Fn TLSv1_2_server_method , 316and 317.Fn TLSv1_2_client_method 318first appeared in OpenSSL 1.0.1 and have been available since 319.Ox 5.3 . 320.Pp 321.Fn DTLS_method , 322.Fn DTLS_server_method , 323and 324.Fn DTLS_client_method 325first appeared in OpenSSL 1.0.2 and have been available since 326.Ox 6.5 . 327.Pp 328.Fn TLS_method , 329.Fn TLS_server_method , 330and 331.Fn TLS_client_method 332first appeared in OpenSSL 1.1.0 and have been available since 333.Ox 5.8 . 334.Pp 335.Fn SSL_CTX_up_ref 336first appeared in OpenSSL 1.1.0 and has been available since 337.Ox 6.3 . 338.Pp 339.Fn DTLSv1_2_method , 340.Fn DTLSv1_2_server_method , 341and 342.Fn DTLSv1_2_client_method 343first appeared in OpenSSL 1.1.0 and have been available since 344.Ox 6.9 . 345