1SSL_CTX_set_options(3)              OpenSSL             SSL_CTX_set_options(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

25       Note: all these functions are implemented using macros.
26
27       SSL_CTX_set_options() adds the options set via bitmask in options to
28       ctx.  Options already set before are not cleared!
29
30       SSL_set_options() adds the options set via bitmask in options to ssl.
31       Options already set before are not cleared!
32
33       SSL_CTX_clear_options() clears the options set via bitmask in options
34       to ctx.
35
36       SSL_clear_options() clears the options set via bitmask in options to
37       ssl.
38
39       SSL_CTX_get_options() returns the options set for ctx.
40
41       SSL_get_options() returns the options set for ssl.
42
43       SSL_get_secure_renegotiation_support() indicates whether the peer
44       supports secure renegotiation.
45

NOTES

47       The behaviour of the SSL library can be changed by setting several
48       options.  The options are coded as bitmasks and can be combined by a
49       logical or 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 the
53       API can be changed by using the similar SSL_CTX_set_mode(3) and
54       SSL_set_mode() functions.
55
56       During a handshake, the option settings of the SSL object are used.
57       When a new SSL object is created from a context using SSL_new(), the
58       current option setting is copied. Changes to ctx do not affect already
59       created SSL objects. SSL_clear() does not affect the settings.
60
61       The following bug workaround options are available:
62
63       SSL_OP_MICROSOFT_SESS_ID_BUG
64           www.microsoft.com - when talking SSLv2, if session-id reuse is
65           performed, the session-id passed back in the server-finished
66           message is different from the one decided upon.
67
68       SSL_OP_NETSCAPE_CHALLENGE_BUG
69           Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte
70           challenge but then appears to only use 16 bytes when generating the
71           encryption keys.  Using 16 bytes is ok but it should be ok to use
72           32.  According to the SSLv3 spec, one should use 32 bytes for the
73           challenge when operating in SSLv2/v3 compatibility mode, but as
74           mentioned above, this breaks this server so 16 bytes is the way to
75           go.
76
77       SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
78           As of OpenSSL 0.9.8q and 1.0.0c, this option has no effect.
79
80       SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
81           ...
82
83       SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
84           ...
85
86       SSL_OP_SAFARI_ECDHE_ECDSA_BUG
87           Don't prefer ECDHE-ECDSA ciphers when the client appears to be
88           Safari on OS X.  OS X 10.8..10.8.3 has broken support for ECDHE-
89           ECDSA ciphers.
90
91       SSL_OP_SSLEAY_080_CLIENT_DH_BUG
92           ...
93
94       SSL_OP_TLS_D5_BUG
95           ...
96
97       SSL_OP_TLS_BLOCK_PADDING_BUG
98           ...
99
100       SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
101           Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol
102           vulnerability affecting CBC ciphers, which cannot be handled by
103           some broken SSL implementations.  This option has no effect for
104           connections using other ciphers.
105
106       SSL_OP_TLSEXT_PADDING
107           Adds a padding extension to ensure the ClientHello size is never
108           between 256 and 511 bytes in length. This is needed as a workaround
109           for some implementations.
110
111       SSL_OP_ALL
112           All of the above bug workarounds.
113
114       It is usually safe to use SSL_OP_ALL to enable the bug workaround
115       options if compatibility with somewhat broken implementations is
116       desired.
117
118       The following modifying options are available:
119
120       SSL_OP_TLS_ROLLBACK_BUG
121           Disable version rollback attack detection.
122
123           During the client key exchange, the client must send the same
124           information about acceptable SSL/TLS protocol levels as during the
125           first hello. Some clients violate this rule by adapting to the
126           server's answer. (Example: the client sends a SSLv2 hello and
127           accepts up to SSLv3.1=TLSv1, the server only understands up to
128           SSLv3. In this case the client must still use the same
129           SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with
130           respect to the server's answer and violate the version rollback
131           protection.)
132
133       SSL_OP_SINGLE_DH_USE
134           Always create a new key when using temporary/ephemeral DH
135           parameters (see SSL_CTX_set_tmp_dh_callback(3)).  This option must
136           be used to prevent small subgroup attacks, when the DH parameters
137           were not generated using "strong" primes (e.g. when using DSA-
138           parameters, see dhparam(1)).  If "strong" primes were used, it is
139           not strictly necessary to generate a new DH key during each
140           handshake but it is also recommended.  SSL_OP_SINGLE_DH_USE should
141           therefore be enabled whenever temporary/ephemeral DH parameters are
142           used.
143
144       SSL_OP_EPHEMERAL_RSA
145           This option is no longer implemented and is treated as no op.
146
147       SSL_OP_CIPHER_SERVER_PREFERENCE
148           When choosing a cipher, use the server's preferences instead of the
149           client preferences. When not set, the SSL server will always follow
150           the clients preferences. When set, the SSLv3/TLSv1 server will
151           choose following its own preferences. Because of the different
152           protocol, for SSLv2 the server will send its list of preferences to
153           the client and the client chooses.
154
155       SSL_OP_PKCS1_CHECK_1
156           ...
157
158       SSL_OP_PKCS1_CHECK_2
159           ...
160
161       SSL_OP_NETSCAPE_CA_DN_BUG
162           If we accept a netscape connection, demand a client cert, have a
163           non-self-signed CA which does not have its CA in netscape, and the
164           browser has a cert, it will crash/hang.  Works for 3.x and 4.xbeta
165
166       SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
167           ...
168
169       SSL_OP_NO_SSLv2
170           Do not use the SSLv2 protocol.  As of OpenSSL 1.0.2g the
171           SSL_OP_NO_SSLv2 option is set by default.
172
173       SSL_OP_NO_SSLv3
174           Do not use the SSLv3 protocol.  It is recommended that applications
175           should set this option.
176
177       SSL_OP_NO_TLSv1
178           Do not use the TLSv1 protocol.
179
180       SSL_OP_NO_TLSv1_1
181           Do not use the TLSv1.1 protocol.
182
183       SSL_OP_NO_TLSv1_2
184           Do not use the TLSv1.2 protocol.
185
186       SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
187           When performing renegotiation as a server, always start a new
188           session (i.e., session resumption requests are only accepted in the
189           initial handshake). This option is not needed for clients.
190
191       SSL_OP_NO_TICKET
192           Normally clients and servers will, where possible, transparently
193           make use of RFC4507bis tickets for stateless session resumption.
194
195           If this option is set this functionality is disabled and tickets
196           will not be used by clients or servers.
197
198       SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
199           Allow legacy insecure renegotiation between OpenSSL and unpatched
200           clients or servers. See the SECURE RENEGOTIATION section for more
201           details.
202
203       SSL_OP_LEGACY_SERVER_CONNECT
204           Allow legacy insecure renegotiation between OpenSSL and unpatched
205           servers only: this option is currently set by default. See the
206           SECURE RENEGOTIATION section for more details.
207

