SSL_CTX_set_options.pod 9.6 KB
Newer Older
1 2 3 4
=pod

=head1 NAME

5 6 7
SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options,
SSL_clear_options, SSL_CTX_get_options, SSL_get_options,
SSL_get_secure_renegotiation_support - manipulate SSL options
8 9 10 11 12 13 14 15

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 long SSL_CTX_set_options(SSL_CTX *ctx, long options);
 long SSL_set_options(SSL *ssl, long options);

16 17 18
 long SSL_CTX_clear_options(SSL_CTX *ctx, long options);
 long SSL_clear_options(SSL *ssl, long options);

19 20 21
 long SSL_CTX_get_options(SSL_CTX *ctx);
 long SSL_get_options(SSL *ssl);

22 23
 long SSL_get_secure_renegotiation_support(SSL *ssl);

24 25 26
=head1 DESCRIPTION

SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>.
27
Options already set before are not cleared!
28 29

SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>.
30
Options already set before are not cleared!
31

32 33 34 35 36
SSL_CTX_clear_options() clears the options set via bitmask in B<options>
to B<ctx>.

SSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>.

37 38 39 40
SSL_CTX_get_options() returns the options set for B<ctx>.

SSL_get_options() returns the options set for B<ssl>.

41 42
SSL_get_secure_renegotiation_support() indicates whether the peer supports
secure renegotiation.
43
Note, this is implemented via a macro.
44

45 46 47
=head1 NOTES

The behaviour of the SSL library can be changed by setting several options.
48
The options are coded as bitmasks and can be combined by a bitwise B<or>
49
operation (|).
50

51 52 53
SSL_CTX_set_options() and SSL_set_options() affect the (external)
protocol behaviour of the SSL library. The (internal) behaviour of
the API can be changed by using the similar
R
Rich Salz 已提交
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 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
a new SSL object is created from a context using SSL_new(), the current
option setting is copied. Changes to B<ctx> do not affect already created
SSL objects. SSL_clear() does not affect the settings.

The following B<bug workaround> options are available:

=over 4

=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG

...

=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER

...

73
=item SSL_OP_SAFARI_ECDHE_ECDSA_BUG
74

75 76
Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X.
OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers.
77 78 79 80 81 82 83 84 85

=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG

...

=item SSL_OP_TLS_D5_BUG

...

86 87 88 89 90 91 92
=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS

Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol
vulnerability affecting CBC ciphers, which cannot be handled by some
broken SSL implementations.  This option has no effect for connections
using other ciphers.

93 94 95 96 97 98
=item SSL_OP_TLSEXT_PADDING

Adds a padding extension to ensure the ClientHello size is never between
256 and 511 bytes in length. This is needed as a workaround for some
implementations.

99 100 101 102 103 104
=item SSL_OP_ALL

All of the above bug workarounds.

=back

105 106 107
It is usually safe to use B<SSL_OP_ALL> to enable the bug workaround
options if compatibility with somewhat broken implementations is
desired.
108 109 110 111 112

The following B<modifying> options are available:

=over 4

113 114 115 116 117 118 119 120 121 122 123 124
=item SSL_OP_TLS_ROLLBACK_BUG

Disable version rollback attack detection.

During the client key exchange, the client must send the same information
about acceptable SSL/TLS protocol levels as during the first hello. Some
clients violate this rule by adapting to the server's answer. (Example:
the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
only understands up to SSLv3. In this case the client must still use the
same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
to the server's answer and violate the version rollback protection.)

125 126
=item SSL_OP_SINGLE_DH_USE

127
Always create a new key when using temporary/ephemeral DH parameters
R
Rich Salz 已提交
128
(see L<SSL_CTX_set_tmp_dh_callback(3)>).
129 130
This option must be used to prevent small subgroup attacks, when
the DH parameters were not generated using "strong" primes
R
Rich Salz 已提交
131
(e.g. when using DSA-parameters, see L<dhparam(1)>).
132
If "strong" primes were used, it is not strictly necessary to generate
U
ispell  
Ulf Möller 已提交
133
a new DH key during each handshake but it is also recommended.
134
B<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever
135
temporary/ephemeral DH parameters are used.
136 137 138

=item SSL_OP_EPHEMERAL_RSA

139
This option is no longer implemented and is treated as no op.
140

141 142 143 144
=item SSL_OP_CIPHER_SERVER_PREFERENCE

When choosing a cipher, use the server's preferences instead of the client
preferences. When not set, the SSL server will always follow the clients
M
Matt Caswell 已提交
145 146
preferences. When set, the SSL/TLS server will choose following its
own preferences.
147

148 149 150 151 152 153 154 155 156
=item SSL_OP_PKCS1_CHECK_1

...

=item SSL_OP_PKCS1_CHECK_2

...


157 158
=item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1,
SSL_OP_NO_TLSv1_2, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2
159

160 161 162 163 164 165
These options turn off the SSLv3, TLSv1, TLSv1.1 or TLSv1.2 protocol
versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS,
respectively.
As of OpenSSL 1.1.0, these options are deprecated, use
L<SSL_CTX_set_min_proto_version(3)> and
L<SSL_CTX_set_max_proto_version(3)> instead.
166

