vtls: add options to specify range of enabled TLS versions

This commit introduces the CURL_SSLVERSION_MAX_* constants as well as
the --tls-max option of the curl tool.

Closes https://github.com/curl/curl/pull/1166

4 files changed, 69 insertions, 3 deletions

diff --git a/docs/cmdline-opts/tls-max.d b/docs/cmdline-opts/tls-max.d
new file mode 100644
index 000000000..7ae862252
--- /dev/null
+++ b/docs/cmdline-opts/tls-max.d
@@ -0,0 +1,24 @@
+Long: tls-max
+Arg: <VERSION>
+Tags: Versions
+Protocols: SSL
+Added: 7.54.0
+Requires: TLS
+See-also: tlsv1.0 tlsv1.1 tlsv1.2
+Help: Use TLSv1.0 or greater
+---
+VERSION defines maximum supported TLS version. A minimum is defined
+by arguments tlsv1.0 or tlsv1.1 or tlsv1.2.
+
+.RS
+.IP "default"
+Use up to recommended TLS version.
+.IP "1.0"
+Use up to TLSv1.0.
+.IP "1.1"
+Use up to TLSv1.1.
+.IP "1.2"
+Use up to TLSv1.2.
+.IP "1.3"
+Use up to TLSv1.3.
+.RE
diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3
index f96a9e6c5..85ecdc41f 100644
--- a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3
+++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3
@@ -46,6 +46,23 @@ TLSv1.1
 TLSv1.2
 .IP CURL_SSLVERSION_TLSv1_3
 TLSv1.3
+.IP CURL_SSLVERSION_MAX_DEFAULT
+The flag defines maximum supported TLS version as TLSv1.2 or default
+value from SSL library. Only library NSS currently allows to get
+maximum supported TLS version.
+(Added in 7.54.0)
+.IP CURL_SSLVERSION_MAX_TLSv1_0
+The flag defines maximum supported TLS version as TLSv1.0.
+(Added in 7.54.0)
+.IP CURL_SSLVERSION_MAX_TLSv1_1
+The flag defines maximum supported TLS version as TLSv1.1.
+(Added in 7.54.0)
+.IP CURL_SSLVERSION_MAX_TLSv1_2
+The flag defines maximum supported TLS version as TLSv1.2.
+(Added in 7.54.0)
+.IP CURL_SSLVERSION_MAX_TLSv1_3
+The flag defines maximum supported TLS version as TLSv1.3.
+(Added in 7.54.0)
 .RE
 .SH DEFAULT
 CURL_SSLVERSION_DEFAULT
@@ -58,7 +75,8 @@ if(curl) {
   curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
 
   /* ask libcurl to use TLS version 1.0 or later */
-  curl_easy_setopt(curl, CURLOPT_PROXY_SSLVERSION, CURL_SSLVERSION_TLSv1);
+  curl_easy_setopt(curl, CURLOPT_PROXY_SSLVERSION, CURL_SSLVERSION_TLSv1_1 |
+                   CURL_SSLVERSION_MAX_DEFAULT);
 
   /* Perform the request */
   curl_easy_perform(curl);
diff --git a/docs/libcurl/opts/CURLOPT_SSLVERSION.3 b/docs/libcurl/opts/CURLOPT_SSLVERSION.3
index 77dfcd49d..d07ae8dde 100644
--- a/docs/libcurl/opts/CURLOPT_SSLVERSION.3
+++ b/docs/libcurl/opts/CURLOPT_SSLVERSION.3
@@ -50,6 +50,23 @@ TLSv1.1 (Added in 7.34.0)
 TLSv1.2 (Added in 7.34.0)
 .IP CURL_SSLVERSION_TLSv1_3
 TLSv1.3 (Added in 7.52.0)
+.IP CURL_SSLVERSION_MAX_DEFAULT
+The flag defines maximum supported TLS version as TLSv1.2 or default
+value from SSL library. Only library NSS currently allows to get
+maximum supported TLS version.
+(Added in 7.54.0)
+.IP CURL_SSLVERSION_MAX_TLSv1_0
+The flag defines maximum supported TLS version as TLSv1.0.
+(Added in 7.54.0)
+.IP CURL_SSLVERSION_MAX_TLSv1_1
+The flag defines maximum supported TLS version as TLSv1.1.
+(Added in 7.54.0)
+.IP CURL_SSLVERSION_MAX_TLSv1_2
+The flag defines maximum supported TLS version as TLSv1.2.
+(Added in 7.54.0)
+.IP CURL_SSLVERSION_MAX_TLSv1_3
+The flag defines maximum supported TLS version as TLSv1.3.
+(Added in 7.54.0)
 .RE
 .SH DEFAULT
 CURL_SSLVERSION_DEFAULT
@@ -61,8 +78,9 @@ CURL *curl = curl_easy_init();
 if(curl) {
   curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
 
-  /* ask libcurl to use TLS version 1.0 or later */
-  curl_easy_setopt(curl, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1);
+  /* ask libcurl to use TLS version 1.1 or later */
+  curl_easy_setopt(curl, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1.1 |
+                   CURL_SSLVERSION_MAX_DEFAULT);
 
   /* Perform the request */
   curl_easy_perform(curl);
diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions
index 8834ada54..f4cd9805f 100644
--- a/docs/libcurl/symbols-in-versions
+++ b/docs/libcurl/symbols-in-versions
@@ -798,6 +798,12 @@ CURL_SSLVERSION_TLSv1_0         7.34.0
 CURL_SSLVERSION_TLSv1_1         7.34.0
 CURL_SSLVERSION_TLSv1_2         7.34.0
 CURL_SSLVERSION_TLSv1_3         7.52.0
+CURL_SSLVERSION_MAX_NONE        7.54.0
+CURL_SSLVERSION_MAX_DEFAULT     7.54.0
+CURL_SSLVERSION_MAX_TLSv1_0     7.54.0
+CURL_SSLVERSION_MAX_TLSv1_1     7.54.0
+CURL_SSLVERSION_MAX_TLSv1_2     7.54.0
+CURL_SSLVERSION_MAX_TLSv1_3     7.54.0
 CURL_TIMECOND_IFMODSINCE        7.9.7
 CURL_TIMECOND_IFUNMODSINCE      7.9.7
 CURL_TIMECOND_LASTMOD           7.9.7