]>
Commit | Line | Data |
---|---|---|
4759abc5 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c | 5 | TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method, |
d8652be0 | 6 | SSL_CTX_new, SSL_CTX_new_ex, SSL_CTX_up_ref, SSLv3_method, |
22806858 MC |
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 | |
c952780c | 14 | - create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled |
57ce7b61 | 15 | functions |
4759abc5 RL |
16 | |
17 | =head1 SYNOPSIS | |
18 | ||
19 | #include <openssl/ssl.h> | |
20 | ||
b4250010 | 21 | SSL_CTX *SSL_CTX_new_ex(OSSL_LIB_CTX *libctx, const char *propq, |
d8652be0 | 22 | const SSL_METHOD *method); |
4ebb342f | 23 | SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); |
c5ebfcab | 24 | int SSL_CTX_up_ref(SSL_CTX *ctx); |
4759abc5 | 25 | |
7946ab33 KR |
26 | const SSL_METHOD *TLS_method(void); |
27 | const SSL_METHOD *TLS_server_method(void); | |
28 | const SSL_METHOD *TLS_client_method(void); | |
29 | ||
91da5e77 RS |
30 | const SSL_METHOD *SSLv23_method(void); |
31 | const SSL_METHOD *SSLv23_server_method(void); | |
32 | const SSL_METHOD *SSLv23_client_method(void); | |
7946ab33 KR |
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 | ||
1fc7d666 | 40 | #ifndef OPENSSL_NO_TLS1_METHOD |
7946ab33 KR |
41 | const SSL_METHOD *TLSv1_method(void); |
42 | const SSL_METHOD *TLSv1_server_method(void); | |
43 | const SSL_METHOD *TLSv1_client_method(void); | |
1fc7d666 | 44 | #endif |
7946ab33 | 45 | |
1fc7d666 | 46 | #ifndef OPENSSL_NO_TLS1_1_METHOD |
7946ab33 KR |
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); | |
1fc7d666 | 50 | #endif |
7946ab33 | 51 | |
1fc7d666 | 52 | #ifndef OPENSSL_NO_TLS1_2_METHOD |
7946ab33 KR |
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); | |
1fc7d666 | 56 | #endif |
7946ab33 KR |
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 | ||
1fc7d666 | 62 | #ifndef OPENSSL_NO_DTLS1_METHOD |
7946ab33 KR |
63 | const SSL_METHOD *DTLSv1_method(void); |
64 | const SSL_METHOD *DTLSv1_server_method(void); | |
65 | const SSL_METHOD *DTLSv1_client_method(void); | |
1fc7d666 | 66 | #endif |
7946ab33 | 67 | |
1fc7d666 | 68 | #ifndef OPENSSL_NO_DTLS1_2_METHOD |
7946ab33 KR |
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); | |
1fc7d666 | 72 | #endif |
7946ab33 | 73 | |
4759abc5 RL |
74 | =head1 DESCRIPTION |
75 | ||
d8652be0 | 76 | SSL_CTX_new_ex() creates a new B<SSL_CTX> object as a framework to |
22806858 | 77 | establish TLS/SSL or DTLS enabled connections using the library context |
b4250010 | 78 | I<libctx> (see L<OSSL_LIB_CTX(3)>). Any cryptographic algorithms that are used |
22806858 MC |
79 | by any B<SSL> objects created from this B<SSL_CTX> will be fetched from the |
80 | I<libctx> using the property query string I<propq> (see | |
81 | L<provider(7)/Fetching algorithms>. Either or both the I<libctx> or I<propq> | |
82 | parameters may be NULL. | |
83 | ||
d8652be0 | 84 | SSL_CTX_new() does the same as SSL_CTX_new_ex() except that the default |
22806858 MC |
85 | library context is used and no property query string is specified. |
86 | ||
87 | An B<SSL_CTX> object is reference counted. Creating an B<SSL_CTX> object for the | |
88 | first time increments the reference count. Freeing the B<SSL_CTX> (using | |
89 | SSL_CTX_free) decrements it. When the reference count drops to zero, any memory | |
90 | or resources allocated to the B<SSL_CTX> object are freed. SSL_CTX_up_ref() | |
91 | increments the reference count for an existing B<SSL_CTX> structure. | |
4759abc5 RL |
92 | |
93 | =head1 NOTES | |
94 | ||
22806858 | 95 | The SSL_CTX object uses I<method> as the connection method. |
57ce7b61 VD |
96 | The methods exist in a generic type (for client and server use), a server only |
97 | type, and a client only type. | |
22806858 | 98 | B<method> can be one of the following types: |
4759abc5 RL |
99 | |
100 | =over 4 | |
101 | ||
8c73aeb6 | 102 | =item TLS_method(), TLS_server_method(), TLS_client_method() |
4759abc5 | 103 | |
8c73aeb6 VD |
104 | These are the general-purpose I<version-flexible> SSL/TLS methods. |
105 | The actual protocol version used will be negotiated to the highest version | |
106 | mutually supported by the client and the server. | |
322755cc | 107 | The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3. |
2b8fa1d5 | 108 | Applications should use these methods, and avoid the version-specific |
f308fa25 | 109 | methods described below, which are deprecated. |
4759abc5 | 110 | |
8c73aeb6 | 111 | =item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() |
3db935a9 | 112 | |
f308fa25 DMSP |
113 | These functions do not exist anymore, they have been renamed to |
114 | TLS_method(), TLS_server_method() and TLS_client_method() respectively. | |
115 | Currently, the old function calls are renamed to the corresponding new | |
116 | ones by preprocessor macros, to ensure that existing code which uses the | |
117 | old function names still compiles. However, using the old function names | |
118 | is deprecated and new code should call the new functions instead. | |
3db935a9 | 119 | |
7946ab33 | 120 | =item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method() |
a27e81ee | 121 | |
8c73aeb6 | 122 | A TLS/SSL connection established with these methods will only understand the |
f308fa25 | 123 | TLSv1.2 protocol. These methods are deprecated. |
a27e81ee | 124 | |
8c73aeb6 | 125 | =item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method() |
4759abc5 | 126 | |
8c73aeb6 | 127 | A TLS/SSL connection established with these methods will only understand the |
f308fa25 | 128 | TLSv1.1 protocol. These methods are deprecated. |
528b1f9a | 129 | |
8c73aeb6 | 130 | =item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() |
528b1f9a | 131 | |
8c73aeb6 | 132 | A TLS/SSL connection established with these methods will only understand the |
f308fa25 | 133 | TLSv1 protocol. These methods are deprecated. |
a27e81ee | 134 | |
8c73aeb6 VD |
135 | =item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method() |
136 | ||
137 | A TLS/SSL connection established with these methods will only understand the | |
138 | SSLv3 protocol. | |
139 | The SSLv3 protocol is deprecated and should not be used. | |
a27e81ee | 140 | |
7946ab33 KR |
141 | =item DTLS_method(), DTLS_server_method(), DTLS_client_method() |
142 | ||
8c73aeb6 | 143 | These are the version-flexible DTLS methods. |
7946ab33 KR |
144 | Currently supported protocols are DTLS 1.0 and DTLS 1.2. |
145 | ||
8c73aeb6 | 146 | =item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method() |
7946ab33 | 147 | |
8c73aeb6 | 148 | These are the version-specific methods for DTLSv1.2. |
f308fa25 | 149 | These methods are deprecated. |
7946ab33 | 150 | |
8c73aeb6 | 151 | =item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method() |
7946ab33 | 152 | |
8c73aeb6 | 153 | These are the version-specific methods for DTLSv1. |
f308fa25 | 154 | These methods are deprecated. |
7946ab33 | 155 | |
4759abc5 RL |
156 | =back |
157 | ||
8c73aeb6 VD |
158 | SSL_CTX_new() initializes the list of ciphers, the session cache setting, the |
159 | callbacks, the keys and certificates and the options to their default values. | |
160 | ||
57ce7b61 | 161 | TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), |
8c73aeb6 VD |
162 | DTLS_server_method() and DTLS_client_method() are the I<version-flexible> |
163 | methods. | |
57ce7b61 | 164 | All other methods only support one specific protocol version. |
8c73aeb6 | 165 | Use the I<version-flexible> methods instead of the version specific methods. |
57ce7b61 VD |
166 | |
167 | If you want to limit the supported protocols for the version flexible | |
8c73aeb6 VD |
168 | methods you can use L<SSL_CTX_set_min_proto_version(3)>, |
169 | L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and | |
eb43101f | 170 | L<SSL_set_max_proto_version(3)> functions. |
57ce7b61 VD |
171 | Using these functions it is possible to choose e.g. TLS_server_method() |
172 | and be able to negotiate with all possible clients, but to only | |
322755cc | 173 | allow newer protocols like TLS 1.0, TLS 1.1, TLS 1.2 or TLS 1.3. |
57ce7b61 | 174 | |
8c73aeb6 | 175 | The list of protocols available can also be limited using the |
582a17d6 | 176 | B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1>, |
322755cc HK |
177 | B<SSL_OP_NO_TLSv1_3>, B<SSL_OP_NO_TLSv1_2> and B<SSL_OP_NO_TLSv1_3> |
178 | options of the | |
582a17d6 MC |
179 | L<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions, but this approach |
180 | is not recommended. Clients should avoid creating "holes" in the set of | |
181 | protocols they support. When disabling a protocol, make sure that you also | |
182 | disable either all previous or all subsequent protocol versions. | |
8c73aeb6 VD |
183 | In clients, when a protocol version is disabled without disabling I<all> |
184 | previous protocol versions, the effect is to also disable all subsequent | |
185 | protocol versions. | |
186 | ||
187 | The SSLv3 protocol is deprecated and should generally not be used. | |
188 | Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set | |
189 | the minimum protocol to at least B<TLS1_VERSION>. | |
4759abc5 RL |
190 | |
191 | =head1 RETURN VALUES | |
192 | ||
193 | The following return values can occur: | |
194 | ||
195 | =over 4 | |
196 | ||
197 | =item NULL | |
198 | ||
8c73aeb6 VD |
199 | The creation of a new SSL_CTX object failed. Check the error stack to find out |
200 | the reason. | |
4759abc5 RL |
201 | |
202 | =item Pointer to an SSL_CTX object | |
203 | ||
204 | The return value points to an allocated SSL_CTX object. | |
205 | ||
c5ebfcab F |
206 | SSL_CTX_up_ref() returns 1 for success and 0 for failure. |
207 | ||
4759abc5 RL |
208 | =back |
209 | ||
b5c4bbbe JL |
210 | =head1 SEE ALSO |
211 | ||
212 | L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>, | |
213 | L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)> | |
214 | ||
45f55f6a KR |
215 | =head1 HISTORY |
216 | ||
57ce7b61 VD |
217 | Support for SSLv2 and the corresponding SSLv2_method(), |
218 | SSLv2_server_method() and SSLv2_client_method() functions where | |
219 | removed in OpenSSL 1.1.0. | |
220 | ||
221 | SSLv23_method(), SSLv23_server_method() and SSLv23_client_method() | |
222 | were deprecated and the preferred TLS_method(), TLS_server_method() | |
938e82f6 | 223 | and TLS_client_method() functions were added in OpenSSL 1.1.0. |
45f55f6a | 224 | |
2b8fa1d5 KR |
225 | All version-specific methods were deprecated in OpenSSL 1.1.0. |
226 | ||
d8652be0 | 227 | SSL_CTX_new_ex() was added in OpenSSL 3.0. |
22806858 | 228 | |
e2f92610 RS |
229 | =head1 COPYRIGHT |
230 | ||
33388b44 | 231 | Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 232 | |
4746f25a | 233 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 | L<https://www.openssl.org/source/license.html>. | |
237 | ||
238 | =cut |