diff options
Diffstat (limited to 'deps/openssl/openssl/doc/ssl/SSL_CTX_set_options.pod')
| -rw-r--r-- | deps/openssl/openssl/doc/ssl/SSL_CTX_set_options.pod | 138 |
1 files changed, 45 insertions, 93 deletions
diff --git a/deps/openssl/openssl/doc/ssl/SSL_CTX_set_options.pod b/deps/openssl/openssl/doc/ssl/SSL_CTX_set_options.pod index 9a7e98c1d4..241aeb3cea 100644 --- a/deps/openssl/openssl/doc/ssl/SSL_CTX_set_options.pod +++ b/deps/openssl/openssl/doc/ssl/SSL_CTX_set_options.pod @@ -2,7 +2,9 @@ =head1 NAME -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 +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 =head1 SYNOPSIS @@ -21,8 +23,6 @@ SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options, SSL_clear_options, =head1 DESCRIPTION -Note: all these functions are implemented using macros. - SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>. Options already set before are not cleared! @@ -40,17 +40,18 @@ SSL_get_options() returns the options set for B<ssl>. SSL_get_secure_renegotiation_support() indicates whether the peer supports secure renegotiation. +Note, this is implemented via a macro. =head1 NOTES The behaviour of the SSL library can be changed by setting several options. -The options are coded as bitmasks and can be combined by a logical B<or> +The options are coded as bitmasks and can be combined by a bitwise B<or> operation (|). 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 -L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> and SSL_set_mode() functions. +L<SSL_CTX_set_mode(3)> and SSL_set_mode() functions. During a handshake, the option settings of the SSL object are used. When a new SSL object is created from a context using SSL_new(), the current @@ -61,25 +62,6 @@ The following B<bug workaround> options are available: =over 4 -=item SSL_OP_MICROSOFT_SESS_ID_BUG - -www.microsoft.com - when talking SSLv2, if session-id reuse is -performed, the session-id passed back in the server-finished message -is different from the one decided upon. - -=item SSL_OP_NETSCAPE_CHALLENGE_BUG - -Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte -challenge but then appears to only use 16 bytes when generating the -encryption keys. Using 16 bytes is ok but it should be ok to use 32. -According to the SSLv3 spec, one should use 32 bytes for the challenge -when operating in SSLv2/v3 compatibility mode, but as mentioned above, -this breaks this server so 16 bytes is the way to go. - -=item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG - -As of OpenSSL 0.9.8q and 1.0.0c, this option has no effect. - =item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG ... @@ -101,10 +83,6 @@ OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers. ... -=item SSL_OP_TLS_BLOCK_PADDING_BUG - -... - =item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol @@ -147,10 +125,10 @@ to the server's answer and violate the version rollback protection.) =item SSL_OP_SINGLE_DH_USE Always create a new key when using temporary/ephemeral DH parameters -(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>). +(see L<SSL_CTX_set_tmp_dh_callback(3)>). This option must be used to prevent small subgroup attacks, when the DH parameters were not generated using "strong" primes -(e.g. when using DSA-parameters, see L<dhparam(1)|dhparam(1)>). +(e.g. when using DSA-parameters, see L<dhparam(1)>). If "strong" primes were used, it is not strictly necessary to generate a new DH key during each handshake but it is also recommended. B<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever @@ -164,9 +142,8 @@ This option is no longer implemented and is treated as no op. 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 -preferences. When set, the SSLv3/TLSv1 server will choose following its -own preferences. Because of the different protocol, for SSLv2 the server -will send its list of preferences to the client and the client chooses. +preferences. When set, the SSL/TLS server will choose following its +own preferences. =item SSL_OP_PKCS1_CHECK_1 @@ -176,37 +153,16 @@ will send its list of preferences to the client and the client chooses. ... -=item SSL_OP_NETSCAPE_CA_DN_BUG - -If we accept a netscape connection, demand a client cert, have a -non-self-signed CA which does not have its CA in netscape, and the -browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta - -=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG - -... - -=item SSL_OP_NO_SSLv2 -Do not use the SSLv2 protocol. -As of OpenSSL 1.0.2g the B<SSL_OP_NO_SSLv2> option is set by default. +=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 -=item SSL_OP_NO_SSLv3 - -Do not use the SSLv3 protocol. -It is recommended that applications should set this option. - -=item SSL_OP_NO_TLSv1 - -Do not use the TLSv1 protocol. - -=item SSL_OP_NO_TLSv1_1 - -Do not use the TLSv1.1 protocol. - -=item SSL_OP_NO_TLSv1_2 - -Do not use the TLSv1.2 protocol. +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. =item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION @@ -233,17 +189,27 @@ 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. +=item SSL_OP_NO_ENCRYPT_THEN_MAC + +Normally clients and servers will transparently attempt to negotiate the +RFC7366 Encrypt-then-MAC option on TLS and DTLS connection. + +If this option is set, Encrypt-then-MAC is disabled. Clients will not +propose, and servers will not accept the extension. + +=item SSL_OP_NO_RENEGOTIATION + +Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest +messages, and ignore renegotiation requests via ClientHello. + =back =head1 SECURE RENEGOTIATION -OpenSSL 0.9.8m and later always attempts to use secure renegotiation as +OpenSSL always attempts to use secure renegotiation as described in RFC5746. This counters the prefix attack described in CVE-2009-3555 and elsewhere. -The deprecated and highly broken SSLv2 protocol does not support -renegotiation at all: its use is B<strongly> discouraged. - 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 @@ -269,14 +235,6 @@ unaware of the unpatched nature of the client. If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then renegotiation B<always> succeeds. -B<NB:> a bug in OpenSSL clients earlier than 0.9.8m (all of which are -unpatched) will result in the connection hanging if it receives a -B<no_renegotiation> alert. OpenSSL versions 0.9.8m and later will regard -a B<no_renegotiation> alert as fatal and respond with a fatal -B<handshake_failure> alert. This is because the OpenSSL API currently has -no provision to indicate to an application that a renegotiation attempt -was refused. - =head2 Patched OpenSSL client and unpatched server. If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or @@ -325,31 +283,25 @@ secure renegotiation and 0 if it does not. =head1 SEE ALSO -L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, -L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, -L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, -L<dhparam(1)|dhparam(1)> +L<ssl(3)>, L<SSL_new(3)>, L<SSL_clear(3)>, +L<SSL_CTX_set_tmp_dh_callback(3)>, +L<SSL_CTX_set_min_proto_version(3)>, +L<dhparam(1)> =head1 HISTORY -B<SSL_OP_CIPHER_SERVER_PREFERENCE> and -B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in -OpenSSL 0.9.7. +The attempt to always try to use secure renegotiation was added in +Openssl 0.9.8m. -B<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically -enabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL> -and must be explicitly set. +B<SSL_OP_NO_RENEGOTIATION> was added in OpenSSL 1.1.0h. -B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e. -Versions up to OpenSSL 0.9.6c do not include the countermeasure that -can be disabled with this option (in OpenSSL 0.9.6d, it was always -enabled). +=head1 COPYRIGHT -SSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL -0.9.8m. +Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. -B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>, B<SSL_OP_LEGACY_SERVER_CONNECT> -and the function SSL_get_secure_renegotiation_support() were first added in -OpenSSL 0.9.8m. +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 |