Add support for minimum and maximum protocol version

Reviewed-by: Viktor Dukhovni <viktor@openssl.org>

4 files changed, 186 insertions, 65 deletions

diff --git a/doc/ssl/SSL_CONF_cmd.pod b/doc/ssl/SSL_CONF_cmd.pod
index bebd20485c..cfac7e22d2 100644
--- a/doc/ssl/SSL_CONF_cmd.pod
+++ b/doc/ssl/SSL_CONF_cmd.pod
@@ -74,7 +74,7 @@ B<prime256v1>). Curve names are case sensitive.
 
 =item B<-named_curve>
 
-This sets the temporary curve used for ephemeral ECDH modes. Only used by 
+This sets the temporary curve used for ephemeral ECDH modes. Only used by
 servers
 
 The B<value> argument is a curve name or the special value B<auto> which
@@ -85,7 +85,7 @@ can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
 =item B<-cipher>
 
 Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
-currently not performed unless a B<SSL> or B<SSL_CTX> structure is 
+currently not performed unless a B<SSL> or B<SSL_CTX> structure is
 associated with B<cctx>.
 
 =item B<-cert>
@@ -109,9 +109,14 @@ Attempts to use the file B<value> as the set of temporary DH parameters for
 the appropriate context. This option is only supported if certificate
 operations are permitted.
 
+=item B<-min_protocol>, B<-max_protocol>
+
+Sets the minimum and maximum supported protocol.
+Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>, B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+
 =item B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
 
-Disables protocol support for SSLv3, TLS 1.0, TLS 1.1 or TLS 1.2 
+Disables protocol support for SSLv3, TLS 1.0, TLS 1.1 or TLS 1.2
 by setting the corresponding options B<SSL_OP_NO_SSL3>,
 B<SSL_OP_NO_TLS1>, B<SSL_OP_NO_TLS1_1> and B<SSL_OP_NO_TLS1_2> respectively.
 
@@ -177,7 +182,7 @@ Note: the command prefix (if set) alters the recognised B<cmd> values.
 =item B<CipherString>
 
 Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
-currently not performed unless an B<SSL> or B<SSL_CTX> structure is 
+currently not performed unless an B<SSL> or B<SSL_CTX> structure is
 associated with B<cctx>.
 
 =item B<Certificate>
@@ -250,7 +255,7 @@ B<prime256v1>). Curve names are case sensitive.
 
 =item B<ECDHParameters>
 
-This sets the temporary curve used for ephemeral ECDH modes. Only used by 
+This sets the temporary curve used for ephemeral ECDH modes. Only used by
 servers
 
 The B<value> argument is a curve name or the special value B<Automatic> which
@@ -258,16 +263,37 @@ picks an appropriate curve based on client and server preferences. The curve
 can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
 (e.g B<prime256v1>). Curve names are case sensitive.
 
+=item B<MinProtocol>
+
+This sets the minimum supported SSL, TLS or DTLS version.
+
+Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>, B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+
+=item B<MaxProtocol>
+
+This sets the maximum supported SSL, TLS or DTLS version.
+
+Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>, B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+
 =item B<Protocol>
 
-The supported versions of the SSL or TLS protocol.
+This can be used to enable or disable certain versions of the SSL, TLS or DTLS protocol.
+
+The B<value> argument is a comma separated list of supported protocols to enable or disable.
+If a protocol is preceded by B<-> that version is disabled.
+
+All protocol versions are enabled by default.
+You need to disable at least 1 protocol version for this setting have any effect.
+Only enabling some protocol versions does not disable the other protocol versions.
+
+Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>, B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+The special value B<ALL> refers to all supported versions.
 
-The B<value> argument is a comma separated list of supported protocols to
-enable or disable. If an protocol is preceded by B<-> that version is disabled.
-All versions are enabled by default, though applications may choose to
-explicitly disable some. Currently supported protocol values are 
-B<SSLv3>, B<TLSv1>, B<TLSv1.1> and B<TLSv1.2>. The special value B<ALL> refers
-to all supported versions.
+This can't enable protocols that are disabled using B<MinProtocol> or B<MaxProtocol>, but can disable protocols that are still allowed by them.
+
+The B<Protocol> command is fragile and deprecated; do not use it.
+Use B<MinProtocol> and B<MaxProtocol> instead.
+If you do use B<Protocol>, make sure that the resulting range of enabled protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make sure to also leave TLS 1.1 enabled.
 
 =item B<Options>
 