167 168 169 170
=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION

When performing renegotiation as a server, always start a new session
(i.e., session resumption requests are only accepted in the initial
171
handshake). This option is not needed for clients.
172

173 174 175 176 177 178 179 180
=item SSL_OP_NO_TICKET

Normally clients and servers will, where possible, transparently make use
of RFC4507bis tickets for stateless session resumption.

If this option is set this functionality is disabled and tickets will
not be used by clients or servers.

D
Dr. Stephen Henson 已提交
181
=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
182

D
Dr. Stephen Henson 已提交
183 184 185 186 187 188 189 190
Allow legacy insecure renegotiation between OpenSSL and unpatched clients or
servers. See the B<SECURE RENEGOTIATION> section for more details.

=item SSL_OP_LEGACY_SERVER_CONNECT

Allow legacy insecure renegotiation between OpenSSL and unpatched servers
B<only>: this option is currently set by default. See the
B<SECURE RENEGOTIATION> section for more details.
191

192 193
=back

194 195
=head1 SECURE RENEGOTIATION

R
Rich Salz 已提交
196
OpenSSL always attempts to use secure renegotiation as
197 198
described in RFC5746. This counters the prefix attack described in
CVE-2009-3555 and elsewhere.
199 200 201 202 203 204

This attack has far reaching consequences which application writers should be
aware of. In the description below an implementation supporting secure
renegotiation is referred to as I<patched>. A server not supporting secure
renegotiation is referred to as I<unpatched>.

D
Dr. Stephen Henson 已提交
205 206 207
The following sections describe the operations permitted by OpenSSL's secure
renegotiation implementation.

208
=head2 Patched client and server
209

D
Dr. Stephen Henson 已提交
210
Connections and renegotiation are always permitted by OpenSSL implementations.
211

D
Dr. Stephen Henson 已提交
212
=head2 Unpatched client and patched OpenSSL server
D
Dr. Stephen Henson 已提交
213

214
The initial connection succeeds but client renegotiation is denied by the
D
Dr. Stephen Henson 已提交
215
server with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal
216 217
B<handshake_failure> alert in SSL v3.0.

D
Dr. Stephen Henson 已提交
218 219 220
If the patched OpenSSL server attempts to renegotiate a fatal
B<handshake_failure> alert is sent. This is because the server code may be
unaware of the unpatched nature of the client.
221 222 223 224

If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then
renegotiation B<always> succeeds.

D
Dr. Stephen Henson 已提交
225
=head2 Patched OpenSSL client and unpatched server.
226

D
Dr. Stephen Henson 已提交
227 228
If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or
B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections
229
and renegotiation between patched OpenSSL clients and unpatched servers
D
Dr. Stephen Henson 已提交
230 231
succeeds. If neither option is set then initial connections to unpatched
servers will fail.
232

D
Dr. Stephen Henson 已提交
233 234 235 236 237 238
The option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even
though it has security implications: otherwise it would be impossible to
connect to unpatched servers (i.e. all of them initially) and this is clearly
not acceptable. Renegotiation is permitted because this does not add any
additional security issues: during an attack clients do not see any
renegotiations anyway.
239 240 241 242

As more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will
B<not> be set by default in a future version of OpenSSL.

D
Dr. Stephen Henson 已提交
243 244
OpenSSL client applications wishing to ensure they can connect to unpatched
servers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT>
245

D
Dr. Stephen Henson 已提交
246 247
OpenSSL client applications that want to ensure they can B<not> connect to
unpatched servers (and thus avoid any security issues) should always B<clear>
248 249
B<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or
SSL_clear_options().
250

D
Dr. Stephen Henson 已提交
251 252 253 254 255 256
The difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and
B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that
B<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure
renegotiation between OpenSSL clients and unpatched servers B<only>, while
B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections
and renegotiation between OpenSSL and unpatched clients or servers.
257

258 259 260 261 262
=head1 RETURN VALUES

SSL_CTX_set_options() and SSL_set_options() return the new options bitmask
after adding B<options>.

263 264 265
SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask
after clearing B<options>.

266 267
SSL_CTX_get_options() and SSL_get_options() return the current bitmask.

268 269 270
SSL_get_secure_renegotiation_support() returns 1 is the peer supports
secure renegotiation and 0 if it does not.

271 272
=head1 SEE ALSO

R
Rich Salz 已提交
273 274
L<ssl(3)>, L<SSL_new(3)>, L<SSL_clear(3)>,
L<SSL_CTX_set_tmp_dh_callback(3)>,
275
L<SSL_CTX_set_min_proto_version(3)>,
R
Rich Salz 已提交
276
L<dhparam(1)>
277 278 279

=head1 HISTORY

R
Rich Salz 已提交
280 281
The attempt to always try to use secure renegotiation was added in
Openssl 0.9.8m.
282

283
=cut
R
Rich Salz 已提交
284 285 286 287 288 289 290 291 292 293 294

=head1 COPYRIGHT

Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut