]>
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, |
a18a31e4 MC |
6 | SSL_CTX_new, SSL_CTX_up_ref, SSLv3_method, SSLv3_server_method, |
7 | SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method, | |
8 | TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, TLS_method, | |
57ce7b61 VD |
9 | TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method, |
10 | SSLv23_client_method, DTLS_method, DTLS_server_method, DTLS_client_method, | |
11 | DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method, | |
c952780c RS |
12 | DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method |
13 | - create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled | |
57ce7b61 | 14 | functions |
4759abc5 RL |
15 | |
16 | =head1 SYNOPSIS | |
17 | ||
18 | #include <openssl/ssl.h> | |
19 | ||
4ebb342f | 20 | SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); |
c5ebfcab | 21 | int SSL_CTX_up_ref(SSL_CTX *ctx); |
4759abc5 | 22 | |
7946ab33 KR |
23 | const SSL_METHOD *TLS_method(void); |
24 | const SSL_METHOD *TLS_server_method(void); | |
25 | const SSL_METHOD *TLS_client_method(void); | |
26 | ||
91da5e77 RS |
27 | const SSL_METHOD *SSLv23_method(void); |
28 | const SSL_METHOD *SSLv23_server_method(void); | |
29 | const SSL_METHOD *SSLv23_client_method(void); | |
7946ab33 KR |
30 | |
31 | #ifndef OPENSSL_NO_SSL3_METHOD | |
32 | const SSL_METHOD *SSLv3_method(void); | |
33 | const SSL_METHOD *SSLv3_server_method(void); | |
34 | const SSL_METHOD *SSLv3_client_method(void); | |
35 | #endif | |
36 | ||
1fc7d666 | 37 | #ifndef OPENSSL_NO_TLS1_METHOD |
7946ab33 KR |
38 | const SSL_METHOD *TLSv1_method(void); |
39 | const SSL_METHOD *TLSv1_server_method(void); | |
40 | const SSL_METHOD *TLSv1_client_method(void); | |
1fc7d666 | 41 | #endif |
7946ab33 | 42 | |
1fc7d666 | 43 | #ifndef OPENSSL_NO_TLS1_1_METHOD |
7946ab33 KR |
44 | const SSL_METHOD *TLSv1_1_method(void); |
45 | const SSL_METHOD *TLSv1_1_server_method(void); | |
46 | const SSL_METHOD *TLSv1_1_client_method(void); | |
1fc7d666 | 47 | #endif |
7946ab33 | 48 | |
1fc7d666 | 49 | #ifndef OPENSSL_NO_TLS1_2_METHOD |
7946ab33 KR |
50 | const SSL_METHOD *TLSv1_2_method(void); |
51 | const SSL_METHOD *TLSv1_2_server_method(void); | |
52 | const SSL_METHOD *TLSv1_2_client_method(void); | |
1fc7d666 | 53 | #endif |
7946ab33 KR |
54 | |
55 | const SSL_METHOD *DTLS_method(void); | |
56 | const SSL_METHOD *DTLS_server_method(void); | |
57 | const SSL_METHOD *DTLS_client_method(void); | |
58 | ||
1fc7d666 | 59 | #ifndef OPENSSL_NO_DTLS1_METHOD |
7946ab33 KR |
60 | const SSL_METHOD *DTLSv1_method(void); |
61 | const SSL_METHOD *DTLSv1_server_method(void); | |
62 | const SSL_METHOD *DTLSv1_client_method(void); | |
1fc7d666 | 63 | #endif |
7946ab33 | 64 | |
1fc7d666 | 65 | #ifndef OPENSSL_NO_DTLS1_2_METHOD |
7946ab33 KR |
66 | const SSL_METHOD *DTLSv1_2_method(void); |
67 | const SSL_METHOD *DTLSv1_2_server_method(void); | |
68 | const SSL_METHOD *DTLSv1_2_client_method(void); | |
1fc7d666 | 69 | #endif |
7946ab33 | 70 | |
4759abc5 RL |
71 | =head1 DESCRIPTION |
72 | ||
57ce7b61 | 73 | SSL_CTX_new() creates a new B<SSL_CTX> object as framework to |
a18a31e4 MC |
74 | establish TLS/SSL or DTLS enabled connections. An B<SSL_CTX> object is |
75 | reference counted. Creating an B<SSL_CTX> object for the first time increments | |
76 | the reference count. Freeing it (using SSL_CTX_free) decrements it. When the | |
77 | reference count drops to zero, any memory or resources allocated to the | |
78 | B<SSL_CTX> object are freed. SSL_CTX_up_ref() increments the reference count for | |
79 | an existing B<SSL_CTX> structure. | |
4759abc5 RL |
80 | |
81 | =head1 NOTES | |
82 | ||
7946ab33 | 83 | The SSL_CTX object uses B<method> as connection method. |
57ce7b61 VD |
84 | The methods exist in a generic type (for client and server use), a server only |
85 | type, and a client only type. | |
7946ab33 | 86 | B<method> can be of the following types: |
4759abc5 RL |
87 | |
88 | =over 4 | |
89 | ||
8c73aeb6 | 90 | =item TLS_method(), TLS_server_method(), TLS_client_method() |
4759abc5 | 91 | |
8c73aeb6 VD |
92 | These are the general-purpose I<version-flexible> SSL/TLS methods. |
93 | The actual protocol version used will be negotiated to the highest version | |
94 | mutually supported by the client and the server. | |
95 | The supported protocols are SSLv3, TLSv1, TLSv1.1 and TLSv1.2. | |
2b8fa1d5 | 96 | Applications should use these methods, and avoid the version-specific |
8c73aeb6 | 97 | methods described below. |
4759abc5 | 98 | |
8c73aeb6 | 99 | =item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() |
3db935a9 | 100 | |
8c73aeb6 VD |
101 | Use of these functions is deprecated. They have been replaced with the above |
102 | TLS_method(), TLS_server_method() and TLS_client_method() respectively. New | |
103 | code should use those functions instead. | |
3db935a9 | 104 | |
7946ab33 | 105 | =item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method() |
a27e81ee | 106 | |
8c73aeb6 VD |
107 | A TLS/SSL connection established with these methods will only understand the |
108 | TLSv1.2 protocol. | |
a27e81ee | 109 | |
8c73aeb6 | 110 | =item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method() |
4759abc5 | 111 | |
8c73aeb6 VD |
112 | A TLS/SSL connection established with these methods will only understand the |
113 | TLSv1.1 protocol. | |
528b1f9a | 114 | |
8c73aeb6 | 115 | =item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() |
528b1f9a | 116 | |
8c73aeb6 VD |
117 | A TLS/SSL connection established with these methods will only understand the |
118 | TLSv1 protocol. | |
a27e81ee | 119 | |
8c73aeb6 VD |
120 | =item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method() |
121 | ||
122 | A TLS/SSL connection established with these methods will only understand the | |
123 | SSLv3 protocol. | |
124 | The SSLv3 protocol is deprecated and should not be used. | |
a27e81ee | 125 | |
7946ab33 KR |
126 | =item DTLS_method(), DTLS_server_method(), DTLS_client_method() |
127 | ||
8c73aeb6 | 128 | These are the version-flexible DTLS methods. |
7946ab33 KR |
129 | Currently supported protocols are DTLS 1.0 and DTLS 1.2. |
130 | ||
8c73aeb6 | 131 | =item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method() |
7946ab33 | 132 | |
8c73aeb6 | 133 | These are the version-specific methods for DTLSv1.2. |
7946ab33 | 134 | |
8c73aeb6 | 135 | =item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method() |
7946ab33 | 136 | |
8c73aeb6 | 137 | These are the version-specific methods for DTLSv1. |
7946ab33 | 138 | |
4759abc5 RL |
139 | =back |
140 | ||
8c73aeb6 VD |
141 | SSL_CTX_new() initializes the list of ciphers, the session cache setting, the |
142 | callbacks, the keys and certificates and the options to their default values. | |
143 | ||
57ce7b61 | 144 | TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), |
8c73aeb6 VD |
145 | DTLS_server_method() and DTLS_client_method() are the I<version-flexible> |
146 | methods. | |
57ce7b61 | 147 | All other methods only support one specific protocol version. |
8c73aeb6 | 148 | Use the I<version-flexible> methods instead of the version specific methods. |
57ce7b61 VD |
149 | |
150 | If you want to limit the supported protocols for the version flexible | |
8c73aeb6 VD |
151 | methods you can use L<SSL_CTX_set_min_proto_version(3)>, |
152 | L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and | |
153 | LSSL_set_max_proto_version(3)> functions. | |
57ce7b61 VD |
154 | Using these functions it is possible to choose e.g. TLS_server_method() |
155 | and be able to negotiate with all possible clients, but to only | |
156 | allow newer protocols like TLS 1.0, TLS 1.1 or TLS 1.2. | |
157 | ||
8c73aeb6 | 158 | The list of protocols available can also be limited using the |
582a17d6 MC |
159 | B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1>, |
160 | B<SSL_OP_NO_TLSv1_3> and B<SSL_OP_NO_TLSv1_2> options of the | |
161 | L<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions, but this approach | |
162 | is not recommended. Clients should avoid creating "holes" in the set of | |
163 | protocols they support. When disabling a protocol, make sure that you also | |
164 | disable either all previous or all subsequent protocol versions. | |
8c73aeb6 VD |
165 | In clients, when a protocol version is disabled without disabling I<all> |
166 | previous protocol versions, the effect is to also disable all subsequent | |
167 | protocol versions. | |
168 | ||
169 | The SSLv3 protocol is deprecated and should generally not be used. | |
170 | Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set | |
171 | the minimum protocol to at least B<TLS1_VERSION>. | |
4759abc5 RL |
172 | |
173 | =head1 RETURN VALUES | |
174 | ||
175 | The following return values can occur: | |
176 | ||
177 | =over 4 | |
178 | ||
179 | =item NULL | |
180 | ||
8c73aeb6 VD |
181 | The creation of a new SSL_CTX object failed. Check the error stack to find out |
182 | the reason. | |
4759abc5 RL |
183 | |
184 | =item Pointer to an SSL_CTX object | |
185 | ||
186 | The return value points to an allocated SSL_CTX object. | |
187 | ||
c5ebfcab F |
188 | SSL_CTX_up_ref() returns 1 for success and 0 for failure. |
189 | ||
4759abc5 RL |
190 | =back |
191 | ||
45f55f6a KR |
192 | =head1 HISTORY |
193 | ||
57ce7b61 VD |
194 | Support for SSLv2 and the corresponding SSLv2_method(), |
195 | SSLv2_server_method() and SSLv2_client_method() functions where | |
196 | removed in OpenSSL 1.1.0. | |
197 | ||
198 | SSLv23_method(), SSLv23_server_method() and SSLv23_client_method() | |
199 | were deprecated and the preferred TLS_method(), TLS_server_method() | |
200 | and TLS_client_method() functions were introduced in OpenSSL 1.1.0. | |
45f55f6a | 201 | |
2b8fa1d5 KR |
202 | All version-specific methods were deprecated in OpenSSL 1.1.0. |
203 | ||
4759abc5 RL |
204 | =head1 SEE ALSO |
205 | ||
8c73aeb6 | 206 | L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>, |
b97fdb57 | 207 | L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)> |
4759abc5 | 208 | |
e2f92610 RS |
209 | =head1 COPYRIGHT |
210 | ||
211 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
212 | ||
213 | Licensed under the OpenSSL license (the "License"). You may not use | |
214 | this file except in compliance with the License. You can obtain a copy | |
215 | in the file LICENSE in the source distribution or at | |
216 | L<https://www.openssl.org/source/license.html>. | |
217 | ||
218 | =cut |