@@ -404,7 +430,7 @@ can be checked instead. If -3 is returned a required argument is missing
 and an error is indicated. If 0 is returned some other error occurred and
 this can be reported back to the user.
 
-The function SSL_CONF_cmd_value_type() can be used by applications to 
+The function SSL_CONF_cmd_value_type() can be used by applications to
 check for the existence of a command or to perform additional syntax
 checking or translation of the command value. For example if the return
 value is B<SSL_CONF_TYPE_FILE> an application could translate a relative
@@ -416,12 +442,29 @@ Set supported signature algorithms:
 
  SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");
 
-Enable all protocols except SSLv3:
+There are various ways to select the supported procotols.
+
+This set the minimum protocol version to TLSv1, and so disables SSLv3.
+This is the recommended way to disable protocols.
+
+ SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1");
+
+The following also disables SSLv3:
+
+ SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
+
+The following will first enable all protocols, and then disable SSLv3.
+If nothing was disabled before it has the same effect as "-SSLv3", but if things were disables it will first enable them again before disabling SSLv3.
 
  SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3");
 
 Only enable TLSv1.2:
 
+ SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2");
+ SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2");
+
+This also only enables TLSv1.2:
+
  SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2");
 
 Disable TLS session tickets:
@@ -474,4 +517,6 @@ B<SSL_CONF_TYPE_NONE> was first added to OpenSSL 1.1.0. In earlier versions of
 OpenSSL passing a command which didn't take an argument would return
 B<SSL_CONF_TYPE_UNKNOWN>.
 
+B<MinProtocol> and B<MaxProtocol> where added in OpenSSL 1.1.0.
+
 =cut
diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod
index 15011f8fc1..2c2120a647 100644
--- a/doc/ssl/SSL_CTX_new.pod
+++ b/doc/ssl/SSL_CTX_new.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-SSL_CTX_new, SSLv3_method, SSLv3_server_method, SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method, TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, TLS_method, TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method, SSLv23_client_method - create a new SSL_CTX object as framework for TLS/SSL enabled functions
+SSL_CTX_new, SSLv3_method, SSLv3_server_method, SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method, TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, TLS_method, TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method, SSLv23_client_method, DTLS_method, DTLS_server_method, DTLS_client_method, DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method, DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method - create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled functions
 
 =head1 SYNOPSIS
 
@@ -10,51 +10,77 @@ SSL_CTX_new, SSLv3_method, SSLv3_server_method, SSLv3_client_method, TLSv1_metho
 
  SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
 
+ const SSL_METHOD *TLS_method(void);
+ const SSL_METHOD *TLS_server_method(void);
+ const SSL_METHOD *TLS_client_method(void);
+
+ #define SSLv23_method           TLS_method
+ #define SSLv23_server_method    TLS_server_method
+ #define SSLv23_client_method    TLS_client_method
+
+ #ifndef OPENSSL_NO_SSL3_METHOD
+ const SSL_METHOD *SSLv3_method(void);
+ const SSL_METHOD *SSLv3_server_method(void);
+ const SSL_METHOD *SSLv3_client_method(void);
+ #endif
+
+ const SSL_METHOD *TLSv1_method(void);
+ const SSL_METHOD *TLSv1_server_method(void);
+ const SSL_METHOD *TLSv1_client_method(void);
+
+ const SSL_METHOD *TLSv1_1_method(void);
+ const SSL_METHOD *TLSv1_1_server_method(void);
+ const SSL_METHOD *TLSv1_1_client_method(void);
+
+ const SSL_METHOD *TLSv1_2_method(void);
+ const SSL_METHOD *TLSv1_2_server_method(void);
+ const SSL_METHOD *TLSv1_2_client_method(void);
+
+ const SSL_METHOD *DTLS_method(void);
+ const SSL_METHOD *DTLS_server_method(void);
+ const SSL_METHOD *DTLS_client_method(void);
+
+ const SSL_METHOD *DTLSv1_method(void);
+ const SSL_METHOD *DTLSv1_server_method(void);
+ const SSL_METHOD *DTLSv1_client_method(void);
+
+ const SSL_METHOD *DTLSv1_2_method(void);
+ const SSL_METHOD *DTLSv1_2_server_method(void);
+ const SSL_METHOD *DTLSv1_2_client_method(void);
+
 =head1 DESCRIPTION
 
-SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish
-TLS/SSL enabled connections.
+SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish TLS/SSL or DTLS enabled connections.
 
 =head1 NOTES
 
-The SSL_CTX object uses B<method> as connection method. The methods exist
-in a generic type (for client and server use), a server only type, and a
-client only type. B<method> can be of the following types:
+The SSL_CTX object uses B<method> as connection method.
+The methods exist in a generic type (for client and server use), a server only type, and a client only type.
+B<method> can be of the following types:
 
 =over 4
 
-=item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void)
+=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()
 
-A TLS/SSL connection established with these methods will only understand the
-SSLv3 protocol. A client will send out SSLv3 client hello messages
-and will indicate that it only understands SSLv3. A server will only understand
-SSLv3 client hello messages.
+An SSL connection established with these methods will only understand the SSLv3 protocol.
+A client will send out a SSLv3 client hello messages and will indicate that it supports SSLv3.
+A server will only understand SSLv3 client hello message and only support the SSLv3 protocol.
 
-=item TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void)
+=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()
 
-A TLS/SSL connection established with these methods will only understand the
-TLSv1 protocol. A client will send out TLSv1 client hello messages
-and will indicate that it only understands TLSv1. A server will only understand
-TLSv1 client hello messages.
+A TLS connection established with these methods will only understand the TLS 1.0 protocol.
 
-=item TLSv1_1_method(void), TLSv1_1_server_method(void), TLSv1_1_client_method(void)
+=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()
 
-A TLS/SSL connection established with these methods will only understand the
-TLSv1.1 protocol. A client will send out TLSv1.1 client hello messages
-and will indicate that it only understands TLSv1.1. A server will only
-understand TLSv1.1 client hello messages.
+A TLS connection established with these methods will only understand the TLS 1.1 protocol.
 
-=item TLSv1_2_method(void), TLSv1_2_server_method(void), TLSv1_2_client_method(void)
+=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()
 
-A TLS/SSL connection established with these methods will only understand the
-TLSv1.2 protocol. A client will send out TLSv1.2 client hello messages
-and will indicate that it only understands TLSv1.2. A server will only
-understand TLSv1.2 client hello messages.
+A TLS connection established with these methods will only understand the TLS 1.2 protocol.
 
-=item TLS_method(void), TLS_server_method(void), TLS_client_method(void)
+=item TLS_method(), TLS_server_method(), TLS_client_method()
 
-A TLS/SSL connection established with these methods may understand the
-SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols.
+A TLS/SSL connection established with these methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols.
 
 If extensions are required (for example server name)
 a client will send out TLSv1 client hello messages including extensions and
@@ -62,26 +88,36 @@ will indicate that it also understands TLSv1.1, TLSv1.2 and permits a
 fallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1 and TLSv1.2
 protocols. This is the best choice when compatibility is a concern.
 
-=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void)
+=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()
 
-Use of these functions is deprecated. They have been replaced with TLS_Method(),
+Use of these functions is deprecated. They have been replaced with TLS_method(),
 TLS_server_method() and TLS_client_method() respectively. New code should use
 those functions instead.
 
+=item DTLS_method(), DTLS_server_method(), DTLS_client_method()
+
+A DTLS connection established with those methods understands all supported DTLS protocols.
+Currently supported protocols are DTLS 1.0 and DTLS 1.2.
+
+=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()
+
+A DTLS connection established with these methods will only understand the DTLS 1.0 protocol.
+
+=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()
+
+A DTLS connection established with these methods will only understand the DTLS 1.2 protocol.
+
 =back
 
-The list of protocols available can later be limited using the
-SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1 and SSL_OP_NO_TLSv1_2
-options of the SSL_CTX_set_options() or SSL_set_options() functions.
-Using these options it is possible to choose e.g. TLS_server_method() and
-be able to negotiate with all possible clients, but to only allow newer
-protocols like TLSv1, TLSv1.1 or TLS v1.2.
+TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), DTLS_server_method() and DTLS_client_method() are the version flexible methods.
+All other methods only support 1 specific protocol version.
+It's recommended to use those methods instead of the version specific methods.
 
