1.\" $OpenBSD: SSL_CTX_new.3,v 1.10 2018/03/27 17:35:50 schwarze Exp $ 2.\" full merge up to: OpenSSL 21cd6e00 Oct 21 14:40:15 2015 +0100 3.\" selective merge up to: OpenSSL eb43101f Dec 9 18:07:09 2016 +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 27 2018 $ 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 DTLSv1_method , 75.Nm DTLSv1_server_method , 76.Nm DTLSv1_client_method 77.Nd create a new SSL_CTX object as framework for TLS/SSL enabled functions 78.Sh SYNOPSIS 79.In openssl/ssl.h 80.Ft SSL_CTX * 81.Fn SSL_CTX_new "const SSL_METHOD *method" 82.Ft int 83.Fn SSL_CTX_up_ref "SSL_CTX *ctx" 84.Ft const SSL_METHOD * 85.Fn TLS_method void 86.Ft const SSL_METHOD * 87.Fn TLS_server_method void 88.Ft const SSL_METHOD * 89.Fn TLS_client_method void 90.Ft const SSL_METHOD * 91.Fn SSLv23_method void 92.Ft const SSL_METHOD * 93.Fn SSLv23_server_method void 94.Ft const SSL_METHOD * 95.Fn SSLv23_client_method void 96.Ft const SSL_METHOD * 97.Fn TLSv1_method void 98.Ft const SSL_METHOD * 99.Fn TLSv1_server_method void 100.Ft const SSL_METHOD * 101.Fn TLSv1_client_method void 102.Ft const SSL_METHOD * 103.Fn TLSv1_1_method void 104.Ft const SSL_METHOD * 105.Fn TLSv1_1_server_method void 106.Ft const SSL_METHOD * 107.Fn TLSv1_1_client_method void 108.Ft const SSL_METHOD * 109.Fn TLSv1_2_method void 110.Ft const SSL_METHOD * 111.Fn TLSv1_2_server_method void 112.Ft const SSL_METHOD * 113.Fn TLSv1_2_client_method void 114.Ft const SSL_METHOD * 115.Fn DTLSv1_method void 116.Ft const SSL_METHOD * 117.Fn DTLSv1_server_method void 118.Ft const SSL_METHOD * 119.Fn DTLSv1_client_method void 120.Sh DESCRIPTION 121.Fn SSL_CTX_new 122creates a new 123.Vt SSL_CTX 124object as framework to establish TLS/SSL or DTLS enabled connections. 125It initializes the list of ciphers, the session cache setting, the 126callbacks, the keys and certificates, and the options to its default 127values. 128.Pp 129An 130.Vt SSL_CTX 131object is reference counted. 132Creating a new 133.Vt SSL_CTX 134object sets its reference count to 1. 135Calling 136.Fn SSL_CTX_up_ref 137on it increments the reference count by 1. 138Calling 139.Xr SSL_CTX_free 3 140on it decrements the reference count by 1. 141When the reference count drops to zero, 142any memory or resources allocated to the 143.Vt SSL_CTX 144object are freed. 145.Pp 146The 147.Vt SSL_CTX 148object uses 149.Fa method 150as its connection method. 151The methods exist in a generic type (for client and server use), 152a server only type, and a client only type. 153.Fa method 154can be of the following types: 155.Bl -tag -width Ds 156.It Xo 157.Fn TLS_method , 158.Fn TLS_server_method , 159.Fn TLS_client_method 160.Xc 161These are the general-purpose version-flexible SSL/TLS methods. 162The actual protocol version used will be negotiated to the highest 163version mutually supported by the client and the server. 164The supported protocols are TLSv1, TLSv1.1 and TLSv1.2. 165Applications should use these methods and avoid the version-specific 166methods described below. 167.It Xo 168.Fn SSLv23_method , 169.Fn SSLv23_server_method , 170.Fn SSLv23_client_method 171.Xc 172Use of these functions is deprecated. 173They have been replaced with the above 174.Fn TLS_method , 175.Fn TLS_server_method , 176and 177.Fn TLS_client_method , 178respectively. 179New code should use those functions instead. 180.It Xo 181.Fn TLSv1_method , 182.Fn TLSv1_server_method , 183.Fn TLSv1_client_method 184.Xc 185A TLS/SSL connection established with these methods will only 186understand the TLSv1 protocol. 187.It Xo 188.Fn TLSv1_1_method , 189.Fn TLSv1_1_server_method , 190.Fn TLSv1_1_client_method 191.Xc 192A TLS/SSL connection established with these methods will only 193understand the TLSv1.1 protocol. 194.It Xo 195.Fn TLSv1_2_method , 196.Fn TLSv1_2_server_method , 197.Fn TLSv1_2_client_method 198.Xc 199A TLS/SSL connection established with these methods will only 200understand the TLSv1.2 protocol. 201.It Xo 202.Fn DTLSv1_method , 203.Fn DTLSv1_server_method , 204.Fn DTLSv1_client_method 205.Xc 206These are the version-specific methods for DTLSv1. 207.El 208.Pp 209The list of protocols available can also be limited using the 210.Dv SSL_OP_NO_TLSv1 , 211.Dv SSL_OP_NO_TLSv1_1 , 212and 213.Dv SSL_OP_NO_TLSv1_2 214options of the 215.Xr SSL_CTX_set_options 3 216or 217.Xr SSL_set_options 3 218functions, but this approach is not recommended. 219Clients should avoid creating "holes" in the set of protocols they support. 220When disabling a protocol, make sure that you also disable either 221all previous or all subsequent protocol versions. 222In clients, when a protocol version is disabled without disabling 223all previous protocol versions, the effect is to also disable all 224subsequent protocol versions. 225.Sh RETURN VALUES 226.Fn SSL_CTX_new 227returns a pointer to the newly allocated object or 228.Dv NULL 229on failure. 230Check the error stack to find out the reason for failure. 231.Pp 232.Fn SSL_CTX_up_ref 233returns 1 for success or 0 for failure. 234.Sh SEE ALSO 235.Xr ssl 3 , 236.Xr SSL_accept 3 , 237.Xr SSL_CTX_free 3 , 238.Xr SSL_CTX_set_min_proto_version 3 , 239.Xr SSL_CTX_set_options 3 , 240.Xr SSL_set_connect_state 3 241.Sh HISTORY 242.Fn SSL_CTX_new 243first appeared in SSLeay 0.5.1. 244.Fn SSLv23_method , 245.Fn SSLv23_server_method , 246and 247.Fn SSLv23_client_method 248first appeared in SSLeay 0.8.0. 249.Fn TLSv1_method , 250.Fn TLSv1_server_method , 251and 252.Fn TLSv1_client_method 253first appeared in SSLeay 0.9.0. 254All these functions have been available since 255.Ox 2.4 . 256.Pp 257.Fn DTLSv1_method , 258.Fn DTLSv1_server_method , 259and 260.Fn DTLSv1_client_method 261first appeared in OpenSSL 0.9.8 and have been available since 262.Ox 4.5 . 263.Pp 264.Fn TLSv1_1_method , 265.Fn TLSv1_1_server_method , 266.Fn TLSv1_1_client_method , 267.Fn TLSv1_2_method , 268.Fn TLSv1_2_server_method , 269and 270.Fn TLSv1_2_client_method 271first appeared in OpenSSL 1.0.1 and have been available since 272.Ox 5.3 . 273.Pp 274.Fn TLS_method , 275.Fn TLS_server_method , 276and 277.Fn TLS_client_method 278first appeared in OpenSSL 1.1.0 and have been available since 279.Ox 5.8 . 280.Pp 281.Fn SSL_CTX_up_ref 282first appeared in OpenSSL 1.1.0 and has been available since 283.Ox 6.3 . 284