5 TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method,
6 SSL_CTX_new, SSL_CTX_new_ex, SSL_CTX_up_ref, SSLv3_method,
7 SSLv3_server_method, SSLv3_client_method, TLSv1_method, TLSv1_server_method,
8 TLSv1_client_method, TLSv1_1_method, TLSv1_1_server_method,
9 TLSv1_1_client_method, TLS_method, TLS_server_method, TLS_client_method,
10 SSLv23_method, SSLv23_server_method, SSLv23_client_method, DTLS_method,
11 DTLS_server_method, DTLS_client_method, DTLSv1_method, DTLSv1_server_method,
12 DTLSv1_client_method, DTLSv1_2_method, DTLSv1_2_server_method,
13 DTLSv1_2_client_method
14 - create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled
19 #include <openssl/ssl.h>
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);
26 const SSL_METHOD *TLS_method(void);
27 const SSL_METHOD *TLS_server_method(void);
28 const SSL_METHOD *TLS_client_method(void);
30 const SSL_METHOD *SSLv23_method(void);
31 const SSL_METHOD *SSLv23_server_method(void);
32 const SSL_METHOD *SSLv23_client_method(void);
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);
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);
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);
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);
58 const SSL_METHOD *DTLS_method(void);
59 const SSL_METHOD *DTLS_server_method(void);
60 const SSL_METHOD *DTLS_client_method(void);
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);
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);
76 SSL_CTX_new_ex() creates a new B<SSL_CTX> object, which holds various
77 configuration and data relevant to SSL/TLS or DTLS session establishment.
78 These are later inherited by the B<SSL> object representing an active session.
79 The I<method> parameter specifies whether the context will be used for the
80 client or server side or both - for details see the L</NOTES> below.
81 The library context I<libctx> (see L<OSSL_LIB_CTX(3)>) is used to provide the
82 cryptographic algorithms needed for the session. Any cryptographic algorithms
83 that are used by any B<SSL> objects created from this B<SSL_CTX> will be fetched
84 from the I<libctx> using the property query string I<propq> (see
85 L<crypto(7)/ALGORITHM FETCHING>. Either or both the I<libctx> or I<propq>
86 parameters may be NULL.
88 SSL_CTX_new() does the same as SSL_CTX_new_ex() except that the default
89 library context is used and no property query string is specified.
91 An B<SSL_CTX> object is reference counted. Creating an B<SSL_CTX> object for the
92 first time increments the reference count. Freeing the B<SSL_CTX> (using
93 SSL_CTX_free) decrements it. When the reference count drops to zero, any memory
94 or resources allocated to the B<SSL_CTX> object are freed. SSL_CTX_up_ref()
95 increments the reference count for an existing B<SSL_CTX> structure.
97 An B<SSL_CTX> object should not be changed after it is used to create any B<SSL>
98 objects or from multiple threads concurrently, since the implementation does not
99 provide serialization of access for these cases.
103 On session establishment, by default, no peer credentials verification is done.
104 This must be explicitly requested, typically using L<SSL_CTX_set_verify(3)>.
105 For verifying peer certificates many options can be set using various functions
106 such as L<SSL_CTX_load_verify_locations(3)> and L<SSL_CTX_set1_param(3)>.
107 The L<X509_VERIFY_PARAM_set_purpose(3)> function can be used, also in conjunction
108 with L<SSL_CTX_get0_param(3)>, to set the intended purpose of the session.
109 The default is B<X509_PURPOSE_SSL_SERVER> on the client side
110 and B<X509_PURPOSE_SSL_CLIENT> on the server side.
112 The SSL_CTX object uses I<method> as the connection method.
113 Three method variants are available: a generic method (for either client or
114 server use), a server-only method, and a client-only method.
116 The I<method> parameter of SSL_CTX_new_ex() and SSL_CTX_new()
117 can be one of the following:
121 =item TLS_method(), TLS_server_method(), TLS_client_method()
123 These are the general-purpose I<version-flexible> SSL/TLS methods.
124 The actual protocol version used will be negotiated to the highest version
125 mutually supported by the client and the server.
126 The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3.
127 Applications should use these methods, and avoid the version-specific
128 methods described below, which are deprecated.
130 =item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()
132 These functions do not exist anymore, they have been renamed to
133 TLS_method(), TLS_server_method() and TLS_client_method() respectively.
134 Currently, the old function calls are renamed to the corresponding new
135 ones by preprocessor macros, to ensure that existing code which uses the
136 old function names still compiles. However, using the old function names
137 is deprecated and new code should call the new functions instead.
139 =item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()
141 A TLS/SSL connection established with these methods will only understand the
142 TLSv1.2 protocol. These methods are deprecated.
144 =item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()
146 A TLS/SSL connection established with these methods will only understand the
147 TLSv1.1 protocol. These methods are deprecated.
149 =item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()
151 A TLS/SSL connection established with these methods will only understand the
152 TLSv1 protocol. These methods are deprecated.
154 =item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()
156 A TLS/SSL connection established with these methods will only understand the
158 The SSLv3 protocol is deprecated and should not be used.
160 =item DTLS_method(), DTLS_server_method(), DTLS_client_method()
162 These are the version-flexible DTLS methods.
163 Currently supported protocols are DTLS 1.0 and DTLS 1.2.
165 =item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()
167 These are the version-specific methods for DTLSv1.2.
168 These methods are deprecated.
170 =item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()
172 These are the version-specific methods for DTLSv1.
173 These methods are deprecated.
177 SSL_CTX_new() initializes the list of ciphers, the session cache setting, the
178 callbacks, the keys and certificates and the options to their default values.
180 TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(),
181 DTLS_server_method() and DTLS_client_method() are the I<version-flexible>
183 All other methods only support one specific protocol version.
184 Use the I<version-flexible> methods instead of the version specific methods.
186 If you want to limit the supported protocols for the version flexible
187 methods you can use L<SSL_CTX_set_min_proto_version(3)>,
188 L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and
189 L<SSL_set_max_proto_version(3)> functions.
190 Using these functions it is possible to choose e.g. TLS_server_method()
191 and be able to negotiate with all possible clients, but to only
192 allow newer protocols like TLS 1.0, TLS 1.1, TLS 1.2 or TLS 1.3.
194 The list of protocols available can also be limited using the
195 B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1>,
196 B<SSL_OP_NO_TLSv1_3>, B<SSL_OP_NO_TLSv1_2> and B<SSL_OP_NO_TLSv1_3>
198 L<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions, but this approach
199 is not recommended. Clients should avoid creating "holes" in the set of
200 protocols they support. When disabling a protocol, make sure that you also
201 disable either all previous or all subsequent protocol versions.
202 In clients, when a protocol version is disabled without disabling I<all>
203 previous protocol versions, the effect is to also disable all subsequent
206 The SSLv3 protocol is deprecated and should generally not be used.
207 Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set
208 the minimum protocol to at least B<TLS1_VERSION>.
212 The following return values can occur:
218 The creation of a new SSL_CTX object failed. Check the error stack to find out
221 =item Pointer to an SSL_CTX object
223 The return value points to an allocated SSL_CTX object.
225 SSL_CTX_up_ref() returns 1 for success and 0 for failure.
231 L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>,
232 SSL_CTX_set_verify(3), L<SSL_CTX_set1_param(3)>, L<SSL_CTX_get0_param(3)>,
233 L<SSL_connect(3)>, L<SSL_accept(3)>,
234 L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)>
238 Support for SSLv2 and the corresponding SSLv2_method(),
239 SSLv2_server_method() and SSLv2_client_method() functions where
240 removed in OpenSSL 1.1.0.
242 SSLv23_method(), SSLv23_server_method() and SSLv23_client_method()
243 were deprecated and the preferred TLS_method(), TLS_server_method()
244 and TLS_client_method() functions were added in OpenSSL 1.1.0.
246 All version-specific methods were deprecated in OpenSSL 1.1.0.
248 SSL_CTX_new_ex() was added in OpenSSL 3.0.
252 Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
254 Licensed under the Apache License 2.0 (the "License"). You may not use
255 this file except in compliance with the License. You can obtain a copy
256 in the file LICENSE in the source distribution or at
257 L<https://www.openssl.org/source/license.html>.