-Applications which never want to support SSLv3 can set SSL_OP_NO_SSLv3.
+If you want to limit the supported protocols for the version flexible methods you can use SSL_CTX_set_min_proto_version(), SSL_set_min_proto_version(), SSL_CTX_set_max_proto_version() and SSL_set_max_proto_version() functions.
+They can also be limited using by using an option like SSL_OP_NO_SSLv3 of the SSL_CTX_set_options() or SSL_set_options() functions, but that's not recommended.
+Using these functions it is possible to choose e.g. TLS_server_method() and be able to negotiate with all possible clients, but to only allow newer protocols like TLS v1, TLS v1.1 or TLS v1.2.
 
-SSL_CTX_new() initializes the list of ciphers, the session cache setting,
-the callbacks, the keys and certificates and the options to its default
-values.
+SSL_CTX_new() initializes the list of ciphers, the session cache setting, the callbacks, the keys and certificates and the options to its default values.
 
 =head1 RETURN VALUES
 
@@ -102,14 +138,14 @@ The return value points to an allocated SSL_CTX object.
 
 =head1 HISTORY
 
-SSLv2_method, SSLv2_server_method and SSLv2_client_method where removed in
-OpenSSL 1.1.0. SSLv23_method, SSLv23_server_method and SSLv23_client_method were
-deprecated and TLS_method, TLS_server_method and TLS_client_method
-were introduced in OpenSSL 1.1.0.
+SSLv3
+SSLv2_method, SSLv2_server_method and SSLv2_client_method where removed in OpenSSL 1.1.0.
+SSLv23_method, SSLv23_server_method and SSLv23_client_method were deprecated and TLS_method, TLS_server_method and TLS_client_method were introduced in OpenSSL 1.1.0.
 
 =head1 SEE ALSO
 
 L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
+L<SSL_CTX_set_min_proto_version(3)>,
 L<ssl(3)>,  L<SSL_set_connect_state(3)>
 
 =cut
diff --git a/doc/ssl/SSL_CTX_set_min_proto_version.pod b/doc/ssl/SSL_CTX_set_min_proto_version.pod
new file mode 100644
index 0000000000..4cb4c43a2d
--- /dev/null
+++ b/doc/ssl/SSL_CTX_set_min_proto_version.pod
@@ -0,0 +1,42 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_min_proto_version, SSL_CTX_set_max_proto_version, SSL_set_min_proto_version, SSL_set_max_proto_version - Set minimum and maximum supported protocol version
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set_min_proto_version(SSL_CTX *ctx, int version);
+ int SSL_CTX_set_max_proto_version(SSL_CTX *ctx, int version);
+ int SSL_set_min_proto_version(SSL *ssl, int version);
+ int SSL_set_max_proto_version(SSL *ssl, int version);
+
+=head1 DESCRIPTION
+
+The functions set the minimum and maximum supported portocol versions for the B<ctx> or B<ssl>.
+This works in combination with the options set via SSL_CTX_set_options() that allows to disable specific protocol versions.
+You should use these functions instead of disabling a specific protocol version.
+
+When setting the minimum or maximum version to 0 it will use the lowest or highest supported version, respectively, by the library.
+
+Currently supported versions are B<SSL3_VERSION>, B<TLS1_VERSION>, B<TLS1_1_VERSION>, B<TLS1_2_VERSION>, B<DTLS1_VERSION> and B<DTLS1_2_VERSION>.
+
+=head1 RETURN VALUES
+
+The function returns 1 on success and 0 on failure.
+
+=head1 NOTES
+
+All these functions are implemented using macros.
+
+=head1 HISTORY
+
+The functions were added in OpenSSL 1.1.0
+
+=head1 SEE ALSO
+
+L<SSL_CTX_set_options(3)>, L<SSL_CONF_cmd(3)>
+
+=cut
diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod
index cf137a5ed4..bf7f7fd318 100644
--- a/doc/ssl/SSL_CTX_set_options.pod
+++ b/doc/ssl/SSL_CTX_set_options.pod
@@ -153,13 +153,10 @@ own preferences.
 ...
 
 
-=item SSL_OP_NO_SSLv3
+=item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1
 
-Do not use the SSLv3 protocol.
-
-=item SSL_OP_NO_TLSv1
-
-Do not use the TLSv1 protocol.
+Do not use the SSLv3 or TLSv1 protocol, respectively.
+You should avoid using those settings and instead use SSL_CTX_set_min_proto_version() and SSL_CTX_set_max_proto_version().
 
 =item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
 
@@ -269,6 +266,7 @@ secure renegotiation and 0 if it does not.
 
 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