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 Note: all these functions are implemented using macros.
26 SSL_CTX_set_options() adds the options set via bitmask in options to
28 ctx. Options already set before are not cleared!
29 SSL_set_options() adds the options set via bitmask in options to ssl.
31 Options already set before are not cleared!
32 SSL_CTX_clear_options() clears the options set via bitmask in options
34 to ctx.
35 SSL_clear_options() clears the options set via bitmask in options to
37 ssl.
38 SSL_CTX_get_options() returns the options set for ctx.
40 SSL_get_options() returns the options set for ssl.
42 SSL_get_secure_renegotiation_support() indicates whether the peer
44 supports secure renegotiation.
45
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 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 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 The following bug workaround options are available:
62 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 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 SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
78 As of OpenSSL 0.9.8q and 1.0.0c, this option has no effect.
79 SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
81 ...
82 SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
84 ...
85 SSL_OP_MSIE_SSLV2_RSA_PADDING
87 As of OpenSSL 0.9.7h and 0.9.8a, this option has no effect.
88 SSL_OP_SSLEAY_080_CLIENT_DH_BUG
90 ...
91 SSL_OP_TLS_D5_BUG
93 ...
94 SSL_OP_TLS_BLOCK_PADDING_BUG
96 ...
97 SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
99 Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol
100 vulnerability affecting CBC ciphers, which cannot be handled by
101 some broken SSL implementations. This option has no effect for
102 connections using other ciphers.
103 SSL_OP_ALL
105 All of the above bug workarounds.
106 It is usually safe to use SSL_OP_ALL to enable the bug workaround
108 options if compatibility with somewhat broken implementations is
109 desired.
110 The following modifying options are available:
112 SSL_OP_TLS_ROLLBACK_BUG
114 Disable version rollback attack detection.
115 During the client key exchange, the client must send the same
117 information about acceptable SSL/TLS protocol levels as during the
118 first hello. Some clients violate this rule by adapting to the
119 server's answer. (Example: the client sends a SSLv2 hello and
120 accepts up to SSLv3.1=TLSv1, the server only understands up to
121 SSLv3. In this case the client must still use the same
122 SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with
123 respect to the server's answer and violate the version rollback
124 protection.)
125 SSL_OP_SINGLE_DH_USE
127 Always create a new key when using temporary/ephemeral DH
128 parameters (see SSL_CTX_set_tmp_dh_callback(3)). This option must
129 be used to prevent small subgroup attacks, when the DH parameters
130 were not generated using "strong" primes (e.g. when using DSA-
131 parameters, see dhparam(1)). If "strong" primes were used, it is
132 not strictly necessary to generate a new DH key during each
133 handshake but it is also recommended. SSL_OP_SINGLE_DH_USE should
134 therefore be enabled whenever temporary/ephemeral DH parameters are
135 used.
136 SSL_OP_EPHEMERAL_RSA
138 This option is no longer implemented and is treated as no op.
139 SSL_OP_CIPHER_SERVER_PREFERENCE
141 When choosing a cipher, use the server's preferences instead of the
142 client preferences. When not set, the SSL server will always follow
143 the clients preferences. When set, the SSLv3/TLSv1 server will
144 choose following its own preferences. Because of the different
145 protocol, for SSLv2 the server will send its list of preferences to
146 the client and the client chooses.
147 SSL_OP_PKCS1_CHECK_1
149 ...
150 SSL_OP_PKCS1_CHECK_2
152 ...
153 SSL_OP_NETSCAPE_CA_DN_BUG
155 If we accept a netscape connection, demand a client cert, have a
156 non-self-signed CA which does not have its CA in netscape, and the
157 browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta
158 SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
160 ...
161 SSL_OP_NO_SSLv2
163 Do not use the SSLv2 protocol.
164 SSL_OP_NO_SSLv3
166 Do not use the SSLv3 protocol.
167 SSL_OP_NO_TLSv1
169 Do not use the TLSv1 protocol.
170 SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
172 When performing renegotiation as a server, always start a new
173 session (i.e., session resumption requests are only accepted in the
174 initial handshake). This option is not needed for clients.
175 SSL_OP_NO_TICKET
177 Normally clients and servers will, where possible, transparently
178 make use of RFC4507bis tickets for stateless session resumption.
179 If this option is set this functionality is disabled and tickets
181 will not be used by clients or servers.
182 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
184 Allow legacy insecure renegotiation between OpenSSL and unpatched
185 clients or servers. See the SECURE RENEGOTIATION section for more
186 details.
187 SSL_OP_LEGACY_SERVER_CONNECT
189 Allow legacy insecure renegotiation between OpenSSL and unpatched
190 servers only: this option is currently set by default. See the
191 SECURE RENEGOTIATION section for more details.
192
194 OpenSSL 0.9.8m and later always attempts to use secure renegotiation as
195 described in RFC5746. This counters the prefix attack described in
196 CVE-2009-3555 and elsewhere.
197 The deprecated and highly broken SSLv2 protocol does not support
199 renegotiation at all: its use is strongly discouraged.
200 This attack has far reaching consequences which application writers
202 should be aware of. In the description below an implementation
203 supporting secure renegotiation is referred to as patched. A server not
204 supporting secure renegotiation is referred to as unpatched.
205 The following sections describe the operations permitted by OpenSSL's
207 secure renegotiation implementation.
208 Patched client and server
210 Connections and renegotiation are always permitted by OpenSSL
211 implementations.
212 Unpatched client and patched OpenSSL server
214 The initial connection suceeds but client renegotiation is denied by
215 the server with a no_renegotiation warning alert if TLS v1.0 is used or
216 a fatal handshake_failure alert in SSL v3.0.
217 If the patched OpenSSL server attempts to renegotiate a fatal
219 handshake_failure alert is sent. This is because the server code may be
220 unaware of the unpatched nature of the client.
221 If the option SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION is set then
223 renegotiation always succeeds.
224 NB: a bug in OpenSSL clients earlier than 0.9.8m (all of which are
226 unpatched) will result in the connection hanging if it receives a
227 no_renegotiation alert. OpenSSL versions 0.9.8m and later will regard a
228 no_renegotiation alert as fatal and respond with a fatal
229 handshake_failure alert. This is because the OpenSSL API currently has
230 no provision to indicate to an application that a renegotiation attempt
231 was refused.
232 Patched OpenSSL client and unpatched server.
234 If the option SSL_OP_LEGACY_SERVER_CONNECT or
235 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION is set then initial
236 connections and renegotiation between patched OpenSSL clients and
237 unpatched servers succeeds. If neither option is set then initial
238 connections to unpatched servers will fail.
239 The option SSL_OP_LEGACY_SERVER_CONNECT is currently set by default
241 even though it has security implications: otherwise it would be
242 impossible to connect to unpatched servers (i.e. all of them initially)
243 and this is clearly not acceptable. Renegotiation is permitted because
244 this does not add any additional security issues: during an attack
245 clients do not see any renegotiations anyway.
246 As more servers become patched the option SSL_OP_LEGACY_SERVER_CONNECT
248 will not be set by default in a future version of OpenSSL.
249 OpenSSL client applications wishing to ensure they can connect to
251 unpatched servers should always set SSL_OP_LEGACY_SERVER_CONNECT
252 OpenSSL client applications that want to ensure they can not connect to
254 unpatched servers (and thus avoid any security issues) should always
255 clear SSL_OP_LEGACY_SERVER_CONNECT using SSL_CTX_clear_options() or
256 SSL_clear_options().
257 The difference between the SSL_OP_LEGACY_SERVER_CONNECT and
259 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION options is that
260 SSL_OP_LEGACY_SERVER_CONNECT enables initial connections and secure
261 renegotiation between OpenSSL clients and unpatched servers only, while
262 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION allows initial connections and
263 renegotiation between OpenSSL and unpatched clients or servers.
264
266 SSL_CTX_set_options() and SSL_set_options() return the new options
267 bitmask after adding options.
268 SSL_CTX_clear_options() and SSL_clear_options() return the new options
270 bitmask after clearing options.
271 SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
273 SSL_get_secure_renegotiation_support() returns 1 is the peer supports
275 secure renegotiation and 0 if it does not.
276
278 ssl(3), SSL_new(3), SSL_clear(3), SSL_CTX_set_tmp_dh_callback(3),
279 SSL_CTX_set_tmp_rsa_callback(3), dhparam(1)
280
282 SSL_OP_CIPHER_SERVER_PREFERENCE and
283 SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION have been added in
284 OpenSSL 0.9.7.
285 SSL_OP_TLS_ROLLBACK_BUG has been added in OpenSSL 0.9.6 and was
287 automatically enabled with SSL_OP_ALL. As of 0.9.7, it is no longer
288 included in SSL_OP_ALL and must be explicitly set.
289 SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS has been added in OpenSSL 0.9.6e.
291 Versions up to OpenSSL 0.9.6c do not include the countermeasure that
292 can be disabled with this option (in OpenSSL 0.9.6d, it was always
293 enabled).
294 SSL_CTX_clear_options() and SSL_clear_options() were first added in
296 OpenSSL 0.9.8m.
297 SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION, SSL_OP_LEGACY_SERVER_CONNECT
299 and the function SSL_get_secure_renegotiation_support() were first
300 added in OpenSSL 0.9.8m.
3011.0.1e 2017-03-22 SSL_CTX_set_options(3)