file(DOWNLOAD|UPLOAD): Add TLS_VERSION option for https connections

Add an option to specify the minimum allowed TLS version for https
connections.

Issue: #25701

27 files changed, 122 insertions, 0 deletions

diff --git a/.gitlab/ci/configure_debian12_aarch64_ninja.cmake b/.gitlab/ci/configure_debian12_aarch64_ninja.cmake
index 5b97e4f..cdfd461 100644
--- a/.gitlab/ci/configure_debian12_aarch64_ninja.cmake
+++ b/.gitlab/ci/configure_debian12_aarch64_ninja.cmake
@@ -92,6 +92,7 @@ set(CMake_TEST_IPO_WORKS_Fortran "ON" CACHE BOOL "")
 set(CMake_TEST_JQ "/usr/bin/jq" CACHE PATH "")
 set(CMake_TEST_Qt5 "ON" CACHE BOOL "")
 set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "")
+set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "")
 set(CMake_TEST_UseSWIG "ON" CACHE BOOL "")
 
 include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_debian12_ninja_common.cmake b/.gitlab/ci/configure_debian12_ninja_common.cmake
index d4d117b..78c1d55 100644
--- a/.gitlab/ci/configure_debian12_ninja_common.cmake
+++ b/.gitlab/ci/configure_debian12_ninja_common.cmake
@@ -97,6 +97,7 @@ set(CMake_TEST_IPO_WORKS_Fortran "ON" CACHE BOOL "")
 set(CMake_TEST_JQ "/usr/bin/jq" CACHE PATH "")
 set(CMake_TEST_Qt5 "ON" CACHE BOOL "")
 set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "")
+set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "")
 
 if (NOT "$ENV{SWIFTC}" STREQUAL "")
   set(CMAKE_Swift_COMPILER "$ENV{SWIFTC}" CACHE FILEPATH "")
diff --git a/.gitlab/ci/configure_fedora39_makefiles.cmake b/.gitlab/ci/configure_fedora39_makefiles.cmake
index 953b2a8..fe03851 100644
--- a/.gitlab/ci/configure_fedora39_makefiles.cmake
+++ b/.gitlab/ci/configure_fedora39_makefiles.cmake
@@ -98,6 +98,7 @@ if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "")
 endif()
 set(CMake_TEST_Qt5 "ON" CACHE BOOL "")
 set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "")
+set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "")
 set(CMake_TEST_UseSWIG "ON" CACHE BOOL "")
 
 include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_fedora39_ninja.cmake b/.gitlab/ci/configure_fedora39_ninja.cmake
index ff233a3..8d04bde 100644
--- a/.gitlab/ci/configure_fedora39_ninja.cmake
+++ b/.gitlab/ci/configure_fedora39_ninja.cmake
@@ -3,6 +3,7 @@ if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "")
   set(CMake_TEST_ISPC "ON" CACHE STRING "")
 endif()
 set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "")
+set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "")
 
 # "Release" flags without "-DNDEBUG" so we get assertions.
 set(CMAKE_C_FLAGS_RELEASE "-O3" CACHE STRING "")
diff --git a/.gitlab/ci/configure_macos_arm64_ninja.cmake b/.gitlab/ci/configure_macos_arm64_ninja.cmake
index f2068a1..a0a309e 100644
--- a/.gitlab/ci/configure_macos_arm64_ninja.cmake
+++ b/.gitlab/ci/configure_macos_arm64_ninja.cmake
@@ -4,5 +4,6 @@ set(CMake_TEST_FindOpenMP_C "ON" CACHE BOOL "")
 set(CMake_TEST_FindOpenMP_CXX "ON" CACHE BOOL "")
 set(CMake_TEST_GUI "ON" CACHE BOOL "")
 set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "")
+set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "")
 include("${CMAKE_CURRENT_LIST_DIR}/configure_macos_common.cmake")
 include("${CMAKE_CURRENT_LIST_DIR}/configure_common.cmake")
