X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fssl%2FSSL_CTX_set_options.pod;h=635b470e12453c1c7f8ed74a76374fb349e26d6d;hp=65062ad68cf53450e2e816d07d14c74e853f65b4;hb=ba6017a19346a169ca09bb67427ccf6fc56af0af;hpb=b5071dc2f67d7667ab3cbbe50a30342f999b896a diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod index 65062ad68c..635b470e12 100644 --- a/doc/ssl/SSL_CTX_set_options.pod +++ b/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 to B. Options already set before are not cleared! @@ -40,6 +40,7 @@ SSL_get_options() returns the options set for B. SSL_get_secure_renegotiation_support() indicates whether the peer supports secure renegotiation. +Note, this is implemented via a macro. =head1 NOTES @@ -50,7 +51,7 @@ 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 and SSL_set_mode() functions. +L 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 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). +(see L). 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). +(e.g. when using DSA-parameters, see L). 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 should therefore be enabled whenever @@ -158,23 +136,14 @@ temporary/ephemeral DH parameters are used. =item SSL_OP_EPHEMERAL_RSA -Always use ephemeral (temporary) RSA key when doing RSA operations -(see L). -According to the specifications this is only done, when a RSA key -can only be used for signature operations (namely under export ciphers -with restricted RSA keylength). By setting this option, ephemeral -RSA keys are always used. This option breaks compatibility with the -SSL/TLS specifications and may lead to interoperability problems with -clients and should therefore never be used. Ciphers with DHE (ephemeral -Diffie-Hellman) key exchange should be used instead. +This option is no longer implemented and is treated as no op. =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 -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 @@ -184,27 +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_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_NETSCAPE_DEMO_CIPHER_CHANGE_BUG - -... - -=item SSL_OP_NO_SSLv2 - -Do not use the SSLv2 protocol. - -=item SSL_OP_NO_SSLv3 - -Do not use the SSLv3 protocol. - -=item SSL_OP_NO_TLSv1 - -Do not use the TLSv1 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 and +L instead. =item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION @@ -235,13 +193,10 @@ B section for more details. =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 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. A server not supporting secure @@ -267,14 +222,6 @@ unaware of the unpatched nature of the client. If the option B is set then renegotiation B succeeds. -B 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 alert. OpenSSL versions 0.9.8m and later will regard -a B alert as fatal and respond with a fatal -B 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 or @@ -323,31 +270,23 @@ secure renegotiation and 0 if it does not. =head1 SEE ALSO -L, L, L, -L, -L, -L +L, L, L, +L, +L, +L =head1 HISTORY -B and -B have been added in -OpenSSL 0.9.7. - -B has been added in OpenSSL 0.9.6 and was automatically -enabled with B. As of 0.9.7, it is no longer included in B -and must be explicitly set. +The attempt to always try to use secure renegotiation was added in +Openssl 0.9.8m. -B 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-2016 The OpenSSL Project Authors. All Rights Reserved. -B, B -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. =cut