Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_new.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_NEW 3SSL"
58 .TH SSL_CTX_NEW 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method,
65 SSL_CTX_new, SSL_CTX_new_ex, SSL_CTX_up_ref, SSLv3_method,
66 SSLv3_server_method, SSLv3_client_method, TLSv1_method, TLSv1_server_method,
67 TLSv1_client_method, TLSv1_1_method, TLSv1_1_server_method,
68 TLSv1_1_client_method, TLS_method, TLS_server_method, TLS_client_method,
69 SSLv23_method, SSLv23_server_method, SSLv23_client_method, DTLS_method,
70 DTLS_server_method, DTLS_client_method, DTLSv1_method, DTLSv1_server_method,
71 DTLSv1_client_method, DTLSv1_2_method, DTLSv1_2_server_method,
72 DTLSv1_2_client_method
73 \&\- create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled
74 functions
75 .SH SYNOPSIS
76 .IX Header "SYNOPSIS"
77 .Vb 1
78 \& #include <openssl/ssl.h>
79 \&
80 \& SSL_CTX *SSL_CTX_new_ex(OSSL_LIB_CTX *libctx, const char *propq,
81 \& const SSL_METHOD *method);
82 \& SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
83 \& int SSL_CTX_up_ref(SSL_CTX *ctx);
84 \&
85 \& const SSL_METHOD *TLS_method(void);
86 \& const SSL_METHOD *TLS_server_method(void);
87 \& const SSL_METHOD *TLS_client_method(void);
88 \&
89 \& const SSL_METHOD *SSLv23_method(void);
90 \& const SSL_METHOD *SSLv23_server_method(void);
91 \& const SSL_METHOD *SSLv23_client_method(void);
92 \&
93 \& #ifndef OPENSSL_NO_SSL3_METHOD
94 \& const SSL_METHOD *SSLv3_method(void);
95 \& const SSL_METHOD *SSLv3_server_method(void);
96 \& const SSL_METHOD *SSLv3_client_method(void);
97 \& #endif
98 \&
99 \& #ifndef OPENSSL_NO_TLS1_METHOD
100 \& const SSL_METHOD *TLSv1_method(void);
101 \& const SSL_METHOD *TLSv1_server_method(void);
102 \& const SSL_METHOD *TLSv1_client_method(void);
103 \& #endif
104 \&
105 \& #ifndef OPENSSL_NO_TLS1_1_METHOD
106 \& const SSL_METHOD *TLSv1_1_method(void);
107 \& const SSL_METHOD *TLSv1_1_server_method(void);
108 \& const SSL_METHOD *TLSv1_1_client_method(void);
109 \& #endif
110 \&
111 \& #ifndef OPENSSL_NO_TLS1_2_METHOD
112 \& const SSL_METHOD *TLSv1_2_method(void);
113 \& const SSL_METHOD *TLSv1_2_server_method(void);
114 \& const SSL_METHOD *TLSv1_2_client_method(void);
115 \& #endif
116 \&
117 \& const SSL_METHOD *DTLS_method(void);
118 \& const SSL_METHOD *DTLS_server_method(void);
119 \& const SSL_METHOD *DTLS_client_method(void);
120 \&
121 \& #ifndef OPENSSL_NO_DTLS1_METHOD
122 \& const SSL_METHOD *DTLSv1_method(void);
123 \& const SSL_METHOD *DTLSv1_server_method(void);
124 \& const SSL_METHOD *DTLSv1_client_method(void);
125 \& #endif
126 \&
127 \& #ifndef OPENSSL_NO_DTLS1_2_METHOD
128 \& const SSL_METHOD *DTLSv1_2_method(void);
129 \& const SSL_METHOD *DTLSv1_2_server_method(void);
130 \& const SSL_METHOD *DTLSv1_2_client_method(void);
131 \& #endif
132 .Ve
133 .SH DESCRIPTION
134 .IX Header "DESCRIPTION"
135 \&\fBSSL_CTX_new_ex()\fR creates a new \fBSSL_CTX\fR object, which holds various
136 configuration and data relevant to SSL/TLS or DTLS session establishment.
137 These are later inherited by the \fBSSL\fR object representing an active session.
138 The \fImethod\fR parameter specifies whether the context will be used for the
139 client or server side or both \- for details see the "NOTES" below.
140 The library context \fIlibctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)) is used to provide the
141 cryptographic algorithms needed for the session. Any cryptographic algorithms
142 that are used by any \fBSSL\fR objects created from this \fBSSL_CTX\fR will be fetched
143 from the \fIlibctx\fR using the property query string \fIpropq\fR (see
144 "ALGORITHM FETCHING" in \fBcrypto\fR\|(7). Either or both the \fIlibctx\fR or \fIpropq\fR
145 parameters may be NULL.
146 .PP
147 \&\fBSSL_CTX_new()\fR does the same as \fBSSL_CTX_new_ex()\fR except that the default
148 library context is used and no property query string is specified.
149 .PP
150 An \fBSSL_CTX\fR object is reference counted. Creating an \fBSSL_CTX\fR object for the
151 first time increments the reference count. Freeing the \fBSSL_CTX\fR (using
152 SSL_CTX_free) decrements it. When the reference count drops to zero, any memory
153 or resources allocated to the \fBSSL_CTX\fR object are freed. \fBSSL_CTX_up_ref()\fR
154 increments the reference count for an existing \fBSSL_CTX\fR structure.
155 .PP
156 An \fBSSL_CTX\fR object should not be changed after it is used to create any \fBSSL\fR
157 objects or from multiple threads concurrently, since the implementation does not
158 provide serialization of access for these cases.
159 .SH NOTES
160 .IX Header "NOTES"
161 On session establishment, by default, no peer credentials verification is done.
162 This must be explicitly requested, typically using \fBSSL_CTX_set_verify\fR\|(3).
163 For verifying peer certificates many options can be set using various functions
164 such as \fBSSL_CTX_load_verify_locations\fR\|(3) and \fBSSL_CTX_set1_param\fR\|(3).
165 .PP
166 The SSL/(D)TLS implementation uses the \fBX509_STORE_CTX_set_default\fR\|(3)
167 function to prepare checks for \fBX509_PURPOSE_SSL_SERVER\fR on the client side
168 and \fBX509_PURPOSE_SSL_CLIENT\fR on the server side.
169 The \fBX509_VERIFY_PARAM_set_purpose\fR\|(3) function can be used, also in conjunction
170 with \fBSSL_CTX_get0_param\fR\|(3), to override the default purpose of the session.
171 .PP
172 The SSL_CTX object uses \fImethod\fR as the connection method.
173 Three method variants are available: a generic method (for either client or
174 server use), a server-only method, and a client-only method.
175 .PP
176 The \fImethod\fR parameter of \fBSSL_CTX_new_ex()\fR and \fBSSL_CTX_new()\fR
177 can be one of the following:
178 .IP "\fBTLS_method()\fR, \fBTLS_server_method()\fR, \fBTLS_client_method()\fR" 4
179 .IX Item "TLS_method(), TLS_server_method(), TLS_client_method()"
180 These are the general-purpose \fIversion-flexible\fR SSL/TLS methods.
181 The actual protocol version used will be negotiated to the highest version
182 mutually supported by the client and the server.
183 The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3.
184 Applications should use these methods, and avoid the version-specific
185 methods described below, which are deprecated.
186 .IP "\fBSSLv23_method()\fR, \fBSSLv23_server_method()\fR, \fBSSLv23_client_method()\fR" 4
187 .IX Item "SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()"
188 These functions do not exist anymore, they have been renamed to
189 \&\fBTLS_method()\fR, \fBTLS_server_method()\fR and \fBTLS_client_method()\fR respectively.
190 Currently, the old function calls are renamed to the corresponding new
191 ones by preprocessor macros, to ensure that existing code which uses the
192 old function names still compiles. However, using the old function names
193 is deprecated and new code should call the new functions instead.
194 .IP "\fBTLSv1_2_method()\fR, \fBTLSv1_2_server_method()\fR, \fBTLSv1_2_client_method()\fR" 4
195 .IX Item "TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()"
196 A TLS/SSL connection established with these methods will only understand the
197 TLSv1.2 protocol. These methods are deprecated.
198 .IP "\fBTLSv1_1_method()\fR, \fBTLSv1_1_server_method()\fR, \fBTLSv1_1_client_method()\fR" 4
199 .IX Item "TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()"
200 A TLS/SSL connection established with these methods will only understand the
201 TLSv1.1 protocol. These methods are deprecated.
202 .IP "\fBTLSv1_method()\fR, \fBTLSv1_server_method()\fR, \fBTLSv1_client_method()\fR" 4
203 .IX Item "TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()"
204 A TLS/SSL connection established with these methods will only understand the
205 TLSv1 protocol. These methods are deprecated.
206 .IP "\fBSSLv3_method()\fR, \fBSSLv3_server_method()\fR, \fBSSLv3_client_method()\fR" 4
207 .IX Item "SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()"
208 A TLS/SSL connection established with these methods will only understand the
209 SSLv3 protocol.
210 The SSLv3 protocol is deprecated and should not be used.
211 .IP "\fBDTLS_method()\fR, \fBDTLS_server_method()\fR, \fBDTLS_client_method()\fR" 4
212 .IX Item "DTLS_method(), DTLS_server_method(), DTLS_client_method()"
213 These are the version-flexible DTLS methods.
214 Currently supported protocols are DTLS 1.0 and DTLS 1.2.
215 .IP "\fBDTLSv1_2_method()\fR, \fBDTLSv1_2_server_method()\fR, \fBDTLSv1_2_client_method()\fR" 4
216 .IX Item "DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()"
217 These are the version-specific methods for DTLSv1.2.
218 These methods are deprecated.
219 .IP "\fBDTLSv1_method()\fR, \fBDTLSv1_server_method()\fR, \fBDTLSv1_client_method()\fR" 4
220 .IX Item "DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()"
221 These are the version-specific methods for DTLSv1.
222 These methods are deprecated.
223 .PP
224 \&\fBSSL_CTX_new()\fR initializes the list of ciphers, the session cache setting, the
225 callbacks, the keys and certificates and the options to their default values.
226 .PP
227 \&\fBTLS_method()\fR, \fBTLS_server_method()\fR, \fBTLS_client_method()\fR, \fBDTLS_method()\fR,
228 \&\fBDTLS_server_method()\fR and \fBDTLS_client_method()\fR are the \fIversion-flexible\fR
229 methods.
230 All other methods only support one specific protocol version.
231 Use the \fIversion-flexible\fR methods instead of the version specific methods.
232 .PP
233 If you want to limit the supported protocols for the version flexible
234 methods you can use \fBSSL_CTX_set_min_proto_version\fR\|(3),
235 \&\fBSSL_set_min_proto_version\fR\|(3), \fBSSL_CTX_set_max_proto_version\fR\|(3) and
236 \&\fBSSL_set_max_proto_version\fR\|(3) functions.
237 Using these functions it is possible to choose e.g. \fBTLS_server_method()\fR
238 and be able to negotiate with all possible clients, but to only
239 allow newer protocols like TLS 1.0, TLS 1.1, TLS 1.2 or TLS 1.3.
240 .PP
241 The list of protocols available can also be limited using the
242 \&\fBSSL_OP_NO_SSLv3\fR, \fBSSL_OP_NO_TLSv1\fR, \fBSSL_OP_NO_TLSv1_1\fR,
243 \&\fBSSL_OP_NO_TLSv1_3\fR, \fBSSL_OP_NO_TLSv1_2\fR and \fBSSL_OP_NO_TLSv1_3\fR
244 options of the
245 \&\fBSSL_CTX_set_options\fR\|(3) or \fBSSL_set_options\fR\|(3) functions, but this approach
246 is not recommended. Clients should avoid creating "holes" in the set of
247 protocols they support. When disabling a protocol, make sure that you also
248 disable either all previous or all subsequent protocol versions.
249 In clients, when a protocol version is disabled without disabling \fIall\fR
250 previous protocol versions, the effect is to also disable all subsequent
251 protocol versions.
252 .PP
253 The SSLv3 protocol is deprecated and should generally not be used.
254 Applications should typically use \fBSSL_CTX_set_min_proto_version\fR\|(3) to set
255 the minimum protocol to at least \fBTLS1_VERSION\fR.
256 .SH "RETURN VALUES"
257 .IX Header "RETURN VALUES"
258 The following return values can occur:
259 .IP NULL 4
260 .IX Item "NULL"
261 The creation of a new SSL_CTX object failed. Check the error stack to find out
262 the reason.
263 .IP "Pointer to an SSL_CTX object" 4
264 .IX Item "Pointer to an SSL_CTX object"
265 The return value points to an allocated SSL_CTX object.
266 .Sp
267 \&\fBSSL_CTX_up_ref()\fR returns 1 for success and 0 for failure.
268 .SH "SEE ALSO"
269 .IX Header "SEE ALSO"
270 \&\fBSSL_CTX_set_options\fR\|(3), \fBSSL_CTX_free\fR\|(3), \fBX509_STORE_CTX_set_default\fR\|(3),
271 \&\fBSSL_CTX_set_verify\fR\|(3), \fBSSL_CTX_set1_param\fR\|(3), \fBSSL_CTX_get0_param\fR\|(3),
272 \&\fBSSL_connect\fR\|(3), \fBSSL_accept\fR\|(3),
273 \&\fBSSL_CTX_set_min_proto_version\fR\|(3), \fBssl\fR\|(7), \fBSSL_set_connect_state\fR\|(3)
274 .SH HISTORY
275 .IX Header "HISTORY"
276 Support for SSLv2 and the corresponding \fBSSLv2_method()\fR,
277 \&\fBSSLv2_server_method()\fR and \fBSSLv2_client_method()\fR functions where
278 removed in OpenSSL 1.1.0.
279 .PP
280 \&\fBSSLv23_method()\fR, \fBSSLv23_server_method()\fR and \fBSSLv23_client_method()\fR
281 were deprecated and the preferred \fBTLS_method()\fR, \fBTLS_server_method()\fR
282 and \fBTLS_client_method()\fR functions were added in OpenSSL 1.1.0.
283 .PP
284 All version-specific methods were deprecated in OpenSSL 1.1.0.
285 .PP
286 \&\fBSSL_CTX_new_ex()\fR was added in OpenSSL 3.0.
287 .SH COPYRIGHT
288 .IX Header "COPYRIGHT"
289 Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
290 .PP
291 Licensed under the Apache License 2.0 (the "License"). You may not use
292 this file except in compliance with the License. You can obtain a copy
293 in the file LICENSE in the source distribution or at
294 <https://www.openssl.org/source/license.html>.