xref: /openssl/doc/man3/SSL_CTX_new.pod (revision da1c088f)
1=pod
2
3=head1 NAME
4
5TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method,
6SSL_CTX_new, SSL_CTX_new_ex, SSL_CTX_up_ref, SSLv3_method,
7SSLv3_server_method, SSLv3_client_method, TLSv1_method, TLSv1_server_method,
8TLSv1_client_method, TLSv1_1_method, TLSv1_1_server_method,
9TLSv1_1_client_method, TLS_method, TLS_server_method, TLS_client_method,
10SSLv23_method, SSLv23_server_method, SSLv23_client_method, DTLS_method,
11DTLS_server_method, DTLS_client_method, DTLSv1_method, DTLSv1_server_method,
12DTLSv1_client_method, DTLSv1_2_method, DTLSv1_2_server_method,
13DTLSv1_2_client_method
14- create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled
15functions
16
17=head1 SYNOPSIS
18
19 #include <openssl/ssl.h>
20
21 SSL_CTX *SSL_CTX_new_ex(OSSL_LIB_CTX *libctx, const char *propq,
22                         const SSL_METHOD *method);
23 SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
24 int SSL_CTX_up_ref(SSL_CTX *ctx);
25
26 const SSL_METHOD *TLS_method(void);
27 const SSL_METHOD *TLS_server_method(void);
28 const SSL_METHOD *TLS_client_method(void);
29
30 const SSL_METHOD *SSLv23_method(void);
31 const SSL_METHOD *SSLv23_server_method(void);
32 const SSL_METHOD *SSLv23_client_method(void);
33
34 #ifndef OPENSSL_NO_SSL3_METHOD
35 const SSL_METHOD *SSLv3_method(void);
36 const SSL_METHOD *SSLv3_server_method(void);
37 const SSL_METHOD *SSLv3_client_method(void);
38 #endif
39
40 #ifndef OPENSSL_NO_TLS1_METHOD
41 const SSL_METHOD *TLSv1_method(void);
42 const SSL_METHOD *TLSv1_server_method(void);
43 const SSL_METHOD *TLSv1_client_method(void);
44 #endif
45
46 #ifndef OPENSSL_NO_TLS1_1_METHOD
47 const SSL_METHOD *TLSv1_1_method(void);
48 const SSL_METHOD *TLSv1_1_server_method(void);
49 const SSL_METHOD *TLSv1_1_client_method(void);
50 #endif
51
52 #ifndef OPENSSL_NO_TLS1_2_METHOD
53 const SSL_METHOD *TLSv1_2_method(void);
54 const SSL_METHOD *TLSv1_2_server_method(void);
55 const SSL_METHOD *TLSv1_2_client_method(void);
56 #endif
57
58 const SSL_METHOD *DTLS_method(void);
59 const SSL_METHOD *DTLS_server_method(void);
60 const SSL_METHOD *DTLS_client_method(void);
61
62 #ifndef OPENSSL_NO_DTLS1_METHOD
63 const SSL_METHOD *DTLSv1_method(void);
64 const SSL_METHOD *DTLSv1_server_method(void);
65 const SSL_METHOD *DTLSv1_client_method(void);
66 #endif
67
68 #ifndef OPENSSL_NO_DTLS1_2_METHOD
69 const SSL_METHOD *DTLSv1_2_method(void);
70 const SSL_METHOD *DTLSv1_2_server_method(void);
71 const SSL_METHOD *DTLSv1_2_client_method(void);
72 #endif
73
74=head1 DESCRIPTION
75
76SSL_CTX_new_ex() creates a new B<SSL_CTX> object, which holds various
77configuration and data relevant to SSL/TLS or DTLS session establishment.
78These are later inherited by the B<SSL> object representing an active session.
79The I<method> parameter specifies whether the context will be used for the
80client or server side or both - for details see the L</NOTES> below.
81The library context I<libctx> (see L<OSSL_LIB_CTX(3)>) is used to provide the
82cryptographic algorithms needed for the session. Any cryptographic algorithms
83that are used by any B<SSL> objects created from this B<SSL_CTX> will be fetched
84from the I<libctx> using the property query string I<propq> (see
85L<crypto(7)/ALGORITHM FETCHING>. Either or both the I<libctx> or I<propq>
86parameters may be NULL.
87
88SSL_CTX_new() does the same as SSL_CTX_new_ex() except that the default
89library context is used and no property query string is specified.
90
91An B<SSL_CTX> object is reference counted. Creating an B<SSL_CTX> object for the
92first time increments the reference count. Freeing the B<SSL_CTX> (using
93SSL_CTX_free) decrements it. When the reference count drops to zero, any memory
94or resources allocated to the B<SSL_CTX> object are freed. SSL_CTX_up_ref()
95increments the reference count for an existing B<SSL_CTX> structure.
96
97An B<SSL_CTX> object should not be changed after it is used to create any B<SSL>
98objects or from multiple threads concurrently, since the implementation does not
99provide serialization of access for these cases.
100
101=head1 NOTES
102
103On session establishment, by default, no peer credentials verification is done.
104This must be explicitly requested, typically using L<SSL_CTX_set_verify(3)>.
105For verifying peer certificates many options can be set using various functions
106such as L<SSL_CTX_load_verify_locations(3)> and L<SSL_CTX_set1_param(3)>.
107The L<X509_VERIFY_PARAM_set_purpose(3)> function can be used, also in conjunction
108with L<SSL_CTX_get0_param(3)>, to set the intended purpose of the session.
109The default is B<X509_PURPOSE_SSL_SERVER> on the client side
110and B<X509_PURPOSE_SSL_CLIENT> on the server side.
111
112The SSL_CTX object uses I<method> as the connection method.
113Three method variants are available: a generic method (for either client or
114server use), a server-only method, and a client-only method.
115
116The I<method> parameter of SSL_CTX_new_ex() and SSL_CTX_new()
117can be one of the following:
118
119=over 4
120
121=item TLS_method(), TLS_server_method(), TLS_client_method()
122
123These are the general-purpose I<version-flexible> SSL/TLS methods.
124The actual protocol version used will be negotiated to the highest version
125mutually supported by the client and the server.
126The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3.
127Applications should use these methods, and avoid the version-specific
128methods described below, which are deprecated.
129
130=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()
131
132These functions do not exist anymore, they have been renamed to
133TLS_method(), TLS_server_method() and TLS_client_method() respectively.
134Currently, the old function calls are renamed to the corresponding new
135ones by preprocessor macros, to ensure that existing code which uses the
136old function names still compiles. However, using the old function names
137is deprecated and new code should call the new functions instead.
138
139=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()
140
141A TLS/SSL connection established with these methods will only understand the
142TLSv1.2 protocol. These methods are deprecated.
143
144=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()
145
146A TLS/SSL connection established with these methods will only understand the
147TLSv1.1 protocol.  These methods are deprecated.
148
149=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()
150
151A TLS/SSL connection established with these methods will only understand the
152TLSv1 protocol. These methods are deprecated.
153
154=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()
155
156A TLS/SSL connection established with these methods will only understand the
157SSLv3 protocol.
158The SSLv3 protocol is deprecated and should not be used.
159
160=item DTLS_method(), DTLS_server_method(), DTLS_client_method()
161
162These are the version-flexible DTLS methods.
163Currently supported protocols are DTLS 1.0 and DTLS 1.2.
164
165=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()
166
167These are the version-specific methods for DTLSv1.2.
168These methods are deprecated.
169
170=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()
171
172These are the version-specific methods for DTLSv1.
173These methods are deprecated.
174
175=back
176
177SSL_CTX_new() initializes the list of ciphers, the session cache setting, the
178callbacks, the keys and certificates and the options to their default values.
179
180TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(),
181DTLS_server_method() and DTLS_client_method() are the I<version-flexible>
182methods.
183All other methods only support one specific protocol version.
184Use the I<version-flexible> methods instead of the version specific methods.
185
186If you want to limit the supported protocols for the version flexible
187methods you can use L<SSL_CTX_set_min_proto_version(3)>,
188L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and
189L<SSL_set_max_proto_version(3)> functions.
190Using these functions it is possible to choose e.g. TLS_server_method()
191and be able to negotiate with all possible clients, but to only
192allow newer protocols like TLS 1.0, TLS 1.1, TLS 1.2 or TLS 1.3.
193
194The list of protocols available can also be limited using the
195B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1>,
196B<SSL_OP_NO_TLSv1_3>, B<SSL_OP_NO_TLSv1_2> and B<SSL_OP_NO_TLSv1_3>
197options of the
198L<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions, but this approach
199is not recommended. Clients should avoid creating "holes" in the set of
200protocols they support. When disabling a protocol, make sure that you also
201disable either all previous or all subsequent protocol versions.
202In clients, when a protocol version is disabled without disabling I<all>
203previous protocol versions, the effect is to also disable all subsequent
204protocol versions.
205
206The SSLv3 protocol is deprecated and should generally not be used.
207Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set
208the minimum protocol to at least B<TLS1_VERSION>.
209
210=head1 RETURN VALUES
211
212The following return values can occur:
213
214=over 4
215
216=item NULL
217
218The creation of a new SSL_CTX object failed. Check the error stack to find out
219the reason.
220
221=item Pointer to an SSL_CTX object
222
223The return value points to an allocated SSL_CTX object.
224
225SSL_CTX_up_ref() returns 1 for success and 0 for failure.
226
227=back
228
229=head1 SEE ALSO
230
231L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>,
232SSL_CTX_set_verify(3), L<SSL_CTX_set1_param(3)>, L<SSL_CTX_get0_param(3)>,
233L<SSL_connect(3)>, L<SSL_accept(3)>,
234L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)>
235
236=head1 HISTORY
237
238Support for SSLv2 and the corresponding SSLv2_method(),
239SSLv2_server_method() and SSLv2_client_method() functions where
240removed in OpenSSL 1.1.0.
241
242SSLv23_method(), SSLv23_server_method() and SSLv23_client_method()
243were deprecated and the preferred TLS_method(), TLS_server_method()
244and TLS_client_method() functions were added in OpenSSL 1.1.0.
245
246All version-specific methods were deprecated in OpenSSL 1.1.0.
247
248SSL_CTX_new_ex() was added in OpenSSL 3.0.
249
250=head1 COPYRIGHT
251
252Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
253
254Licensed under the Apache License 2.0 (the "License").  You may not use
255this file except in compliance with the License.  You can obtain a copy
256in the file LICENSE in the source distribution or at
257L<https://www.openssl.org/source/license.html>.
258
259=cut
260