SECURE RENEGOTIATION

209       OpenSSL 0.9.8m and later always attempts to use secure renegotiation as
210       described in RFC5746. This counters the prefix attack described in
211       CVE-2009-3555 and elsewhere.
212
213       The deprecated and highly broken SSLv2 protocol does not support
214       renegotiation at all: its use is strongly discouraged.
215
216       This attack has far reaching consequences which application writers
217       should be aware of. In the description below an implementation
218       supporting secure renegotiation is referred to as patched. A server not
219       supporting secure renegotiation is referred to as unpatched.
220
221       The following sections describe the operations permitted by OpenSSL's
222       secure renegotiation implementation.
223
224   Patched client and server
225       Connections and renegotiation are always permitted by OpenSSL
226       implementations.
227
228   Unpatched client and patched OpenSSL server
229       The initial connection succeeds but client renegotiation is denied by
230       the server with a no_renegotiation warning alert if TLS v1.0 is used or
231       a fatal handshake_failure alert in SSL v3.0.
232
233       If the patched OpenSSL server attempts to renegotiate a fatal
234       handshake_failure alert is sent. This is because the server code may be
235       unaware of the unpatched nature of the client.
236
237       If the option SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION is set then
238       renegotiation always succeeds.
239
240       NB: a bug in OpenSSL clients earlier than 0.9.8m (all of which are
241       unpatched) will result in the connection hanging if it receives a
242       no_renegotiation alert. OpenSSL versions 0.9.8m and later will regard a
243       no_renegotiation alert as fatal and respond with a fatal
244       handshake_failure alert. This is because the OpenSSL API currently has
245       no provision to indicate to an application that a renegotiation attempt
246       was refused.
247
248   Patched OpenSSL client and unpatched server.
249       If the option SSL_OP_LEGACY_SERVER_CONNECT or
250       SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION is set then initial
251       connections and renegotiation between patched OpenSSL clients and
252       unpatched servers succeeds. If neither option is set then initial
253       connections to unpatched servers will fail.
254
255       The option SSL_OP_LEGACY_SERVER_CONNECT is currently set by default
256       even though it has security implications: otherwise it would be
257       impossible to connect to unpatched servers (i.e. all of them initially)
258       and this is clearly not acceptable. Renegotiation is permitted because
259       this does not add any additional security issues: during an attack
260       clients do not see any renegotiations anyway.
261
262       As more servers become patched the option SSL_OP_LEGACY_SERVER_CONNECT
263       will not be set by default in a future version of OpenSSL.
264
265       OpenSSL client applications wishing to ensure they can connect to
266       unpatched servers should always set SSL_OP_LEGACY_SERVER_CONNECT
267
268       OpenSSL client applications that want to ensure they can not connect to
269       unpatched servers (and thus avoid any security issues) should always
270       clear SSL_OP_LEGACY_SERVER_CONNECT using SSL_CTX_clear_options() or
271       SSL_clear_options().
272
273       The difference between the SSL_OP_LEGACY_SERVER_CONNECT and
274       SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION options is that
275       SSL_OP_LEGACY_SERVER_CONNECT enables initial connections and secure
276       renegotiation between OpenSSL clients and unpatched servers only, while
277       SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION allows initial connections and
278       renegotiation between OpenSSL and unpatched clients or servers.
279

