| blob | 78b64f063130a489379ce5b707c8ff82b68d5681 |
1 .\" $OpenBSD: SSL_CTX_new.3,v 1.9 2018/03/24 00:55:37 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 24 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
122 creates a new
123 .Vt SSL_CTX
124 object as framework to establish TLS/SSL or DTLS enabled connections.
125 It initializes the list of ciphers, the session cache setting, the
126 callbacks, the keys and certificates, and the options to its default
127 values.
128 .Pp
129 An
130 .Vt SSL_CTX
131 object is reference counted.
132 Creating a new
133 .Vt SSL_CTX
134 object sets its reference count to 1.
135 Calling
136 .Fn SSL_CTX_up_ref
137 on it increments the reference count by 1.
138 Calling
139 .Xr SSL_CTX_free 3
140 on it decrements the reference count by 1.
141 When the reference count drops to zero,
142 any memory or resources allocated to the
143 .Vt SSL_CTX
144 object are freed.
145 .Pp
146 The
147 .Vt SSL_CTX
148 object uses
149 .Fa method
150 as its connection method.
151 The methods exist in a generic type (for client and server use),
152 a server only type, and a client only type.
153 .Fa method
154 can 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
161 These are the general-purpose version-flexible SSL/TLS methods.
162 The actual protocol version used will be negotiated to the highest
163 version mutually supported by the client and the server.
164 The supported protocols are TLSv1, TLSv1.1 and TLSv1.2.
165 Applications should use these methods and avoid the version-specific
166 methods described below.
167 .It Xo
168 .Fn SSLv23_method ,
169 .Fn SSLv23_server_method ,
170 .Fn SSLv23_client_method
171 .Xc
172 Use of these functions is deprecated.
173 They have been replaced with the above
174 .Fn TLS_method ,
175 .Fn TLS_server_method ,
176 and
177 .Fn TLS_client_method ,
178 respectively.
179 New 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
185 A TLS/SSL connection established with these methods will only
186 understand 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
192 A TLS/SSL connection established with these methods will only
193 understand 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
199 A TLS/SSL connection established with these methods will only
200 understand the TLSv1.2 protocol.
201 .It Xo
202 .Fn DTLSv1_method ,
203 .Fn DTLSv1_server_method ,
204 .Fn DTLSv1_client_method
205 .Xc
206 These are the version-specific methods for DTLSv1.
207 .El
208 .Pp
209 The list of protocols available can also be limited using the
210 .Dv SSL_OP_NO_TLSv1 ,
211 .Dv SSL_OP_NO_TLSv1_1 ,
212 and
213 .Dv SSL_OP_NO_TLSv1_2
214 options of the
215 .Xr SSL_CTX_set_options 3
216 or
217 .Xr SSL_set_options 3
218 functions, but this approach is not recommended.
219 Clients should avoid creating "holes" in the set of protocols they support.
220 When disabling a protocol, make sure that you also disable either
221 all previous or all subsequent protocol versions.
222 In clients, when a protocol version is disabled without disabling
223 all previous protocol versions, the effect is to also disable all
224 subsequent protocol versions.
225 .Sh RETURN VALUES
226 .Fn SSL_CTX_new
227 returns a pointer to the newly allocated object or
228 .Dv NULL
229 on failure.
230 Check the error stack to find out the reason for failure.
231 .Pp
232 .Fn SSL_CTX_up_ref
233 returns 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 ,
243 .Fn SSLv23_method ,
244 .Fn SSLv23_server_method ,
245 and
246 .Fn SSLv23_client_method
247 appeared before SSLeay 0.8.
248 .Fn TLSv1_method ,
249 .Fn TLSv1_server_method ,
250 and
251 .Fn TLSv1_client_method
252 first appeared in SSLeay 0.9.0.
253 All these functions have been available since
254 .Ox 2.4 .
255 .Pp
256 .Fn DTLSv1_method ,
257 .Fn DTLSv1_server_method ,
258 and
259 .Fn DTLSv1_client_method
260 first appeared in OpenSSL 0.9.8 and have been available since
261 .Ox 4.5 .
262 .Pp
263 .Fn TLSv1_1_method ,
264 .Fn TLSv1_1_server_method ,
265 .Fn TLSv1_1_client_method ,
266 .Fn TLSv1_2_method ,
267 .Fn TLSv1_2_server_method ,
268 and
269 .Fn TLSv1_2_client_method
270 first appeared in OpenSSL 1.0.1 and have been available since
271 .Ox 5.3 .
272 .Pp
273 .Fn TLS_method ,
274 .Fn TLS_server_method ,
275 and
276 .Fn TLS_client_method
277 first appeared in OpenSSL 1.1.0 and have been available since
278 .Ox 5.8 .
279 .Pp
280 .Fn SSL_CTX_up_ref
281 first appeared in OpenSSL 1.1.0 and has been available since
282 .Ox 6.3 .