1SSL_CTX_SET_OPTIONS(3) OpenSSL SSL_CTX_SET_OPTIONS(3)
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 long SSL_CTX_set_options(SSL_CTX *ctx, long options);
14 long SSL_set_options(SSL *ssl, long options);
15 long SSL_CTX_clear_options(SSL_CTX *ctx, long options);
17 long SSL_clear_options(SSL *ssl, long options);
18 long SSL_CTX_get_options(SSL_CTX *ctx);
20 long SSL_get_options(SSL *ssl);
21 long SSL_get_secure_renegotiation_support(SSL *ssl);
23
25 SSL_CTX_set_options() adds the options set via bitmask in options to
26 ctx. Options already set before are not cleared!
27 SSL_set_options() adds the options set via bitmask in options to ssl.
29 Options already set before are not cleared!
30 SSL_CTX_clear_options() clears the options set via bitmask in options
32 to ctx.
33 SSL_clear_options() clears the options set via bitmask 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 bitmasks 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_SAFARI_ECDHE_ECDSA_BUG
62 Don't prefer ECDHE-ECDSA ciphers when the client appears to be
63 Safari on OS X. OS X 10.8..10.8.3 has broken support for ECDHE-
64 ECDSA ciphers.
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_TLSEXT_PADDING
73 Adds a padding extension to ensure the ClientHello size is never
74 between 256 and 511 bytes in length. This is needed as a workaround
75 for some implementations.
76 SSL_OP_ALL
78 All of the above bug workarounds plus SSL_OP_LEGACY_SERVER_CONNECT
79 as mentioned below.
80 It is usually safe to use SSL_OP_ALL to enable the bug workaround
82 options if compatibility with somewhat broken implementations is
83 desired.
84 The following modifying options are available:
86 SSL_OP_TLS_ROLLBACK_BUG
88 Disable version rollback attack detection.
89 During the client key exchange, the client must send the same
91 information about acceptable SSL/TLS protocol levels as during the
92 first hello. Some clients violate this rule by adapting to the
93 server's answer. (Example: the client sends a SSLv2 hello and
94 accepts up to SSLv3.1=TLSv1, the server only understands up to
95 SSLv3. In this case the client must still use the same
96 SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with
97 respect to the server's answer and violate the version rollback
98 protection.)
99 SSL_OP_CIPHER_SERVER_PREFERENCE
101 When choosing a cipher, use the server's preferences instead of the
102 client preferences. When not set, the SSL server will always follow
103 the clients preferences. When set, the SSL/TLS server will choose
104 following its own preferences.
105 SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2,
107 SSL_OP_NO_TLSv1_3, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2
108 These options turn off the SSLv3, TLSv1, TLSv1.1, TLSv1.2 or
109 TLSv1.3 protocol versions with TLS or the DTLSv1, DTLSv1.2 versions
110 with DTLS, respectively. As of OpenSSL 1.1.0, these options are
111 deprecated, use SSL_CTX_set_min_proto_version(3) and
112 SSL_CTX_set_max_proto_version(3) instead.
113 SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
115 When performing renegotiation as a server, always start a new
116 session (i.e., session resumption requests are only accepted in the
117 initial handshake). This option is not needed for clients.
118 SSL_OP_NO_COMPRESSION
120 Do not use compression even if it is supported.
121 SSL_OP_NO_QUERY_MTU
123 Do not query the MTU. Only affects DTLS connections.
124 SSL_OP_COOKIE_EXCHANGE
126 Turn on Cookie Exchange as described in RFC4347 Section 4.2.1. Only
127 affects DTLS connections.
128 SSL_OP_NO_TICKET
130 SSL/TLS supports two mechanisms for resuming sessions: session ids
131 and stateless session tickets.
132 When using session ids a copy of the session information is cached
134 on the server and a unique id is sent to the client. When the
135 client wishes to resume it provides the unique id so that the
136 server can retrieve the session information from its cache.
137 When using stateless session tickets the server uses a session
139 ticket encryption key to encrypt the session information. This
140 encrypted data is sent to the client as a "ticket". When the client
141 wishes to resume it sends the encrypted data back to the server.
142 The server uses its key to decrypt the data and resume the session.
143 In this way the server can operate statelessly - no session
144 information needs to be cached locally.
145 The TLSv1.3 protocol only supports tickets and does not directly
147 support session ids. However OpenSSL allows two modes of ticket
148 operation in TLSv1.3: stateful and stateless. Stateless tickets
149 work the same way as in TLSv1.2 and below. Stateful tickets mimic
150 the session id behaviour available in TLSv1.2 and below. The
151 session information is cached on the server and the session id is
152 wrapped up in a ticket and sent back to the client. When the client
153 wishes to resume, it presents a ticket in the same way as for
154 stateless tickets. The server can then extract the session id from
155 the ticket and retrieve the session information from its cache.
156 By default OpenSSL will use stateless tickets. The SSL_OP_NO_TICKET
158 option will cause stateless tickets to not be issued. In TLSv1.2
159 and below this means no ticket gets sent to the client at all. In
160 TLSv1.3 a stateful ticket will be sent. This is a server-side
161 option only.
162 In TLSv1.3 it is possible to suppress all tickets (stateful and
164 stateless) from being sent by calling SSL_CTX_set_num_tickets(3) or
165 SSL_set_num_tickets(3).
166 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
168 Allow legacy insecure renegotiation between OpenSSL and unpatched
169 clients or servers. See the SECURE RENEGOTIATION section for more
170 details.
171 SSL_OP_LEGACY_SERVER_CONNECT
173 Allow legacy insecure renegotiation between OpenSSL and unpatched
174 servers only: this option is currently set by default. See the
175 SECURE RENEGOTIATION section for more details.
176 SSL_OP_NO_ENCRYPT_THEN_MAC
178 Normally clients and servers will transparently attempt to
179 negotiate the RFC7366 Encrypt-then-MAC option on TLS and DTLS
180 connection.
181 If this option is set, Encrypt-then-MAC is disabled. Clients will
183 not propose, and servers will not accept the extension.
184 SSL_OP_NO_RENEGOTIATION
186 Disable all renegotiation in TLSv1.2 and earlier. Do not send
187 HelloRequest messages, and ignore renegotiation requests via
188 ClientHello.
189 SSL_OP_ALLOW_NO_DHE_KEX
191 In TLSv1.3 allow a non-(ec)dhe based key exchange mode on
192 resumption. This means that there will be no forward secrecy for
193 the resumed session.
194 SSL_OP_PRIORITIZE_CHACHA
196 When SSL_OP_CIPHER_SERVER_PREFERENCE is set, temporarily
197 reprioritize ChaCha20-Poly1305 ciphers to the top of the server
198 cipher list if a ChaCha20-Poly1305 cipher is at the top of the
199 client cipher list. This helps those clients (e.g. mobile) use
200 ChaCha20-Poly1305 if that cipher is anywhere in the server cipher
201 list; but still allows other clients to use AES and other ciphers.
202 Requires SSL_OP_CIPHER_SERVER_PREFERENCE.
203 SSL_OP_ENABLE_MIDDLEBOX_COMPAT
205 If set then dummy Change Cipher Spec (CCS) messages are sent in
206 TLSv1.3. This has the effect of making TLSv1.3 look more like
207 TLSv1.2 so that middleboxes that do not understand TLSv1.3 will not
208 drop the connection. Regardless of whether this option is set or
209 not CCS messages received from the peer will always be ignored in
210 TLSv1.3. This option is set by default. To switch it off use
211 SSL_clear_options(). A future version of OpenSSL may not set this
212 by default.
213 SSL_OP_NO_ANTI_REPLAY
215 By default, when a server is configured for early data (i.e.,
216 max_early_data > 0), OpenSSL will switch on replay protection. See
217 SSL_read_early_data(3) for a description of the replay protection
218 feature. Anti-replay measures are required to comply with the
219 TLSv1.3 specification. Some applications may be able to mitigate
220 the replay risks in other ways and in such cases the built in
221 OpenSSL functionality is not required. Those applications can turn
222 this feature off by setting this option. This is a server-side
223 opton only. It is ignored by clients.
224 The following options no longer have any effect but their identifiers
226 are retained for compatibility purposes:
227 SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
229 SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
230 SSL_OP_SSLEAY_080_CLIENT_DH_BUG
231 SSL_OP_TLS_D5_BUG
232 SSL_OP_TLS_BLOCK_PADDING_BUG
233 SSL_OP_MSIE_SSLV2_RSA_PADDING
234 SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
235 SSL_OP_MICROSOFT_SESS_ID_BUG
236 SSL_OP_NETSCAPE_CHALLENGE_BUG
237 SSL_OP_PKCS1_CHECK_1
238 SSL_OP_PKCS1_CHECK_2
239 SSL_OP_SINGLE_DH_USE
240 SSL_OP_SINGLE_ECDH_USE
241 SSL_OP_EPHEMERAL_RSA
242
244 OpenSSL always attempts to use secure renegotiation as described in
245 RFC5746. This counters the prefix attack described in CVE-2009-3555 and
246 elsewhere.
247 This attack has far reaching consequences which application writers
249 should be aware of. In the description below an implementation
250 supporting secure renegotiation is referred to as patched. A server not
251 supporting secure renegotiation is referred to as unpatched.
252 The following sections describe the operations permitted by OpenSSL's
254 secure renegotiation implementation.
255 Patched client and server
257 Connections and renegotiation are always permitted by OpenSSL
258 implementations.
259 Unpatched client and patched OpenSSL server
261 The initial connection succeeds but client renegotiation is denied by
262 the server with a no_renegotiation warning alert if TLS v1.0 is used or
263 a fatal handshake_failure alert in SSL v3.0.
264 If the patched OpenSSL server attempts to renegotiate a fatal
266 handshake_failure alert is sent. This is because the server code may be
267 unaware of the unpatched nature of the client.
268 If the option SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION is set then
270 renegotiation always succeeds.
271 Patched OpenSSL client and unpatched server.
273 If the option SSL_OP_LEGACY_SERVER_CONNECT or
274 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION is set then initial
275 connections and renegotiation between patched OpenSSL clients and
276 unpatched servers succeeds. If neither option is set then initial
277 connections to unpatched servers will fail.
278 The option SSL_OP_LEGACY_SERVER_CONNECT is currently set by default
280 even though it has security implications: otherwise it would be
281 impossible to connect to unpatched servers (i.e. all of them initially)
282 and this is clearly not acceptable. Renegotiation is permitted because
283 this does not add any additional security issues: during an attack
284 clients do not see any renegotiations anyway.
285 As more servers become patched the option SSL_OP_LEGACY_SERVER_CONNECT
287 will not be set by default in a future version of OpenSSL.
288 OpenSSL client applications wishing to ensure they can connect to
290 unpatched servers should always set SSL_OP_LEGACY_SERVER_CONNECT
291 OpenSSL client applications that want to ensure they can not connect to
293 unpatched servers (and thus avoid any security issues) should always
294 clear SSL_OP_LEGACY_SERVER_CONNECT using SSL_CTX_clear_options() or
295 SSL_clear_options().
296 The difference between the SSL_OP_LEGACY_SERVER_CONNECT and
298 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION options is that
299 SSL_OP_LEGACY_SERVER_CONNECT enables initial connections and secure
300 renegotiation between OpenSSL clients and unpatched servers only, while
301 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION allows initial connections and
302 renegotiation between OpenSSL and unpatched clients or servers.
303
305 SSL_CTX_set_options() and SSL_set_options() return the new options
306 bitmask after adding options.
307 SSL_CTX_clear_options() and SSL_clear_options() return the new options
309 bitmask after clearing options.
310 SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
312 SSL_get_secure_renegotiation_support() returns 1 is the peer supports
314 secure renegotiation and 0 if it does not.
315
317 ssl(7), SSL_new(3), SSL_clear(3), SSL_CTX_set_tmp_dh_callback(3),
318 SSL_CTX_set_min_proto_version(3), dhparam(1)
319
321 The attempt to always try to use secure renegotiation was added in
322 OpenSSL 0.9.8m.
323 The SSL_OP_PRIORITIZE_CHACHA and SSL_OP_NO_RENEGOTIATION options were
325 added in OpenSSL 1.1.1.
326
328 Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.
329 Licensed under the OpenSSL license (the "License"). You may not use
331 this file except in compliance with the License. You can obtain a copy
332 in the file LICENSE in the source distribution or at
333 <https://www.openssl.org/source/license.html>.
3341.1.1d 2019-10-03 SSL_CTX_SET_OPTIONS(3)