1SSL_CTX_SET_OPTIONS(3ossl) OpenSSL SSL_CTX_SET_OPTIONS(3ossl)
2
6 SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options,
7 SSL_clear_options, SSL_CTX_get_options, SSL_get_options,
8 SSL_get_secure_renegotiation_support - manipulate SSL options
9
11 #include <openssl/ssl.h>
12 uint64_t SSL_CTX_set_options(SSL_CTX *ctx, uint64_t options);
14 uint64_t SSL_set_options(SSL *ssl, uint64_t options);
15 uint64_t SSL_CTX_clear_options(SSL_CTX *ctx, uint64_t options);
17 uint64_t SSL_clear_options(SSL *ssl, uint64_t options);
18 uint64_t SSL_CTX_get_options(const SSL_CTX *ctx);
20 uint64_t SSL_get_options(const SSL *ssl);
21 long SSL_get_secure_renegotiation_support(SSL *ssl);
23
25 SSL_CTX_set_options() adds the options set via bit-mask in options to
26 ctx. Options already set before are not cleared!
27 SSL_set_options() adds the options set via bit-mask in options to ssl.
29 Options already set before are not cleared!
30 SSL_CTX_clear_options() clears the options set via bit-mask in options
32 to ctx.
33 SSL_clear_options() clears the options set via bit-mask in options to
35 ssl.
36 SSL_CTX_get_options() returns the options set for ctx.
38 SSL_get_options() returns the options set for ssl.
40 SSL_get_secure_renegotiation_support() indicates whether the peer
42 supports secure renegotiation. Note, this is implemented via a macro.
43
45 The behaviour of the SSL library can be changed by setting several
46 options. The options are coded as bit-masks and can be combined by a
47 bitwise or operation (|).
48 SSL_CTX_set_options() and SSL_set_options() affect the (external)
50 protocol behaviour of the SSL library. The (internal) behaviour of the
51 API can be changed by using the similar SSL_CTX_set_mode(3) and
52 SSL_set_mode() functions.
53 During a handshake, the option settings of the SSL object are used.
55 When a new SSL object is created from a context using SSL_new(), the
56 current option setting is copied. Changes to ctx do not affect already
57 created SSL objects. SSL_clear() does not affect the settings.
58 The following bug workaround options are available:
60 SSL_OP_CRYPTOPRO_TLSEXT_BUG
62 Add server-hello extension from the early version of cryptopro
63 draft when GOST ciphersuite is negotiated. Required for
64 interoperability with CryptoPro CSP 3.x.
65 SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
67 Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol
68 vulnerability affecting CBC ciphers, which cannot be handled by
69 some broken SSL implementations. This option has no effect for
70 connections using other ciphers.
71 SSL_OP_SAFARI_ECDHE_ECDSA_BUG
73 Don't prefer ECDHE-ECDSA ciphers when the client appears to be
74 Safari on OS X. OS X 10.8..10.8.3 has broken support for ECDHE-
75 ECDSA ciphers.
76 SSL_OP_TLSEXT_PADDING
78 Adds a padding extension to ensure the ClientHello size is never
79 between 256 and 511 bytes in length. This is needed as a workaround
80 for some implementations.
81 SSL_OP_ALL
83 All of the above bug workarounds.
84 It is usually safe to use SSL_OP_ALL to enable the bug workaround
86 options if compatibility with somewhat broken implementations is
87 desired.
88 The following modifying options are available:
90 SSL_OP_ALLOW_CLIENT_RENEGOTIATION
92 Client-initiated renegotiation is disabled by default. Use this
93 option to enable it.
94 SSL_OP_ALLOW_NO_DHE_KEX
96 In TLSv1.3 allow a non-(ec)dhe based key exchange mode on
97 resumption. This means that there will be no forward secrecy for
98 the resumed session.
99 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
101 Allow legacy insecure renegotiation between OpenSSL and unpatched
102 clients or servers. See the SECURE RENEGOTIATION section for more
103 details.
104 SSL_OP_CIPHER_SERVER_PREFERENCE
106 When choosing a cipher, use the server's preferences instead of the
107 client preferences. When not set, the SSL server will always follow
108 the clients preferences. When set, the SSL/TLS server will choose
109 following its own preferences.
110 SSL_OP_CISCO_ANYCONNECT
112 Use Cisco's version identifier of DTLS_BAD_VER when establishing a
113 DTLSv1 connection. Only available when using the deprecated
114 DTLSv1_client_method() API.
115 SSL_OP_CLEANSE_PLAINTEXT
117 By default TLS connections keep a copy of received plaintext
118 application data in a static buffer until it is overwritten by the
119 next portion of data. When enabling SSL_OP_CLEANSE_PLAINTEXT
120 deciphered application data is cleansed by calling
121 OPENSSL_cleanse(3) after passing data to the application. Data is
122 also cleansed when releasing the connection (e.g. SSL_free(3)).
123 Since OpenSSL only cleanses internal buffers, the application is
125 still responsible for cleansing all other buffers. Most notably,
126 this applies to buffers passed to functions like SSL_read(3),
127 SSL_peek(3) but also like SSL_write(3).
128 SSL_OP_COOKIE_EXCHANGE
130 Turn on Cookie Exchange as described in RFC4347 Section 4.2.1. Only
131 affects DTLS connections.
132 SSL_OP_DISABLE_TLSEXT_CA_NAMES
134 Disable TLS Extension CA Names. You may want to disable it for
135 security reasons or for compatibility with some Windows TLS
136 implementations crashing when this extension is larger than 1024
137 bytes.
138 SSL_OP_ENABLE_KTLS
140 Enable the use of kernel TLS. In order to benefit from kernel TLS
141 OpenSSL must have been compiled with support for it, and it must be
142 supported by the negotiated ciphersuites and extensions. The
143 specific ciphersuites and extensions that are supported may vary by
144 platform and kernel version.
145 The kernel TLS data-path implements the record layer, and the
147 encryption algorithm. The kernel will utilize the best hardware
148 available for encryption. Using the kernel data-path should reduce
149 the memory footprint of OpenSSL because no buffering is required.
150 Also, the throughput should improve because data copy is avoided
151 when user data is encrypted into kernel memory instead of the usual
152 encrypt then copy to kernel.
153 Kernel TLS might not support all the features of OpenSSL. For
155 instance, renegotiation, and setting the maximum fragment size is
156 not possible as of Linux 4.20.
157 Note that with kernel TLS enabled some cryptographic operations are
159 performed by the kernel directly and not via any available OpenSSL
160 Providers. This might be undesirable if, for example, the
161 application requires all cryptographic operations to be performed
162 by the FIPS provider.
163 SSL_OP_ENABLE_MIDDLEBOX_COMPAT
165 If set then dummy Change Cipher Spec (CCS) messages are sent in
166 TLSv1.3. This has the effect of making TLSv1.3 look more like
167 TLSv1.2 so that middleboxes that do not understand TLSv1.3 will not
168 drop the connection. Regardless of whether this option is set or
169 not CCS messages received from the peer will always be ignored in
170 TLSv1.3. This option is set by default. To switch it off use
171 SSL_clear_options(). A future version of OpenSSL may not set this
172 by default.
173 SSL_OP_IGNORE_UNEXPECTED_EOF
175 Some TLS implementations do not send the mandatory close_notify
176 alert on shutdown. If the application tries to wait for the
177 close_notify alert but the peer closes the connection without
178 sending it, an error is generated. When this option is enabled the
179 peer does not need to send the close_notify alert and a closed
180 connection will be treated as if the close_notify alert was
181 received.
182 You should only enable this option if the protocol running over TLS
184 can detect a truncation attack itself, and that the application is
185 checking for that truncation attack.
186 For more information on shutting down a connection, see
188 SSL_shutdown(3).
189 SSL_OP_LEGACY_SERVER_CONNECT
191 Allow legacy insecure renegotiation between OpenSSL and unpatched
192 servers only. See the SECURE RENEGOTIATION section for more
193 details.
194 SSL_OP_NO_ANTI_REPLAY
196 By default, when a server is configured for early data (i.e.,
197 max_early_data > 0), OpenSSL will switch on replay protection. See
198 SSL_read_early_data(3) for a description of the replay protection
199 feature. Anti-replay measures are required to comply with the
200 TLSv1.3 specification. Some applications may be able to mitigate
201 the replay risks in other ways and in such cases the built in
202 OpenSSL functionality is not required. Those applications can turn
203 this feature off by setting this option. This is a server-side
204 option only. It is ignored by clients.
205 SSL_OP_NO_COMPRESSION
207 Do not use compression even if it is supported. This option is set
208 by default. To switch it off use SSL_clear_options().
209 SSL_OP_NO_ENCRYPT_THEN_MAC
211 Normally clients and servers will transparently attempt to
212 negotiate the RFC7366 Encrypt-then-MAC option on TLS and DTLS
213 connection.
214 If this option is set, Encrypt-then-MAC is disabled. Clients will
216 not propose, and servers will not accept the extension.
217 SSL_OP_NO_EXTENDED_MASTER_SECRET
219 Normally clients and servers will transparently attempt to
220 negotiate the RFC7627 Extended Master Secret option on TLS and DTLS
221 connection.
222 If this option is set, Extended Master Secret is disabled. Clients
224 will not propose, and servers will not accept the extension.
225 SSL_OP_NO_QUERY_MTU
227 Do not query the MTU. Only affects DTLS connections.
228 SSL_OP_NO_RENEGOTIATION
230 Disable all renegotiation in TLSv1.2 and earlier. Do not send
231 HelloRequest messages, and ignore renegotiation requests via
232 ClientHello.
233 SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
235 When performing renegotiation as a server, always start a new
236 session (i.e., session resumption requests are only accepted in the
237 initial handshake). This option is not needed for clients.
238 SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2,
240 SSL_OP_NO_TLSv1_3, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2
241 These options turn off the SSLv3, TLSv1, TLSv1.1, TLSv1.2 or
242 TLSv1.3 protocol versions with TLS or the DTLSv1, DTLSv1.2 versions
243 with DTLS, respectively. As of OpenSSL 1.1.0, these options are
244 deprecated, use SSL_CTX_set_min_proto_version(3) and
245 SSL_CTX_set_max_proto_version(3) instead.
246 SSL_OP_NO_TICKET
248 SSL/TLS supports two mechanisms for resuming sessions: session ids
249 and stateless session tickets.
250 When using session ids a copy of the session information is cached
252 on the server and a unique id is sent to the client. When the
253 client wishes to resume it provides the unique id so that the
254 server can retrieve the session information from its cache.
255 When using stateless session tickets the server uses a session
257 ticket encryption key to encrypt the session information. This
258 encrypted data is sent to the client as a "ticket". When the client
259 wishes to resume it sends the encrypted data back to the server.
260 The server uses its key to decrypt the data and resume the session.
261 In this way the server can operate statelessly - no session
262 information needs to be cached locally.
263 The TLSv1.3 protocol only supports tickets and does not directly
265 support session ids. However, OpenSSL allows two modes of ticket
266 operation in TLSv1.3: stateful and stateless. Stateless tickets
267 work the same way as in TLSv1.2 and below. Stateful tickets mimic
268 the session id behaviour available in TLSv1.2 and below. The
269 session information is cached on the server and the session id is
270 wrapped up in a ticket and sent back to the client. When the client
271 wishes to resume, it presents a ticket in the same way as for
272 stateless tickets. The server can then extract the session id from
273 the ticket and retrieve the session information from its cache.
274 By default OpenSSL will use stateless tickets. The SSL_OP_NO_TICKET
276 option will cause stateless tickets to not be issued. In TLSv1.2
277 and below this means no ticket gets sent to the client at all. In
278 TLSv1.3 a stateful ticket will be sent. This is a server-side
279 option only.
280 In TLSv1.3 it is possible to suppress all tickets (stateful and
282 stateless) from being sent by calling SSL_CTX_set_num_tickets(3) or
283 SSL_set_num_tickets(3).
284 SSL_OP_PRIORITIZE_CHACHA
286 When SSL_OP_CIPHER_SERVER_PREFERENCE is set, temporarily
287 reprioritize ChaCha20-Poly1305 ciphers to the top of the server
288 cipher list if a ChaCha20-Poly1305 cipher is at the top of the
289 client cipher list. This helps those clients (e.g. mobile) use
290 ChaCha20-Poly1305 if that cipher is anywhere in the server cipher
291 list; but still allows other clients to use AES and other ciphers.
292 Requires SSL_OP_CIPHER_SERVER_PREFERENCE.
293 SSL_OP_TLS_ROLLBACK_BUG
295 Disable version rollback attack detection.
296 During the client key exchange, the client must send the same
298 information about acceptable SSL/TLS protocol levels as during the
299 first hello. Some clients violate this rule by adapting to the
300 server's answer. (Example: the client sends a SSLv2 hello and
301 accepts up to SSLv3.1=TLSv1, the server only understands up to
302 SSLv3. In this case the client must still use the same
303 SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with
304 respect to the server's answer and violate the version rollback
305 protection.)
306 The following options no longer have any effect but their identifiers
308 are retained for compatibility purposes:
309 SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
311 SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
312 SSL_OP_SSLEAY_080_CLIENT_DH_BUG
313 SSL_OP_TLS_D5_BUG
314 SSL_OP_TLS_BLOCK_PADDING_BUG
315 SSL_OP_MSIE_SSLV2_RSA_PADDING
316 SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
317 SSL_OP_MICROSOFT_SESS_ID_BUG
318 SSL_OP_NETSCAPE_CHALLENGE_BUG
319 SSL_OP_PKCS1_CHECK_1
320 SSL_OP_PKCS1_CHECK_2
321 SSL_OP_SINGLE_DH_USE
322 SSL_OP_SINGLE_ECDH_USE
323 SSL_OP_EPHEMERAL_RSA
324 SSL_OP_NETSCAPE_CA_DN_BUG
325 SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
326
328 OpenSSL always attempts to use secure renegotiation as described in
329 RFC5746. This counters the prefix attack described in CVE-2009-3555 and
330 elsewhere.
331 This attack has far reaching consequences which application writers
333 should be aware of. In the description below an implementation
334 supporting secure renegotiation is referred to as patched. A server not
335 supporting secure renegotiation is referred to as unpatched.
336 The following sections describe the operations permitted by OpenSSL's
338 secure renegotiation implementation.
339 Patched client and server
341 Connections and renegotiation are always permitted by OpenSSL
342 implementations.
343 Unpatched client and patched OpenSSL server
345 The initial connection succeeds but client renegotiation is denied by
346 the server with a no_renegotiation warning alert if TLS v1.0 is used or
347 a fatal handshake_failure alert in SSL v3.0.
348 If the patched OpenSSL server attempts to renegotiate a fatal
350 handshake_failure alert is sent. This is because the server code may be
351 unaware of the unpatched nature of the client.
352 If the option SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION is set then
354 renegotiation always succeeds.
355 Patched OpenSSL client and unpatched server
357 If the option SSL_OP_LEGACY_SERVER_CONNECT or
358 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION is set then initial
359 connections and renegotiation between patched OpenSSL clients and
360 unpatched servers succeeds. If neither option is set then initial
361 connections to unpatched servers will fail.
362 Setting the option SSL_OP_LEGACY_SERVER_CONNECT has security
364 implications; clients that are willing to connect to servers that do
365 not implement RFC 5746 secure renegotiation are subject to attacks such
366 as CVE-2009-3555.
367 OpenSSL client applications wishing to ensure they can connect to
369 unpatched servers should always set SSL_OP_LEGACY_SERVER_CONNECT
370 OpenSSL client applications that want to ensure they can not connect to
372 unpatched servers (and thus avoid any security issues) should always
373 clear SSL_OP_LEGACY_SERVER_CONNECT using SSL_CTX_clear_options() or
374 SSL_clear_options().
375 The difference between the SSL_OP_LEGACY_SERVER_CONNECT and
377 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION options is that
378 SSL_OP_LEGACY_SERVER_CONNECT enables initial connections and secure
379 renegotiation between OpenSSL clients and unpatched servers only, while
380 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION allows initial connections and
381 renegotiation between OpenSSL and unpatched clients or servers.
382
384 SSL_CTX_set_options() and SSL_set_options() return the new options bit-
385 mask after adding options.
386 SSL_CTX_clear_options() and SSL_clear_options() return the new options
388 bit-mask after clearing options.
389 SSL_CTX_get_options() and SSL_get_options() return the current bit-
391 mask.
392 SSL_get_secure_renegotiation_support() returns 1 is the peer supports
394 secure renegotiation and 0 if it does not.
395
397 ssl(7), SSL_new(3), SSL_clear(3), SSL_shutdown(3)
398 SSL_CTX_set_tmp_dh_callback(3), SSL_CTX_set_min_proto_version(3),
399 openssl-dhparam(1)
400
402 The attempt to always try to use secure renegotiation was added in
403 OpenSSL 0.9.8m.
404 The SSL_OP_PRIORITIZE_CHACHA and SSL_OP_NO_RENEGOTIATION options were
406 added in OpenSSL 1.1.1.
407 The SSL_OP_NO_EXTENDED_MASTER_SECRET and SSL_OP_IGNORE_UNEXPECTED_EOF
409 options were added in OpenSSL 3.0.
410 The SSL_OP_ constants and the corresponding parameter and return values
412 of the affected functions were changed to "uint64_t" type in OpenSSL
413 3.0. For that reason it is no longer possible use the SSL_OP_ macro
414 values in preprocessor "#if" conditions. However it is still possible
415 to test whether these macros are defined or not.
416
418 Copyright 2001-2023 The OpenSSL Project Authors. All Rights Reserved.
419 Licensed under the Apache License 2.0 (the "License"). You may not use
421 this file except in compliance with the License. You can obtain a copy
422 in the file LICENSE in the source distribution or at
423 <https://www.openssl.org/source/license.html>.
4243.1.1 2023-08-31 SSL_CTX_SET_OPTIONS(3ossl)