apache · hongzhi-gao · Jun 18, 2026 · Jun 18, 2026
diff --git a/.github/scripts/package-client-cpp-manylinux228.sh b/.github/scripts/package-client-cpp-manylinux228.sh
@@ -71,9 +71,22 @@ fi
 cmake --version
 java -version
 
+# manylinux_2_28 is AlmaLinux 8, whose system OpenSSL is 1.1.1 (EOL and not
+# Apache-2.0 - must not be bundled/redistributed in an ASF convenience binary).
+# Build OpenSSL 3.x from source instead (-Diotdb.openssl.from.source=ON), which
+# keeps the glibc 2.28 baseline. OpenSSL 3.x's Configure needs perl plus a few
+# modules (IPC::Cmd, Data::Dumper) that are not on the minimal image - install
+# them even when perl itself is already present.
+if command -v dnf >/dev/null 2>&1; then
+  dnf install -y perl perl-IPC-Cmd perl-Data-Dumper
+else
+  yum install -y perl perl-IPC-Cmd perl-Data-Dumper
+fi
+
 cd "${GITHUB_WORKSPACE:?GITHUB_WORKSPACE is not set}"
 ./mvnw clean package -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests \
   -Dspotless.skip=true \
+  -Diotdb.openssl.from.source=ON \
   -Dclient.cpp.package.classifier="${PACKAGE_CLASSIFIER}"
 
 SO="iotdb-client/client-cpp/target/install/lib/libiotdb_session.so"

diff --git a/.github/workflows/client-cpp-package.yml b/.github/workflows/client-cpp-package.yml
@@ -295,10 +295,14 @@ jobs:
         shell: bash
         run: |
           set -euxo pipefail
-          brew install boost openssl llvm@17 bison
+          # Pin openssl@3 (Apache-2.0): the default 'openssl' formula will move to
+          # OpenSSL 4.0, which drops the legacy TLS-method APIs Thrift still uses.
+          brew install boost openssl@3 llvm@17 bison
           ln -sf "$(brew --prefix llvm@17)/bin/clang-format" "$(brew --prefix)/bin/clang-format"
           echo "$(brew --prefix bison)/bin" >> "$GITHUB_PATH"
           echo "$(brew --prefix llvm@17)/bin" >> "$GITHUB_PATH"
+          # Homebrew OpenSSL is keg-only, so point find_package(OpenSSL) at it.
+          echo "OPENSSL_ROOT_DIR=$(brew --prefix openssl@3)" >> "$GITHUB_ENV"
           clang-format --version
           bison --version
       - name: Cache Maven packages
@@ -415,8 +419,16 @@ jobs:
             throw "Boost not found under C:\local after installing ${{ matrix.boost_choco }}"
           }
           echo $boostDir.FullName >> $env:GITHUB_PATH
-          choco install openssl -y --no-progress
-          $sslPath = (Get-ChildItem 'C:\Program Files\OpenSSL*' -Directory | Select-Object -First 1).FullName
+          # Use a pinned OpenSSL 3.x (Apache-2.0). 'choco install openssl' now
+          # installs OpenSSL 4.0, which removed the legacy TLS-method APIs that
+          # Apache Thrift's TSSLSocket still calls. The FireDaemon zip is a clean
+          # prebuilt OpenSSL 3.5.x that keeps them.
+          $sslZip = "$env:RUNNER_TEMP\openssl-3.5.3.zip"
+          $sslDir = "$env:RUNNER_TEMP\openssl-3"
+          curl.exe -L --fail --retry 3 -o $sslZip 'https://download.firedaemon.com/FireDaemon-OpenSSL/openssl-3.5.3.zip'
+          Expand-Archive -Path $sslZip -DestinationPath $sslDir -Force
+          $sslPath = (Get-ChildItem $sslDir -Recurse -Directory -Filter 'x64' | Select-Object -First 1).FullName
+          if (-not $sslPath) { throw "OpenSSL x64 dir not found under $sslDir" }
           echo "$sslPath\bin" >> $env:GITHUB_PATH
           echo "OPENSSL_ROOT_DIR=$sslPath" >> $env:GITHUB_ENV
       - name: Cache Maven packages

diff --git a/.github/workflows/multi-language-client.yml b/.github/workflows/multi-language-client.yml
@@ -125,10 +125,13 @@ jobs:
         if: runner.os == 'macOS'
         shell: bash
         run: |
