Skip to content

C++ client: build with OpenSSL 3.x by default and bundle the runtime …#17987

Open
hongzhi-gao wants to merge 2 commits into
apache:masterfrom
hongzhi-gao:pr/cpp-client-openssl3
Open

C++ client: build with OpenSSL 3.x by default and bundle the runtime …#17987
hongzhi-gao wants to merge 2 commits into
apache:masterfrom
hongzhi-gao:pr/cpp-client-openssl3

Conversation

@hongzhi-gao

@hongzhi-gao hongzhi-gao commented Jun 18, 2026

Copy link
Copy Markdown
Contributor

Enables SSL for the C++ session client out of the box and ships a self-contained package.

What

  • Default WITH_SSL / with.ssl to ON (CMake + Maven), so the client and the CI packaging/verify jobs build with SSL by default.
  • Bundle the OpenSSL shared libraries into the package lib/ (new InstallOpenSSLRuntime.cmake) so the SDK runs on machines without a system OpenSSL. iotdb_session gets an $ORIGIN / @loader_path runtime path, and the examples copy the bundled libs next to their binaries, so the package is self-contained (verified the example smoke test resolves the bundled libssl.so.3, not a system one).
  • Bump the bundled Apache Thrift 0.21.0 -> 0.23.0.

OpenSSL version

  • Use OpenSSL 3.x (Apache-2.0 License | OpenSSL Library ). OpenSSL 1.1.1 is EOL and not Apache-2.0, so it is never linked or redistributed.
  • Note: OpenSSL 4.0 removed the legacy TLS-method APIs (TLSv1_method, SSLv3_method, ASN1_STRING_data) that Thrift's TSSLSocket still calls, so the CI pins OpenSSL 3.x rather than installing the latest.
  • find_package(OpenSSL) uses the system OpenSSL when present; otherwise it builds OpenSSL 3.5.0 from source as shared libraries. The Linux packaging build forces the from-source build (-DIOTDB_OPENSSL_FROM_SOURCE=ON) because the manylinux_2_28 / AlmaLinux 8 baseline ships OpenSSL 1.1.1, preserving the glibc 2.28 floor while shipping 3.x.

Build tooling

  • Build bison >= 3.7 from source when the system bison is too old for Thrift 0.23's grammar build (manylinux ships 3.0.4).
  • Encode WITH_SSL in the bundled-Thrift build stamp and forward OPENSSL_ROOT_DIR so Thrift's TSSLSocket links the same OpenSSL that is bundled.

CI

  • Install/point at OpenSSL 3.x (not 4.0): Windows uses a pinned prebuilt OpenSSL 3.5.x; macOS uses brew openssl@3; the manylinux job builds 3.x from source (installs the perl modules OpenSSL's Configure needs).

Tested

  • https://github.com/hongzhi-gao/iotdb/actions/runs/27747857268
  • Windows (MSVC / VS2022): iotdb_session.dll links and imports libssl-3-x64.dll / libcrypto-3-x64.dll, both bundled into lib/.
  • Linux (Ubuntu via WSL): from-source OpenSSL 3.5.0 shared build, libiotdb_session.so has RUNPATH=$ORIGIN and the bundled libssl.so.3 / libcrypto.so.3 are resolved in preference to the system OpenSSL.

…libs

Enables SSL for the C++ session client out of the box and ships a
self-contained package.

What
- Default WITH_SSL / with.ssl to ON (CMake + Maven), so the client and the
  CI packaging/verify jobs build with SSL by default.
- Bundle the OpenSSL shared libraries into the package lib/ (new
  InstallOpenSSLRuntime.cmake) so the SDK runs on machines without a system
  OpenSSL. iotdb_session gets an $ORIGIN / @loader_path runtime path, and the
  examples copy the bundled libs next to their binaries, so the package is
  self-contained (verified the example smoke test resolves the bundled
  libssl.so.3, not a system one).
- Bump the bundled Apache Thrift 0.21.0 -> 0.23.0.

OpenSSL version
- Use OpenSSL 3.x (Apache-2.0). OpenSSL 1.1.1 is EOL and not Apache-2.0, so it
  is never linked or redistributed.
- Note: OpenSSL 4.0 removed the legacy TLS-method APIs (TLSv1_method,
  SSLv3_method, ASN1_STRING_data) that Thrift's TSSLSocket still calls, so the
  CI pins OpenSSL 3.x rather than installing the latest.
- find_package(OpenSSL) uses the system OpenSSL when present; otherwise it
  builds OpenSSL 3.5.0 from source as shared libraries. The Linux packaging
  build forces the from-source build (-DIOTDB_OPENSSL_FROM_SOURCE=ON) because
  the manylinux_2_28 / AlmaLinux 8 baseline ships OpenSSL 1.1.1, preserving the
  glibc 2.28 floor while shipping 3.x.

Build tooling
- Build bison >= 3.7 from source when the system bison is too old for Thrift
  0.23's grammar build (manylinux ships 3.0.4).
- Encode WITH_SSL in the bundled-Thrift build stamp and forward OPENSSL_ROOT_DIR
  so Thrift's TSSLSocket links the same OpenSSL that is bundled.

CI
- Install/point at OpenSSL 3.x (not 4.0): Windows uses a pinned prebuilt
  OpenSSL 3.5.x; macOS uses brew openssl@3; the manylinux job builds 3.x from
  source (installs the perl modules OpenSSL's Configure needs).

Tested
- Windows (MSVC / VS2022): iotdb_session.dll links and imports
  libssl-3-x64.dll / libcrypto-3-x64.dll, both bundled into lib/.
- Linux (Ubuntu via WSL): from-source OpenSSL 3.5.0 shared build,
  libiotdb_session.so has RUNPATH=$ORIGIN and the bundled libssl.so.3 /
  libcrypto.so.3 are resolved in preference to the system OpenSSL.
Bundling/static-linking third-party components requires reproducing their
notices in the binary distribution.

- Add third_party/NOTICE attributing the redistributed components: Apache
  Thrift (statically linked, Apache-2.0, incl. its NOTICE text), OpenSSL
  (bundled shared libs, Apache-2.0), and Boost (statically linked, BSL-1.0).
- Add third_party/licenses/LICENSE-Boost-1.0 (BSL-1.0 is not Apache-2.0).
  Apache-2.0 components are covered by the package's top-level LICENSE.
- Ship third_party/NOTICE and third_party/licenses/ in the package (assembly).
- DEPENDENCIES.md: split redistributed (Thrift/Boost/OpenSSL) from build-only
  tools (m4/flex/bison), which are not in the distributed binary.
- apache-rat: exclude the bundled third-party NOTICE / license texts (they must
  not carry an ASF header).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant