Introducing option SSL_OP_IGNORE_UNEXPECTED_EOF
[openssl.git] / doc / man3 / SSL_CTX_set_options.pod
1 =pod
2
3 =head1 NAME
4
5 SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options,
6 SSL_clear_options, SSL_CTX_get_options, SSL_get_options,
7 SSL_get_secure_renegotiation_support - manipulate SSL options
8
9 =head1 SYNOPSIS
10
11  #include <openssl/ssl.h>
12
13  long SSL_CTX_set_options(SSL_CTX *ctx, long options);
14  long SSL_set_options(SSL *ssl, long options);
15
16  long SSL_CTX_clear_options(SSL_CTX *ctx, long options);
17  long SSL_clear_options(SSL *ssl, long options);
18
19  long SSL_CTX_get_options(SSL_CTX *ctx);
20  long SSL_get_options(SSL *ssl);
21
22  long SSL_get_secure_renegotiation_support(SSL *ssl);
23
24 =head1 DESCRIPTION
25
26 SSL_CTX_set_options() adds the options set via bit-mask in B<options> to B<ctx>.
27 Options already set before are not cleared!
28
29 SSL_set_options() adds the options set via bit-mask in B<options> to B<ssl>.
30 Options already set before are not cleared!
31
32 SSL_CTX_clear_options() clears the options set via bit-mask in B<options>
33 to B<ctx>.
34
35 SSL_clear_options() clears the options set via bit-mask in B<options> to B<ssl>.
36
37 SSL_CTX_get_options() returns the options set for B<ctx>.
38
39 SSL_get_options() returns the options set for B<ssl>.
40
41 SSL_get_secure_renegotiation_support() indicates whether the peer supports
42 secure renegotiation.
43 Note, this is implemented via a macro.
44
45 =head1 NOTES
46
47 The behaviour of the SSL library can be changed by setting several options.
48 The options are coded as bit-masks and can be combined by a bitwise B<or>
49 operation (|).
50
51 SSL_CTX_set_options() and SSL_set_options() affect the (external)
52 protocol behaviour of the SSL library. The (internal) behaviour of
53 the API can be changed by using the similar
54 L<SSL_CTX_set_mode(3)> and SSL_set_mode() functions.
55
56 During a handshake, the option settings of the SSL object are used. When
57 a new SSL object is created from a context using SSL_new(), the current
58 option setting is copied. Changes to B<ctx> do not affect already created
59 SSL objects. SSL_clear() does not affect the settings.
60
61 The following B<bug workaround> options are available:
62
63 =over 4
64
65 =item SSL_OP_SAFARI_ECDHE_ECDSA_BUG
66
67 Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X.
68 OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers.
69
70 =item SSL_OP_DISABLE_TLSEXT_CA_NAMES
71
72 Disable TLS Extension CA Names. You may want to disable it for security reasons
73 or for compatibility with some Windows TLS implementations crashing when this
74 extension is larger than 1024 bytes.
75
76 =item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
77
78 Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol
79 vulnerability affecting CBC ciphers, which cannot be handled by some
80 broken SSL implementations.  This option has no effect for connections
81 using other ciphers.
82
83 =item SSL_OP_TLSEXT_PADDING
84
85 Adds a padding extension to ensure the ClientHello size is never between
86 256 and 511 bytes in length. This is needed as a workaround for some
87 implementations.
88
89 =item SSL_OP_ALL
90
91 All of the above bug workarounds plus B<SSL_OP_LEGACY_SERVER_CONNECT> as
92 mentioned below.
93
94 =back
95
96 It is usually safe to use B<SSL_OP_ALL> to enable the bug workaround
97 options if compatibility with somewhat broken implementations is
98 desired.
99
100 The following B<modifying> options are available:
101
102 =over 4
103
104 =item SSL_OP_TLS_ROLLBACK_BUG
105
106 Disable version rollback attack detection.
107
108 During the client key exchange, the client must send the same information
109 about acceptable SSL/TLS protocol levels as during the first hello. Some
110 clients violate this rule by adapting to the server's answer. (Example:
111 the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
112 only understands up to SSLv3. In this case the client must still use the
113 same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
114 to the server's answer and violate the version rollback protection.)
115
116 =item SSL_OP_CIPHER_SERVER_PREFERENCE
117
118 When choosing a cipher, use the server's preferences instead of the client
119 preferences. When not set, the SSL server will always follow the clients
120 preferences. When set, the SSL/TLS server will choose following its
121 own preferences.
122
123 =item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1,
124 SSL_OP_NO_TLSv1_2, SSL_OP_NO_TLSv1_3, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2
125
126 These options turn off the SSLv3, TLSv1, TLSv1.1, TLSv1.2 or TLSv1.3 protocol
127 versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS,
128 respectively.
129 As of OpenSSL 1.1.0, these options are deprecated, use
130 L<SSL_CTX_set_min_proto_version(3)> and
131 L<SSL_CTX_set_max_proto_version(3)> instead.
132
133 =item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
134
135 When performing renegotiation as a server, always start a new session
136 (i.e., session resumption requests are only accepted in the initial
137 handshake). This option is not needed for clients.
138
139 =item SSL_OP_NO_COMPRESSION
140
141 Do not use compression even if it is supported.
142
143 =item SSL_OP_NO_QUERY_MTU
144
145 Do not query the MTU. Only affects DTLS connections.
146
147 =item SSL_OP_COOKIE_EXCHANGE
148
149 Turn on Cookie Exchange as described in RFC4347 Section 4.2.1. Only affects
150 DTLS connections.
151
152 =item SSL_OP_NO_TICKET
153
154 SSL/TLS supports two mechanisms for resuming sessions: session ids and stateless
155 session tickets.
156
157 When using session ids a copy of the session information is
158 cached on the server and a unique id is sent to the client. When the client
159 wishes to resume it provides the unique id so that the server can retrieve the
160 session information from its cache.
161
162 When using stateless session tickets the server uses a session ticket encryption
163 key to encrypt the session information. This encrypted data is sent to the
164 client as a "ticket". When the client wishes to resume it sends the encrypted
165 data back to the server. The server uses its key to decrypt the data and resume
166 the session. In this way the server can operate statelessly - no session
167 information needs to be cached locally.
168
169 The TLSv1.3 protocol only supports tickets and does not directly support session
170 ids. However OpenSSL allows two modes of ticket operation in TLSv1.3: stateful
171 and stateless. Stateless tickets work the same way as in TLSv1.2 and below.
172 Stateful tickets mimic the session id behaviour available in TLSv1.2 and below.
173 The session information is cached on the server and the session id is wrapped up
174 in a ticket and sent back to the client. When the client wishes to resume, it
175 presents a ticket in the same way as for stateless tickets. The server can then
176 extract the session id from the ticket and retrieve the session information from
177 its cache.
178
179 By default OpenSSL will use stateless tickets. The SSL_OP_NO_TICKET option will
180 cause stateless tickets to not be issued. In TLSv1.2 and below this means no
181 ticket gets sent to the client at all. In TLSv1.3 a stateful ticket will be
182 sent. This is a server-side option only.
183
184 In TLSv1.3 it is possible to suppress all tickets (stateful and stateless) from
185 being sent by calling L<SSL_CTX_set_num_tickets(3)> or
186 L<SSL_set_num_tickets(3)>.
187
188 =item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
189
190 Allow legacy insecure renegotiation between OpenSSL and unpatched clients or
191 servers. See the B<SECURE RENEGOTIATION> section for more details.
192
193 =item SSL_OP_LEGACY_SERVER_CONNECT
194
195 Allow legacy insecure renegotiation between OpenSSL and unpatched servers
196 B<only>: this option is currently set by default. See the
197 B<SECURE RENEGOTIATION> section for more details.
198
199 =item SSL_OP_NO_ENCRYPT_THEN_MAC
200
201 Normally clients and servers will transparently attempt to negotiate the
202 RFC7366 Encrypt-then-MAC option on TLS and DTLS connection.
203
204 If this option is set, Encrypt-then-MAC is disabled. Clients will not
205 propose, and servers will not accept the extension.
206
207 =item SSL_OP_NO_EXTENDED_MASTER_SECRET
208
209 Normally clients and servers will transparently attempt to negotiate the
210 RFC7627 Extended Master Secret option on TLS and DTLS connection.
211
212 If this option is set, Extended Master Secret is disabled. Clients will
213 not propose, and servers will not accept the extension.
214
215 =item SSL_OP_NO_RENEGOTIATION
216
217 Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest
218 messages, and ignore renegotiation requests via ClientHello.
219
220 =item SSL_OP_IGNORE_UNEXPECTED_EOF
221
222 Some TLS implementations do not send the mandatory close_notify alert on
223 shutdown. If the application tries to wait for the close_notify alert but the
224 peer closes the connection without sending it, an error is generated. When this
225 option is enabled the peer does not need to send the close_notify alert and a
226 closed connection will be treated as if the close_notify alert was received.
227
228 You should only enable this option if the protocol running over TLS
229 can detect a truncation attack itself, and that the application is checking for
230 that truncation attack.
231
232 For more information on shutting down a connection, see L<SSL_shutdown(3)>.
233
234 =item SSL_OP_ALLOW_NO_DHE_KEX
235
236 In TLSv1.3 allow a non-(ec)dhe based key exchange mode on resumption. This means
237 that there will be no forward secrecy for the resumed session.
238
239 =item SSL_OP_PRIORITIZE_CHACHA
240
241 When SSL_OP_CIPHER_SERVER_PREFERENCE is set, temporarily reprioritize
242 ChaCha20-Poly1305 ciphers to the top of the server cipher list if a
243 ChaCha20-Poly1305 cipher is at the top of the client cipher list. This helps
244 those clients (e.g. mobile) use ChaCha20-Poly1305 if that cipher is anywhere
245 in the server cipher list; but still allows other clients to use AES and other
246 ciphers. Requires B<SSL_OP_CIPHER_SERVER_PREFERENCE>.
247
248 =item SSL_OP_ENABLE_MIDDLEBOX_COMPAT
249
250 If set then dummy Change Cipher Spec (CCS) messages are sent in TLSv1.3. This
251 has the effect of making TLSv1.3 look more like TLSv1.2 so that middleboxes that
252 do not understand TLSv1.3 will not drop the connection. Regardless of whether
253 this option is set or not CCS messages received from the peer will always be
254 ignored in TLSv1.3. This option is set by default. To switch it off use
255 SSL_clear_options(). A future version of OpenSSL may not set this by default.
256
257 =item SSL_OP_NO_ANTI_REPLAY
258
259 By default, when a server is configured for early data (i.e., max_early_data > 0),
260 OpenSSL will switch on replay protection. See L<SSL_read_early_data(3)> for a
261 description of the replay protection feature. Anti-replay measures are required
262 to comply with the TLSv1.3 specification. Some applications may be able to
263 mitigate the replay risks in other ways and in such cases the built in OpenSSL
264 functionality is not required. Those applications can turn this feature off by
265 setting this option. This is a server-side opton only. It is ignored by
266 clients.
267
268 =back
269
270 The following options no longer have any effect but their identifiers are
271 retained for compatibility purposes:
272
273 =over 4
274
275 =item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
276
277 =item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
278
279 =item SSL_OP_SSLEAY_080_CLIENT_DH_BUG
280
281 =item SSL_OP_TLS_D5_BUG
282
283 =item SSL_OP_TLS_BLOCK_PADDING_BUG
284
285 =item SSL_OP_MSIE_SSLV2_RSA_PADDING
286
287 =item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
288
289 =item SSL_OP_MICROSOFT_SESS_ID_BUG
290
291 =item SSL_OP_NETSCAPE_CHALLENGE_BUG
292
293 =item SSL_OP_PKCS1_CHECK_1
294
295 =item SSL_OP_PKCS1_CHECK_2
296
297 =item SSL_OP_SINGLE_DH_USE
298
299 =item SSL_OP_SINGLE_ECDH_USE
300
301 =item SSL_OP_EPHEMERAL_RSA
302
303 =back
304
305 =head1 SECURE RENEGOTIATION
306
307 OpenSSL always attempts to use secure renegotiation as
308 described in RFC5746. This counters the prefix attack described in
309 CVE-2009-3555 and elsewhere.
310
311 This attack has far reaching consequences which application writers should be
312 aware of. In the description below an implementation supporting secure
313 renegotiation is referred to as I<patched>. A server not supporting secure
314 renegotiation is referred to as I<unpatched>.
315
316 The following sections describe the operations permitted by OpenSSL's secure
317 renegotiation implementation.
318
319 =head2 Patched client and server
320
321 Connections and renegotiation are always permitted by OpenSSL implementations.
322
323 =head2 Unpatched client and patched OpenSSL server
324
325 The initial connection succeeds but client renegotiation is denied by the
326 server with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal
327 B<handshake_failure> alert in SSL v3.0.
328
329 If the patched OpenSSL server attempts to renegotiate a fatal
330 B<handshake_failure> alert is sent. This is because the server code may be
331 unaware of the unpatched nature of the client.
332
333 If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then
334 renegotiation B<always> succeeds.
335
336 =head2 Patched OpenSSL client and unpatched server
337
338 If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or
339 B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections
340 and renegotiation between patched OpenSSL clients and unpatched servers
341 succeeds. If neither option is set then initial connections to unpatched
342 servers will fail.
343
344 The option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even
345 though it has security implications: otherwise it would be impossible to
346 connect to unpatched servers (i.e. all of them initially) and this is clearly
347 not acceptable. Renegotiation is permitted because this does not add any
348 additional security issues: during an attack clients do not see any
349 renegotiations anyway.
350
351 As more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will
352 B<not> be set by default in a future version of OpenSSL.
353
354 OpenSSL client applications wishing to ensure they can connect to unpatched
355 servers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT>
356
357 OpenSSL client applications that want to ensure they can B<not> connect to
358 unpatched servers (and thus avoid any security issues) should always B<clear>
359 B<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or
360 SSL_clear_options().
361
362 The difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and
363 B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that
364 B<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure
365 renegotiation between OpenSSL clients and unpatched servers B<only>, while
366 B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections
367 and renegotiation between OpenSSL and unpatched clients or servers.
368
369 =head1 RETURN VALUES
370
371 SSL_CTX_set_options() and SSL_set_options() return the new options bit-mask
372 after adding B<options>.
373
374 SSL_CTX_clear_options() and SSL_clear_options() return the new options bit-mask
375 after clearing B<options>.
376
377 SSL_CTX_get_options() and SSL_get_options() return the current bit-mask.
378
379 SSL_get_secure_renegotiation_support() returns 1 is the peer supports
380 secure renegotiation and 0 if it does not.
381
382 =head1 SEE ALSO
383
384 L<ssl(7)>, L<SSL_new(3)>, L<SSL_clear(3)>, L<SSL_shutdown(3)>
385 L<SSL_CTX_set_tmp_dh_callback(3)>,
386 L<SSL_CTX_set_min_proto_version(3)>,
387 L<openssl-dhparam(1)>
388
389 =head1 HISTORY
390
391 The attempt to always try to use secure renegotiation was added in
392 OpenSSL 0.9.8m.
393
394 The B<SSL_OP_PRIORITIZE_CHACHA> and B<SSL_OP_NO_RENEGOTIATION> options
395 were added in OpenSSL 1.1.1.
396
397 The B<SSL_OP_NO_EXTENDED_MASTER_SECRET> and B<SSL_OP_IGNORE_UNEXPECTED_EOF>
398 options were added in OpenSSL 3.0.
399
400 =head1 COPYRIGHT
401
402 Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved.
403
404 Licensed under the Apache License 2.0 (the "License").  You may not use
405 this file except in compliance with the License.  You can obtain a copy
406 in the file LICENSE in the source distribution or at
407 L<https://www.openssl.org/source/license.html>.
408
409 =cut