-          brew install boost openssl llvm@17 bison
+          # Pin openssl@3 (Apache-2.0); the default formula will move to OpenSSL 4.0.
+          brew install boost openssl@3 llvm@17 bison
           ln -sf "$(brew --prefix llvm@17)/bin/clang-format" "$(brew --prefix)/bin/clang-format"
           echo "$(brew --prefix bison)/bin" >> "$GITHUB_PATH"
           echo "$(brew --prefix llvm@17)/bin" >> "$GITHUB_PATH"
+          # Homebrew OpenSSL is keg-only, so point find_package(OpenSSL) at it.
+          echo "OPENSSL_ROOT_DIR=$(brew --prefix openssl@3)" >> "$GITHUB_ENV"
           clang-format --version
           bison --version
           sudo rm -rf /Applications/Xcode_14.3.1.app
@@ -144,8 +147,14 @@ jobs:
           $boost_path = (Get-ChildItem -Path 'C:\local\' -Filter 'boost_*').FullName
           echo $boost_path >> $env:GITHUB_PATH
 
-          choco install openssl -y
-          $sslPath = (Get-ChildItem 'C:\Program Files\OpenSSL*' -Directory | Select-Object -First 1).FullName
+          # Pinned OpenSSL 3.x (Apache-2.0): 'choco install openssl' now installs
+          # OpenSSL 4.0, which removed the legacy TLS-method APIs Thrift uses.
+          $sslZip = "$env:RUNNER_TEMP\openssl-3.5.3.zip"
+          $sslDir = "$env:RUNNER_TEMP\openssl-3"
+          curl.exe -L --fail --retry 3 -o $sslZip 'https://download.firedaemon.com/FireDaemon-OpenSSL/openssl-3.5.3.zip'
+          Expand-Archive -Path $sslZip -DestinationPath $sslDir -Force
+          $sslPath = (Get-ChildItem $sslDir -Recurse -Directory -Filter 'x64' | Select-Object -First 1).FullName
+          if (-not $sslPath) { throw "OpenSSL x64 dir not found under $sslDir" }
           echo "$sslPath\bin" >> $env:GITHUB_PATH
           echo "OPENSSL_ROOT_DIR=$sslPath" >> $env:GITHUB_ENV
           choco install llvm --version=17.0.6 --force -y

diff --git a/iotdb-client/client-cpp/CMakeLists.txt b/iotdb-client/client-cpp/CMakeLists.txt
@@ -78,7 +78,7 @@ if(NOT MSVC)
     file(WRITE "${_iotdb_cxx11_abi_stamp}" "${_iotdb_cxx11_abi_stamp_value}")
 endif()
 
-option(WITH_SSL "Build with OpenSSL support" OFF)
+option(WITH_SSL "Build with OpenSSL support" ON)
 option(BUILD_TESTING "Build IT test executables" OFF)
 option(IOTDB_OFFLINE "Disable all network access during configure" OFF)
 set(IOTDB_SESSION_VERSION "0.0.0"
@@ -97,7 +97,7 @@ else()
 endif()
 set(BOOST_VERSION "${_iotdb_default_boost_version}"
     CACHE STRING "Boost version used when downloading / unpacking (Thrift build only)")
-set(THRIFT_VERSION "0.21.0"
+set(THRIFT_VERSION "0.23.0"
     CACHE STRING "Apache Thrift version used when downloading / building")
 
 if(WIN32)
@@ -120,6 +120,7 @@ include(FetchBoost)        # -> BOOST_INCLUDE_DIR (Thrift build only)
 include(FetchBuildTools)
 if(WITH_SSL)
     include(FetchOpenSSL)
+    include(InstallOpenSSLRuntime)
 endif()
 include(FetchThrift)
 include(GenerateThriftSources)
@@ -144,6 +145,22 @@ if(UNIX AND NOT APPLE)
             SOVERSION "${IOTDB_SESSION_SOVERSION}")
 endif()
 
+# When SSL is on we bundle the OpenSSL shared libraries next to libiotdb_session
+# in the package lib/ directory. Give the library an $ORIGIN-relative runtime
+# search path so the loader finds them without LD_LIBRARY_PATH / install_name
+# tweaks, keeping the SDK self-contained.
+if(WITH_SSL)
+    if(APPLE)
+        set_target_properties(iotdb_session PROPERTIES
+                BUILD_RPATH "@loader_path"
+                INSTALL_RPATH "@loader_path")
+    elseif(UNIX)
+        set_target_properties(iotdb_session PROPERTIES
+                BUILD_RPATH "$ORIGIN"
+                INSTALL_RPATH "$ORIGIN")
+    endif()
+endif()
+
 add_dependencies(iotdb_session iotdb_thrift_external iotdb_thrift_codegen)
 
 target_compile_definitions(iotdb_session PRIVATE THRIFT_STATIC_DEFINE IOTDB_BUILDING_SHARED)
@@ -223,6 +240,12 @@ install(TARGETS iotdb_session
         LIBRARY DESTINATION lib
         ARCHIVE DESTINATION lib)
 
+# Ship the OpenSSL shared libraries we link against next to iotdb_session so the
+# packaged SDK is self-contained on machines without a system OpenSSL.
+if(WITH_SSL)
+    iotdb_install_openssl_runtime()
+endif()
+
 foreach(_hdr IN LISTS IOTDB_PUBLIC_HEADERS)
     install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/src/include/${_hdr}"
             DESTINATION include)

diff --git a/iotdb-client/client-cpp/README.md b/iotdb-client/client-cpp/README.md
@@ -300,7 +300,7 @@ so they require glibc 2.28 or newer on the deployment host.
 | ppc64le | `quay.io/pypa/manylinux_2_28_ppc64le` |
 | s390x | `quay.io/pypa/manylinux_2_28_s390x` |
 
-Thrift **0.21.0** is compiled from source during the CMake configure step (see
+Thrift **0.23.0** is compiled from source during the CMake configure step (see
 `cmake/FetchThrift.cmake`). Older releases that used pre-built
 `iotdb-tools-thrift` Maven artifacts and `-Diotdb-tools-thrift.version=...`
 for glibc/MSVC compatibility apply only to the **legacy** client-cpp build;
@@ -378,13 +378,13 @@ etc. directly.
 
 | Option                | Default                          | Purpose                                                                                                  |
 |-----------------------|----------------------------------|----------------------------------------------------------------------------------------------------------|
-| `WITH_SSL`            | `OFF`                            | Link against OpenSSL. See *SSL* below.                                                                   |
+| `WITH_SSL`            | `ON`                             | Link against OpenSSL and bundle its runtime libraries. See *SSL* below.                                  |
 | `BUILD_TESTING`       | `OFF` (Maven sets `ON` for verify) | Build Catch2 IT executables (Catch2 v2.13.7 header downloaded at configure time).                        |
 | `CATCH2_INCLUDE_DIR`  | (unset)                          | Pre-downloaded Catch2 include dir (Maven sets this under `target/test/catch2`).                          |
 | `IOTDB_OFFLINE`       | `OFF`                            | Disallow any network access during configure.                                                            |
 | `IOTDB_DEPS_DIR`      | `<client-cpp>/third-party`       | Override the local tarball cache directory.                                                              |
 | `BOOST_VERSION`       | `1.60.0` (`1.84.0` on macOS)     | Boost version that CMake will look for / download.                                                       |
-| `THRIFT_VERSION`      | `0.21.0`                         | Apache Thrift version to build from source.                                                              |
+| `THRIFT_VERSION`      | `0.23.0`                         | Apache Thrift version to build from source.                                                              |
 | `BOOST_ROOT`          | (unset)                          | Existing Boost install to reuse, equivalent to `-Dboost.include.dir=...` from the legacy build.          |
 | `OPENSSL_ROOT_DIR`    | (unset)                          | Existing OpenSSL install when `WITH_SSL=ON`.                                                             |
 | `CMAKE_INSTALL_PREFIX`| `<build>/install`                | Install location.                                                                                        |
@@ -427,12 +427,12 @@ cmake --build build --config Release --target install
 
    | Platform   | Required files                                                                                                                                                       |
    |------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-   | `linux/`   | `thrift-0.21.0.tar.gz`, `boost_1_60_0.tar.gz`, `m4-1.4.19.tar.gz`, `flex-2.6.4.tar.gz`, `bison-3.8.tar.gz` (and `openssl-3.5.0.tar.gz` when `WITH_SSL=ON`)            |
-   | `mac/`     | `thrift-0.21.0.tar.gz`, `boost_1_84_0.tar.gz` (newer Boost for Xcode/Clang; Apple ships m4/flex/bison; `openssl-3.5.0.tar.gz` optional)                               |
-   | `windows/` | `thrift-0.21.0.tar.gz`, `boost_1_60_0.tar.gz` (Boost headers only - no `b2` build required for `iotdb_session`)                                                      |
+   | `linux/`   | `thrift-0.23.0.tar.gz`, `boost_1_60_0.tar.gz`, `m4-1.4.19.tar.gz`, `flex-2.6.4.tar.gz`, `bison-3.8.tar.gz` (and `openssl-3.5.0.tar.gz` only when `WITH_SSL=ON` and no system OpenSSL is present) |
+   | `mac/`     | `thrift-0.23.0.tar.gz`, `boost_1_84_0.tar.gz` (newer Boost for Xcode/Clang; Apple ships m4/flex/bison; `openssl-3.5.0.tar.gz` optional)                               |
+   | `windows/` | `thrift-0.23.0.tar.gz`, `boost_1_60_0.tar.gz` (Boost headers only - no `b2` build required for `iotdb_session`)                                                      |
 
    Reference URLs (the configure step uses the same):
-   - Apache Thrift 0.21.0: <https://archive.apache.org/dist/thrift/0.21.0/thrift-0.21.0.tar.gz>
+   - Apache Thrift 0.23.0: <https://archive.apache.org/dist/thrift/0.23.0/thrift-0.23.0.tar.gz>
    - Boost 1.60.0:        <https://archives.boost.io/release/1.60.0/source/boost_1_60_0.tar.gz>
    - GNU m4 1.4.19:       <https://ftp.gnu.org/gnu/m4/m4-1.4.19.tar.gz>
    - GNU flex 2.6.4:      <https://github.com/westes/flex/releases/download/v2.6.4/flex-2.6.4.tar.gz>
@@ -461,7 +461,7 @@ CI environments can share a single cache by setting
 ### Linux
 
 - Tested with GCC 7+ and Clang 9+. Anything that can compile Apache Thrift
-  0.21.0 works.
+  0.23.0 works.
 - Build deps that must already exist on the host (only required when
   CMake auto-builds m4/flex/bison from tarball): `make`, `autoconf`,
   `gcc`, plus the standard C/C++ toolchain. `sudo` is **not** required;
@@ -492,9 +492,11 @@ Prerequisites:
 2. **flex / bison.** Install <https://sourceforge.net/projects/winflexbison/>
    and rename `win_flex.exe`→`flex.exe`, `win_bison.exe`→`bison.exe` on
    `PATH`.
-3. **OpenSSL** *(only when `WITH_SSL=ON`)*: run the Win64 OpenSSL
-   installer from <https://slproweb.com/products/Win32OpenSSL.html>, then
-   pass `-DOPENSSL_ROOT_DIR=...` to CMake.
+3. **OpenSSL** *(`WITH_SSL=ON` is the default)*: install OpenSSL — e.g.
+   `choco install openssl`, or a Win64 OpenSSL installer from
+   <https://slproweb.com/products/Win32OpenSSL.html> — then pass
+   `-DOPENSSL_ROOT_DIR=...` to CMake if it is not auto-detected. Pass
+   `-DWITH_SSL=OFF` to build without SSL.
 
 On Windows the SDK ships as **`iotdb_session.dll`** plus an import library
 **`iotdb_session.lib`**, built with **`/MD`** (dynamic CRT, same as a
@@ -507,16 +509,27 @@ the GNU autotools tarballs assume a POSIX shell environment.
 
 ## SSL
 
-Both Thrift and `iotdb_session` build without OpenSSL by default. Enable
-SSL with `-Dwith.ssl=ON` (Maven) or `-DWITH_SSL=ON` (standalone CMake).
-CMake first calls `find_package(OpenSSL)`;
-if nothing is found, it falls back to:
+`iotdb_session` builds **with OpenSSL by default** (`WITH_SSL=ON`). Disable
+it with `-Dwith.ssl=OFF` (Maven) or `-DWITH_SSL=OFF` (standalone CMake).
 
-- **Linux / macOS** – use a local `openssl-<ver>.tar.gz` (or download it
-  when not in offline mode), configure with `no-shared`, install into
-  `build/_deps/openssl/install`, and link statically.
-- **Windows** – fail with a friendly message that points at the Win64
-  OpenSSL installer. Building OpenSSL from source via MSVC is out of scope.
+OpenSSL **3.x** is used (Apache-2.0 licensed). Note that **OpenSSL 4.0 removed**
+the legacy TLS-method APIs (`TLSv1_method`, `SSLv3_method`, …) that Apache
+Thrift's `TSSLSocket` still calls, so install/point at a 3.x build, not 4.0.
+
+CMake calls `find_package(OpenSSL)` and uses the system OpenSSL it finds. Its
+shared libraries are **bundled into the package `lib/` directory** (next to
+`iotdb_session`, which records an `$ORIGIN`/`@loader_path` runtime path) so the
+published SDK is self-contained.
+
+Fallbacks:
+
+- **Linux / macOS** – when no system OpenSSL is found (or
+  `-DIOTDB_OPENSSL_FROM_SOURCE=ON`, which the Linux packaging build uses so the
+  AlmaLinux 8 baseline's OpenSSL 1.1.1 is never redistributed), build
+  `openssl-3.5.0.tar.gz` from source as **shared** libraries and bundle them.
+- **Windows** – fail with a friendly message; install a prebuilt OpenSSL 3.x
+  (e.g. the FireDaemon or slproweb 3.5.x zip) and set `-DOPENSSL_ROOT_DIR=...`.
+  Building OpenSSL from source via MSVC is out of scope.
 
 ## Tests
 

diff --git a/iotdb-client/client-cpp/README_zh.md b/iotdb-client/client-cpp/README_zh.md
@@ -236,14 +236,18 @@ Maven 构建会把 SDK 安装到 `target/install/`，并生成
 
 | CMake 变量 | Maven 属性 |
 |------------|------------|
-| `WITH_SSL` | `with.ssl`，例如 `-Dwith.ssl=ON` |
+| `WITH_SSL` | `with.ssl`（默认 `ON`，关闭用 `-Dwith.ssl=OFF`） |
 | `IOTDB_OFFLINE` | `iotdb.offline` |
 | `BUILD_TESTING` | `build.tests` |
 | `IOTDB_DEPS_DIR` | `iotdb.deps.dir` |
 | `BOOST_INCLUDEDIR` | `boost.include.dir` |
 | `CMAKE_BUILD_TYPE` | `cmake.build.type`，例如 `-Dcmake.build.type=Debug` |
 
-直接使用 CMake 时传入 `-DWITH_SSL=ON`、`-DIOTDB_OFFLINE=ON` 等即可。
+SSL 默认开启（`WITH_SSL=ON`）。所捆绑的 Apache Thrift 0.23 同时支持 OpenSSL 1.x
+与 3.x，因此直接使用系统的 OpenSSL（任意版本）。CMake 通过 `find_package(OpenSSL)`
+解析系统 OpenSSL，找不到时回退到从源码构建 OpenSSL 3.5.0；并会把所用的 OpenSSL
+动态库一并复制到产物 `lib/` 目录。Windows 可用 `choco install openssl` 安装。
+直接使用 CMake 时传入 `-DWITH_SSL=OFF`、`-DIOTDB_OFFLINE=ON` 等即可。
 Debug 构建请在配置阶段传入 `-DCMAKE_BUILD_TYPE=Debug`。Windows 使用 Visual
 Studio 生成器时也需要传入该选项，以便内置 Thrift 静态库使用 Debug MSVC 运行时；
 随后用 `cmake --build build --config Debug --target install` 构建安装。

diff --git a/iotdb-client/client-cpp/cmake/FetchBuildTools.cmake b/iotdb-client/client-cpp/cmake/FetchBuildTools.cmake
@@ -253,8 +253,23 @@ if(NOT FLEX_EXECUTABLE)
 endif()
 message(STATUS "[BuildTools] flex  = ${FLEX_EXECUTABLE}")
 
-# bison
+# bison - Thrift 0.23's grammar build uses bison >= 3.7 features (e.g. the
+# --file-prefix-map option), so reject an older system bison (manylinux_2_28
+# ships 3.0.4) and build ${BISON_VERSION} from source instead.
+set(_bison_min_version "3.7")
 find_program(BISON_EXECUTABLE bison)
+if(BISON_EXECUTABLE)
+    execute_process(COMMAND "${BISON_EXECUTABLE}" --version
+            OUTPUT_VARIABLE _bison_ver_out ERROR_QUIET
+            OUTPUT_STRIP_TRAILING_WHITESPACE)
+    string(REGEX MATCH "[0-9]+\\.[0-9]+(\\.[0-9]+)?" _bison_ver "${_bison_ver_out}")
+    if(_bison_ver AND _bison_ver VERSION_LESS _bison_min_version)
+        message(STATUS
+                "[BuildTools] system bison ${_bison_ver} < ${_bison_min_version} "
+                "(too old for Thrift ${THRIFT_VERSION}); building ${BISON_VERSION} from source")
+        unset(BISON_EXECUTABLE CACHE)
+    endif()
+endif()
 if(NOT BISON_EXECUTABLE)
     _iotdb_resolve_tarball(_bison_tarball "bison-${BISON_VERSION}.tar.gz" "${_bison_url}")
     _iotdb_build_autotools(bison "${_bison_tarball}" "bison-${BISON_VERSION}")