RETURN VALUES

281       SSL_CTX_set_options() and SSL_set_options() return the new options
282       bitmask after adding options.
283
284       SSL_CTX_clear_options() and SSL_clear_options() return the new options
285       bitmask after clearing options.
286
287       SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
288
289       SSL_get_secure_renegotiation_support() returns 1 is the peer supports
290       secure renegotiation and 0 if it does not.
291

SEE ALSO

293       ssl(3), SSL_new(3), SSL_clear(3), SSL_CTX_set_tmp_dh_callback(3),
294       SSL_CTX_set_tmp_rsa_callback(3), dhparam(1)
295

HISTORY

297       SSL_OP_CIPHER_SERVER_PREFERENCE and
298       SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION have been added in
299       OpenSSL 0.9.7.
300
301       SSL_OP_TLS_ROLLBACK_BUG has been added in OpenSSL 0.9.6 and was
302       automatically enabled with SSL_OP_ALL. As of 0.9.7, it is no longer
303       included in SSL_OP_ALL and must be explicitly set.
304
305       SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS has been added in OpenSSL 0.9.6e.
306       Versions up to OpenSSL 0.9.6c do not include the countermeasure that
307       can be disabled with this option (in OpenSSL 0.9.6d, it was always
308       enabled).
309
310       SSL_CTX_clear_options() and SSL_clear_options() were first added in
311       OpenSSL 0.9.8m.
312
313       SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION, SSL_OP_LEGACY_SERVER_CONNECT
314       and the function SSL_get_secure_renegotiation_support() were first
315       added in OpenSSL 0.9.8m.
316
317
318
3191.0.2o                            2020-08-01            SSL_CTX_set_options(3)
Impressum