diff --git a/.gitlab/ci/configure_macos_x86_64_makefiles.cmake b/.gitlab/ci/configure_macos_x86_64_makefiles.cmake
index 5d1620d..f0bf1c0 100644
--- a/.gitlab/ci/configure_macos_x86_64_makefiles.cmake
+++ b/.gitlab/ci/configure_macos_x86_64_makefiles.cmake
@@ -7,6 +7,7 @@ if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "")
   set(CMake_TEST_ISPC "ON" CACHE STRING "")
 endif()
 set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "")
+set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "")
 
 include("${CMAKE_CURRENT_LIST_DIR}/configure_macos_common.cmake")
 include("${CMAKE_CURRENT_LIST_DIR}/configure_common.cmake")
diff --git a/.gitlab/ci/configure_macos_x86_64_ninja.cmake b/.gitlab/ci/configure_macos_x86_64_ninja.cmake
index 5d1620d..f0bf1c0 100644
--- a/.gitlab/ci/configure_macos_x86_64_ninja.cmake
+++ b/.gitlab/ci/configure_macos_x86_64_ninja.cmake
@@ -7,6 +7,7 @@ if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "")
   set(CMake_TEST_ISPC "ON" CACHE STRING "")
 endif()
 set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "")
+set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "")
 
 include("${CMAKE_CURRENT_LIST_DIR}/configure_macos_common.cmake")
 include("${CMAKE_CURRENT_LIST_DIR}/configure_common.cmake")
diff --git a/.gitlab/ci/configure_windows_arm64_vs2022_ninja.cmake b/.gitlab/ci/configure_windows_arm64_vs2022_ninja.cmake
index a12ee6c..fa2566e 100644
--- a/.gitlab/ci/configure_windows_arm64_vs2022_ninja.cmake
+++ b/.gitlab/ci/configure_windows_arm64_vs2022_ninja.cmake
@@ -1,6 +1,7 @@
 # Qt host tools are not yet available natively on windows-arm64.
 set(CMake_TEST_GUI "OFF" CACHE BOOL "")
 set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "")
+set(CMake_TEST_TLS_VERSION "1.2" CACHE STRING "")
 set(BUILD_QtDialog "OFF" CACHE BOOL "")
 set(CMAKE_PREFIX_PATH "" CACHE STRING "")
 
diff --git a/.gitlab/ci/configure_windows_vs2022_x64_ninja.cmake b/.gitlab/ci/configure_windows_vs2022_x64_ninja.cmake
index a41ec8b..e224a58 100644
--- a/.gitlab/ci/configure_windows_vs2022_x64_ninja.cmake
+++ b/.gitlab/ci/configure_windows_vs2022_x64_ninja.cmake
@@ -4,6 +4,7 @@ if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "")
   set(CMake_TEST_Swift "ON" CACHE STRING "")
 endif()
 set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "")
+set(CMake_TEST_TLS_VERSION "1.2" CACHE STRING "")
 
 include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_msvc_cxx_modules_common.cmake")
 include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_vs_common_ninja.cmake")
diff --git a/Help/command/file.rst b/Help/command/file.rst
index 4acdc7e..dfbd483 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -1097,6 +1097,11 @@ Transfer
       is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable
       will be used instead.
 
+    ``TLS_VERSION <min>``
+      .. versionadded:: 3.30
+
+      Specify minimum TLS version for ``https://`` URLs.
+
     ``TLS_VERIFY <ON|OFF>``
       Specify whether to verify the server certificate for ``https://`` URLs.
       The default is to *not* verify. If this option is not specified, the
diff --git a/Help/release/dev/curl-tls-version.rst b/Help/release/dev/curl-tls-version.rst
new file mode 100644
index 0000000..1896f45
--- /dev/null
+++ b/Help/release/dev/curl-tls-version.rst
@@ -0,0 +1,6 @@
+curl-tls-version
+----------------
+
+* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands
+  gained a ``TLS_VERSION <min>`` option to specify the minimum TLS
+  version for connections to ``https://`` URLs.
diff --git a/Source/cmCurl.cxx b/Source/cmCurl.cxx
index 24ba368..ae242ee 100644
--- a/Source/cmCurl.cxx
+++ b/Source/cmCurl.cxx
@@ -2,6 +2,9 @@
    file Copyright.txt or https://cmake.org/licensing for details.  */
 #include "cmCurl.h"
 
+#include <cm/string_view>
+#include <cmext/string_view>
+
 #if !defined(CMAKE_USE_SYSTEM_CURL) && !defined(_WIN32) &&                    \
   !defined(__APPLE__) && !defined(CURL_CA_BUNDLE) && !defined(CURL_CA_PATH)
 #  define CMAKE_FIND_CAFILE
@@ -31,6 +34,26 @@
     }                                                                         \
   } while (false)
 
+cm::optional<int> cmCurlParseTLSVersion(std::string const& tls_version)
+{
+  cm::optional<int> v;
+  if (tls_version == "1.0"_s) {
+    v = CURL_SSLVERSION_TLSv1_0;
+  } else if (tls_version == "1.1"_s) {
+    v = CURL_SSLVERSION_TLSv1_1;
+  } else if (tls_version == "1.2"_s) {
+    v = CURL_SSLVERSION_TLSv1_2;
+  } else if (tls_version == "1.3"_s) {
+    // curl version 7.52.0 introduced TLS 1.3 support
+#if defined(LIBCURL_VERSION_NUM) && LIBCURL_VERSION_NUM >= 0x073400
+    v = CURL_SSLVERSION_TLSv1_3;
+#else
+    v = CURL_SSLVERSION_LAST;
+#endif
+  }
+  return v;
+}
+
 std::string cmCurlSetCAInfo(::CURL* curl, const std::string& cafile)
 {
   std::string e;
diff --git a/Source/cmCurl.h b/Source/cmCurl.h
index b5134f4..b895a30 100644
--- a/Source/cmCurl.h
+++ b/Source/cmCurl.h
@@ -6,8 +6,11 @@
 
 #include <string>
 
+#include <cm/optional>
+
 #include <cm3p/curl/curl.h>
 
+cm::optional<int> cmCurlParseTLSVersion(std::string const& tls_version);
 std::string cmCurlSetCAInfo(::CURL* curl, const std::string& cafile = {});
 std::string cmCurlSetNETRCOption(::CURL* curl, const std::string& netrc_level,
                                  const std::string& netrc_file);
diff --git a/Source/cmFileCommand.cxx b/Source/cmFileCommand.cxx
index e3f5b96..dcdb1ae 100644
--- a/Source/cmFileCommand.cxx
+++ b/Source/cmFileCommand.cxx
@@ -1859,6 +1859,7 @@ bool HandleDownloadCommand(std::vector<std::string> const& args,
   long inactivity_timeout = 0;
   std::string logVar;
   std::string statusVar;
+  cm::optional<std::string> tls_version;
   bool tls_verify = status.GetMakefile().IsOn("CMAKE_TLS_VERIFY");
   cmValue cainfo = status.GetMakefile().GetDefinition("CMAKE_TLS_CAINFO");
   std::string netrc_level =
@@ -1905,6 +1906,14 @@ bool HandleDownloadCommand(std::vector<std::string> const& args,
         return false;
       }
       statusVar = *i;
+    } else if (*i == "TLS_VERSION") {
+      ++i;
+      if (i != args.end()) {
+        tls_version = *i;
+      } else {
+        status.SetError("DOWNLOAD missing value for TLS_VERSION.");
+        return false;
+      }
     } else if (*i == "TLS_VERIFY") {
       ++i;
       if (i != args.end()) {
@@ -2092,6 +2101,19 @@ bool HandleDownloadCommand(std::vector<std::string> const& args,
                            cmFileCommandCurlDebugCallback);
   check_curl_result(res, "DOWNLOAD cannot set debug function: ");
 
+  if (tls_version) {
+    if (cm::optional<int> v = cmCurlParseTLSVersion(*tls_version)) {
+      res = ::curl_easy_setopt(curl, CURLOPT_SSLVERSION, *v);
+      check_curl_result(
+        res,
+        cmStrCat("DOWNLOAD cannot set TLS/SSL version ", *tls_version, ": "));
+    } else {
+      status.SetError(
+        cmStrCat("DOWNLOAD given unknown TLS/SSL version ", *tls_version));
+      return false;
+    }
+  }
+
   // check to see if TLS verification is requested
   if (tls_verify) {
     res = ::curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1);
@@ -2281,6 +2303,7 @@ bool HandleUploadCommand(std::vector<std::string> const& args,
   std::string logVar;
   std::string statusVar;
   bool showProgress = false;
+  cm::optional<std::string> tls_version;
   bool tls_verify = status.GetMakefile().IsOn("CMAKE_TLS_VERIFY");
   cmValue cainfo = status.GetMakefile().GetDefinition("CMAKE_TLS_CAINFO");
   std::string userpwd;
@@ -2324,6 +2347,14 @@ bool HandleUploadCommand(std::vector<std::string> const& args,
       statusVar = *i;
     } else if (*i == "SHOW_PROGRESS") {
       showProgress = true;
+    } else if (*i == "TLS_VERSION") {
+      ++i;
+      if (i != args.end()) {
+        tls_version = *i;
+      } else {
+        status.SetError("UPLOAD missing value for TLS_VERSION.");
+        return false;
+      }
     } else if (*i == "TLS_VERIFY") {
       ++i;
       if (i != args.end()) {
@@ -2423,6 +2454,19 @@ bool HandleUploadCommand(std::vector<std::string> const& args,
                            cmFileCommandCurlDebugCallback);
   check_curl_result(res, "UPLOAD cannot set debug function: ");
 
+  if (tls_version) {
+    if (cm::optional<int> v = cmCurlParseTLSVersion(*tls_version)) {
+      res = ::curl_easy_setopt(curl, CURLOPT_SSLVERSION, *v);
+      check_curl_result(
+        res,
+        cmStrCat("UPLOAD cannot set TLS/SSL version ", *tls_version, ": "));
+    } else {
+      status.SetError(
+        cmStrCat("UPLOAD given unknown TLS/SSL version ", *tls_version));
+      return false;
+    }
+  }
+
   // check to see if TLS verification is requested
   if (tls_verify) {
     res = ::curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1);
diff --git a/Tests/RunCMake/CMakeLists.txt b/Tests/RunCMake/CMakeLists.txt
index a2a9ee9..d4bb490 100644
--- a/Tests/RunCMake/CMakeLists.txt
+++ b/Tests/RunCMake/CMakeLists.txt
@@ -553,6 +553,7 @@ add_RunCMake_test(file-CHMOD -DMSYS=${MSYS})
 foreach(var
     CMake_TEST_NO_NETWORK
     CMake_TEST_TLS_VERIFY_URL
+    CMake_TEST_TLS_VERSION
     )
   if(DEFINED ${var})
     list(APPEND file-DOWNLOAD_ARGS -D${var}=${${var}})
diff --git a/Tests/RunCMake/file-DOWNLOAD/RunCMakeTest.cmake b/Tests/RunCMake/file-DOWNLOAD/RunCMakeTest.cmake
index d757eea..33f519f 100644
--- a/Tests/RunCMake/file-DOWNLOAD/RunCMakeTest.cmake
+++ b/Tests/RunCMake/file-DOWNLOAD/RunCMakeTest.cmake
@@ -11,6 +11,7 @@ run_cmake(httpheader-not-set)
 run_cmake(netrc-bad)
 run_cmake(tls-cainfo-not-set)
 run_cmake(tls-verify-not-set)
+run_cmake(TLS_VERSION-missing)
 run_cmake(pass-not-set)
 run_cmake(no-save-hash)
 
@@ -25,7 +26,12 @@ if(NOT CMake_TEST_NO_NETWORK)
   run_cmake(bad-hostname)
 endif()
 
+run_cmake_with_options(TLS_VERSION-bad)
+
 if(CMake_TEST_TLS_VERIFY_URL)
   run_cmake(TLS_VERIFY-bad)
   run_cmake_with_options(TLS_VERIFY-good -Durl=${CMake_TEST_TLS_VERIFY_URL})
+  if(CMake_TEST_TLS_VERSION)
+    run_cmake_with_options(TLS_VERSION-good -Durl=${CMake_TEST_TLS_VERIFY_URL} -Dtls_version=${CMake_TEST_TLS_VERSION})
+  endif()
 endif()
diff --git a/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-bad-result.txt b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-bad-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-bad-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-bad-stderr.txt b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-bad-stderr.txt
new file mode 100644
index 0000000..3a1d453
--- /dev/null
+++ b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-bad-stderr.txt
@@ -0,0 +1,4 @@
+^CMake Error at TLS_VERSION-bad\.cmake:[0-9]+ \(file\):
+  file DOWNLOAD given unknown TLS/SSL version bad-arg
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)$
diff --git a/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-bad.cmake b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-bad.cmake
new file mode 100644
index 0000000..846af16
--- /dev/null
+++ b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-bad.cmake
@@ -0,0 +1 @@
+file(DOWNLOAD "" TLS_VERSION bad-arg TLS_VERIFY 1 STATUS status LOG log)
diff --git a/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-good.cmake b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-good.cmake
new file mode 100644
index 0000000..fcbf650
--- /dev/null
+++ b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-good.cmake
@@ -0,0 +1,6 @@
+file(DOWNLOAD ${url} TLS_VERSION "${tls_version}" TLS_VERIFY 1 STATUS status LOG log)
+message(STATUS "${status}")
+list(GET status 0 code)
+if(NOT code EQUAL 0)
+  message("${log}")
+endif()
diff --git a/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-missing-result.txt b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-missing-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-missing-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-missing-stderr.txt b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-missing-stderr.txt
new file mode 100644
index 0000000..05d9d90
--- /dev/null
+++ b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-missing-stderr.txt
@@ -0,0 +1,4 @@
+^CMake Error at TLS_VERSION-missing\.cmake:[0-9]+ \(file\):
+  file DOWNLOAD missing value for TLS_VERSION\.
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)$
diff --git a/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-missing.cmake b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-missing.cmake
new file mode 100644
index 0000000..29fcd96
--- /dev/null
+++ b/Tests/RunCMake/file-DOWNLOAD/TLS_VERSION-missing.cmake
@@ -0,0 +1 @@
+file(DOWNLOAD "" "" TLS_VERSION)
diff --git a/Tests/RunCMake/file/RunCMakeTest.cmake b/Tests/RunCMake/file/RunCMakeTest.cmake
index c75e062..be8ee7c 100644
--- a/Tests/RunCMake/file/RunCMakeTest.cmake
+++ b/Tests/RunCMake/file/RunCMakeTest.cmake
@@ -12,6 +12,7 @@ run_cmake(UPLOAD-httpheader-not-set)
 run_cmake(UPLOAD-netrc-bad)
 run_cmake(UPLOAD-tls-cainfo-not-set)
 run_cmake(UPLOAD-tls-verify-not-set)
+run_cmake(UPLOAD-TLS_VERSION-missing)
 run_cmake(UPLOAD-pass-not-set)
 run_cmake(INSTALL-DIRECTORY)
 run_cmake(INSTALL-FILES_FROM_DIR)
diff --git a/Tests/RunCMake/file/UPLOAD-TLS_VERSION-missing-result.txt b/Tests/RunCMake/file/UPLOAD-TLS_VERSION-missing-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/file/UPLOAD-TLS_VERSION-missing-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/file/UPLOAD-TLS_VERSION-missing-stderr.txt b/Tests/RunCMake/file/UPLOAD-TLS_VERSION-missing-stderr.txt
new file mode 100644
index 0000000..d61aba7
--- /dev/null
+++ b/Tests/RunCMake/file/UPLOAD-TLS_VERSION-missing-stderr.txt
@@ -0,0 +1,4 @@
+^CMake Error at UPLOAD-TLS_VERSION-missing\.cmake:[0-9]+ \(file\):
+  file UPLOAD missing value for TLS_VERSION\.
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)$
diff --git a/Tests/RunCMake/file/UPLOAD-TLS_VERSION-missing.cmake b/Tests/RunCMake/file/UPLOAD-TLS_VERSION-missing.cmake
new file mode 100644
index 0000000..dff9a9c
--- /dev/null
+++ b/Tests/RunCMake/file/UPLOAD-TLS_VERSION-missing.cmake
@@ -0,0 +1 @@
+file(UPLOAD "" "" TLS_VERSION)