1SSL_CTX_NEW(3ossl)                  OpenSSL                 SSL_CTX_NEW(3ossl)
2
3
4

NAME

6       TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method,
7       SSL_CTX_new, SSL_CTX_new_ex, SSL_CTX_up_ref, SSLv3_method,
8       SSLv3_server_method, SSLv3_client_method, TLSv1_method,
9       TLSv1_server_method, TLSv1_client_method, TLSv1_1_method,
10       TLSv1_1_server_method, TLSv1_1_client_method, TLS_method,
11       TLS_server_method, TLS_client_method, SSLv23_method,
12       SSLv23_server_method, SSLv23_client_method, DTLS_method,
13       DTLS_server_method, DTLS_client_method, DTLSv1_method,
14       DTLSv1_server_method, DTLSv1_client_method, DTLSv1_2_method,
15       DTLSv1_2_server_method, DTLSv1_2_client_method - create a new SSL_CTX
16       object as framework for TLS/SSL or DTLS enabled functions
17

SYNOPSIS

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

DESCRIPTION

75       SSL_CTX_new_ex() creates a new SSL_CTX object, which holds various
76       configuration and data relevant to SSL/TLS or DTLS session
77       establishment.  These are later inherited by the SSL object
78       representing an active session.  The method parameter specifies whether
79       the context will be used for the client or server side or both - for
80       details see the "NOTES" below.  The library context libctx (see
81       OSSL_LIB_CTX(3)) is used to provide the cryptographic algorithms needed
82       for the session. Any cryptographic algorithms that are used by any SSL
83       objects created from this SSL_CTX will be fetched from the libctx using
84       the property query string propq (see "ALGORITHM FETCHING" in crypto(7).
85       Either or both the libctx or propq parameters may be NULL.
86
87       SSL_CTX_new() does the same as SSL_CTX_new_ex() except that the default
88       library context is used and no property query string is specified.
89
90       An SSL_CTX object is reference counted. Creating an SSL_CTX object for
91       the first time increments the reference count. Freeing the SSL_CTX
92       (using SSL_CTX_free) decrements it. When the reference count drops to
93       zero, any memory or resources allocated to the SSL_CTX object are
94       freed. SSL_CTX_up_ref() increments the reference count for an existing
95       SSL_CTX structure.
96
97       An SSL_CTX object should not be changed after it is used to create any
98       SSL objects or from multiple threads concurrently, since the
99       implementation does not provide serialization of access for these
100       cases.
101

NOTES

103       On session estabilishment, by default, no peer credentials verification
104       is done.  This must be explicitly requested, typically using
105       SSL_CTX_set_verify(3).  For verifying peer certificates many options
106       can be set using various functions such as
107       SSL_CTX_load_verify_locations(3) and SSL_CTX_set1_param(3).  The
108       X509_VERIFY_PARAM_set_purpose(3) function can be used, also in
109       conjunction with SSL_CTX_get0_param(3), to set the intended purpose of
110       the session.  The default is X509_PURPOSE_SSL_SERVER on the client side
111       and X509_PURPOSE_SSL_CLIENT on the server side.
112
113       The SSL_CTX object uses method as the connection method.  Three method
114       variants are available: a generic method (for either client or server
115       use), a server-only method, and a client-only method.
116
117       The method parameter of SSL_CTX_new_ex() and SSL_CTX_new() can be one
118       of the following:
119
120       TLS_method(), TLS_server_method(), TLS_client_method()
121           These are the general-purpose version-flexible SSL/TLS methods.
122           The actual protocol version used will be negotiated to the highest
123           version mutually supported by the client and the server.  The
124           supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3.
125           Applications should use these methods, and avoid the version-
126           specific methods described below, which are deprecated.
127
128       SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()
129           These functions do not exist anymore, they have been renamed to
130           TLS_method(), TLS_server_method() and TLS_client_method()
131           respectively.  Currently, the old function calls are renamed to the
132           corresponding new ones by preprocessor macros, to ensure that
133           existing code which uses the old function names still compiles.
134           However, using the old function names is deprecated and new code
135           should call the new functions instead.
136
137       TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()
138           A TLS/SSL connection established with these methods will only
139           understand the TLSv1.2 protocol. These methods are deprecated.
140
141       TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()
142           A TLS/SSL connection established with these methods will only
143           understand the TLSv1.1 protocol.  These methods are deprecated.
144
145       TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()
146           A TLS/SSL connection established with these methods will only
147           understand the TLSv1 protocol. These methods are deprecated.
148
149       SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()
150           A TLS/SSL connection established with these methods will only
151           understand the SSLv3 protocol.  The SSLv3 protocol is deprecated
152           and should not be used.
153
154       DTLS_method(), DTLS_server_method(), DTLS_client_method()
155           These are the version-flexible DTLS methods.  Currently supported
156           protocols are DTLS 1.0 and DTLS 1.2.
157
158       DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()
159           These are the version-specific methods for DTLSv1.2.  These methods
160           are deprecated.
161
162       DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()
163           These are the version-specific methods for DTLSv1.  These methods
164           are deprecated.
165
166       SSL_CTX_new() initializes the list of ciphers, the session cache
167       setting, the callbacks, the keys and certificates and the options to
168       their default values.
169
170       TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(),
171       DTLS_server_method() and DTLS_client_method() are the version-flexible
172       methods.  All other methods only support one specific protocol version.
173       Use the version-flexible methods instead of the version specific
174       methods.
175
176       If you want to limit the supported protocols for the version flexible
177       methods you can use SSL_CTX_set_min_proto_version(3),
178       SSL_set_min_proto_version(3), SSL_CTX_set_max_proto_version(3) and
179       SSL_set_max_proto_version(3) functions.  Using these functions it is
180       possible to choose e.g. TLS_server_method() and be able to negotiate
181       with all possible clients, but to only allow newer protocols like TLS
182       1.0, TLS 1.1, TLS 1.2 or TLS 1.3.
183
184       The list of protocols available can also be limited using the
185       SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_3,
186       SSL_OP_NO_TLSv1_2 and SSL_OP_NO_TLSv1_3 options of the
187       SSL_CTX_set_options(3) or SSL_set_options(3) functions, but this
188       approach is not recommended. Clients should avoid creating "holes" in
189       the set of protocols they support. When disabling a protocol, make sure
190       that you also disable either all previous or all subsequent protocol
191       versions.  In clients, when a protocol version is disabled without
192       disabling all previous protocol versions, the effect is to also disable
193       all subsequent protocol versions.
194
195       The SSLv3 protocol is deprecated and should generally not be used.
196       Applications should typically use SSL_CTX_set_min_proto_version(3) to
197       set the minimum protocol to at least TLS1_VERSION.
198

RETURN VALUES

200       The following return values can occur:
201
202       NULL
203           The creation of a new SSL_CTX object failed. Check the error stack
204           to find out the reason.
205
206       Pointer to an SSL_CTX object
207           The return value points to an allocated SSL_CTX object.
208
209           SSL_CTX_up_ref() returns 1 for success and 0 for failure.
210

SEE ALSO

212       SSL_CTX_set_options(3), SSL_CTX_free(3), SSL_CTX_set_verify(3),
213       SSL_CTX_set1_param(3), SSL_CTX_get0_param(3), SSL_connect(3),
214       SSL_accept(3), SSL_CTX_set_min_proto_version(3), ssl(7),
215       SSL_set_connect_state(3)
216

HISTORY

218       Support for SSLv2 and the corresponding SSLv2_method(),
219       SSLv2_server_method() and SSLv2_client_method() functions where removed
220       in OpenSSL 1.1.0.
221
222       SSLv23_method(), SSLv23_server_method() and SSLv23_client_method() were
223       deprecated and the preferred TLS_method(), TLS_server_method() and
224       TLS_client_method() functions were added in OpenSSL 1.1.0.
225
226       All version-specific methods were deprecated in OpenSSL 1.1.0.
227
228       SSL_CTX_new_ex() was added in OpenSSL 3.0.
229

COPYRIGHT

231       Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
232
233       Licensed under the Apache License 2.0 (the "License").  You may not use
234       this file except in compliance with the License.  You can obtain a copy
235       in the file LICENSE in the source distribution or at
236       <https://www.openssl.org/source/license.html>.
237
238
239
2403.1.1                             2023-08-31                SSL_CTX_NEW(3ossl)