Feature: Digital Signature Verification for HDF5 Plugins

.github/workflows/signed-plugins.yml

@@ -0,0 +1,141 @@
+name: Test Signed Plugins
+
+on:
+  push:
+    branches: [ develop ]
+  pull_request:
+    branches: [ develop ]
+
+permissions:
+  contents: read
+
+env:
+  CTEST_OUTPUT_ON_FAILURE: 1
+
+jobs:
+  # Test signature verification across platforms and configurations
+  test-signed-plugins:
+    name: "${{ matrix.config.name }}"
+    runs-on: ${{ matrix.config.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          # Linux configurations
+          - name: "Linux Serial (Debug + Shared)"
+            os: ubuntu-latest
+            build_type: Debug
+            shared: ON
+            parallel: OFF
+            generator: ""
+
+          - name: "Linux Serial (Release + Static)"
+            os: ubuntu-latest
+            build_type: Release
+            shared: OFF
+            parallel: OFF
+            generator: ""
+
+          - name: "Linux Parallel (Debug + Shared)"
+            os: ubuntu-latest
+            build_type: Debug
+            shared: ON
+            parallel: ON
+            generator: ""
+
+          # macOS configuration
+          - name: "macOS Serial (Release + Shared)"
+            os: macos-latest
+            build_type: Release
+            shared: ON
+            parallel: OFF
+            generator: ""
+
+          # Windows configuration
+          - name: "Windows Serial (Release + Shared)"
+            os: windows-latest
+            build_type: Release
+            shared: ON
+            parallel: OFF
+            generator: "-A x64"
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Install dependencies (Linux)
+      if: runner.os == 'Linux'
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y \
+          libssl-dev \
+          zlib1g-dev \
+          libaec-dev
+
+    - name: Install MPI dependencies (Linux)
+      if: runner.os == 'Linux' && matrix.config.parallel == 'ON'
+      run: |
+        sudo apt-get install -y \
+          libopenmpi-dev \
+          openmpi-bin
+
+    - name: Install dependencies (macOS)
+      if: runner.os == 'macOS'
+      run: |
+        brew install openssl@3
+
+    - name: Generate test RSA key pair (Unix)
+      if: runner.os != 'Windows'
+      run: |
+        openssl genrsa -out ci-test-private.pem 2048
+        openssl rsa -in ci-test-private.pem -pubout -out ci-test-public.pem
+        mkdir -p ci-keystore
+        cp ci-test-public.pem ci-keystore/
+
+    - name: Generate test RSA key pair (Windows)
+      if: runner.os == 'Windows'
+      shell: pwsh
+      run: |
+        & openssl genrsa -out ci-test-private.pem 2048
+        & openssl rsa -in ci-test-private.pem -pubout -out ci-test-public.pem
+        New-Item -ItemType Directory -Force -Path ci-keystore
+        Copy-Item ci-test-public.pem ci-keystore/
+
+    - name: Configure CMake
+      shell: bash
+      run: |
+        EXTRA_FLAGS=""
+        if [ "${{ matrix.config.parallel }}" == "ON" ]; then
+          EXTRA_FLAGS="-DMPIEXEC_PREFLAGS=--oversubscribe"
+        fi
+        cmake -B build \
+          ${{ matrix.config.generator }} \
+          -DCMAKE_BUILD_TYPE=${{ matrix.config.build_type }} \
+          -DHDF5_REQUIRE_SIGNED_PLUGINS:BOOL=ON \
+          -DHDF5_PLUGIN_KEYSTORE_DIR="${PWD}/ci-keystore" \
+          -DHDF5_ENABLE_PARALLEL:BOOL=${{ matrix.config.parallel }} \
+          -DBUILD_SHARED_LIBS:BOOL=${{ matrix.config.shared }} \
+          -DBUILD_STATIC_LIBS:BOOL=ON \
+          -DBUILD_TESTING:BOOL=ON \
+          -DHDF5_BUILD_TOOLS:BOOL=ON \
+          -DHDF5_ENABLE_ZLIB_SUPPORT:BOOL=${{ runner.os == 'Linux' }} \
+          -DHDF5_ENABLE_SZIP_SUPPORT:BOOL=${{ runner.os == 'Linux' }} \
+          $EXTRA_FLAGS
+
+    - name: Build
+      run: cmake --build build --parallel 4 --config ${{ matrix.config.build_type }}
+
+    - name: Copy OpenSSL DLLs (Windows)
+      if: runner.os == 'Windows'
+      shell: pwsh
+      run: |
+        Copy-Item "C:\Program Files\OpenSSL\bin\libcrypto-3-x64.dll" build\bin\${{ matrix.config.build_type }}\
+        Copy-Item "C:\Program Files\OpenSSL\bin\libssl-3-x64.dll" build\bin\${{ matrix.config.build_type }}\
+        # Restrict test keystore ACLs so permission check passes
+        icacls build\test_keystore /inheritance:r /grant "${env:USERNAME}:(OI)(CI)F" /grant "Administrators:(OI)(CI)F"
+
+    - name: Run Tests
+      shell: bash
+      run: |
+        cd build
+        ctest --build-config ${{ matrix.config.build_type }} --parallel 4 --output-on-failure

CMakeLists.txt

@@ -781,6 +781,88 @@ if (HDF5_ENABLE_HDFS)
   endif ()
 endif ()
 
+#-----------------------------------------------------------------------------
+# Option to Require Digitally Signed plugins
+#-----------------------------------------------------------------------------
+option (HDF5_REQUIRE_SIGNED_PLUGINS "Require digitally signed plugins" OFF)
+
+cmake_dependent_option (HDF5_LOCK_PLUGIN_KEYSTORE "Disable HDF5_PLUGIN_KEYSTORE environment variable override (security hardening)" OFF "HDF5_REQUIRE_SIGNED_PLUGINS" OFF)
+mark_as_advanced(HDF5_LOCK_PLUGIN_KEYSTORE)
+
+if (HDF5_REQUIRE_SIGNED_PLUGINS)
+  # KeyStore directory for multiple trusted public keys
+  set(HDF5_PLUGIN_KEYSTORE_DIR "" CACHE PATH
+      "Directory containing trusted public keys (.pem files) for plugin verification")
+  # Find OpenSSL for RSA signature verification
+  find_package(OpenSSL REQUIRED)
+  if (NOT OPENSSL_FOUND)
+    message(FATAL_ERROR "OpenSSL is required for HDF5_REQUIRE_SIGNED_PLUGINS but was not found")
+  endif ()
+
+  # Check minimum OpenSSL version
+  # The signature verification implementation uses modern EVP API (EVP_DigestVerifyInit,
+  # EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal) which requires OpenSSL 1.1.0+
+  if (OPENSSL_VERSION VERSION_LESS "1.1.0")
+    message(FATAL_ERROR
+      "OpenSSL 1.1.0 or later is required for HDF5_REQUIRE_SIGNED_PLUGINS\n"
+      "  Found: OpenSSL ${OPENSSL_VERSION}\n"
+      "  Required: OpenSSL 1.1.0 or later\n"
+      "\n"
+      "The signature verification implementation uses modern EVP API which is not\n"
+      "available in OpenSSL 1.0.2 and earlier versions.\n"
+      "\n"
+      "Solutions:\n"
+      "  1. Upgrade to OpenSSL 3.0 or later (recommended)\n"
+      "     - OpenSSL 3.0 is LTS (supported until 2026-09-07)\n"
+      "     - OpenSSL 3.4+ is also supported\n"
+      "  2. Use LibreSSL 2.7.0 or later (compatible alternative)\n"
+      "  3. Disable signed plugins: -DHDF5_REQUIRE_SIGNED_PLUGINS=OFF\n"
+      "\n"
+      "Note: OpenSSL 1.0.2 reached end-of-life in December 2019\n"
+      "      CentOS 7 users should install openssl11 package")
+  endif ()
+
+  # Informational message for OpenSSL 3.0+ (APIs are compatible, not deprecated)
+  if (OPENSSL_VERSION VERSION_GREATER_EQUAL "3.0.0")
+    message(STATUS "OpenSSL 3.0+ detected - all EVP_* APIs are compatible (not deprecated)")
+  endif ()
+
+  # KeyStore directory is optional at build time; the HDF5_PLUGIN_KEYSTORE
+  # environment variable can be used at runtime instead.  Require a compile-time
+  # directory only when the environment variable override is locked out.
+  if (HDF5_LOCK_PLUGIN_KEYSTORE AND NOT HDF5_PLUGIN_KEYSTORE_DIR)
+    message(FATAL_ERROR
+      "HDF5_LOCK_PLUGIN_KEYSTORE=ON requires a compile-time KeyStore directory:\n"
+      "  -DHDF5_PLUGIN_KEYSTORE_DIR=/etc/hdf5/trusted_keys")
+  endif ()
+
+  # Configure KeyStore directory if provided.
+  # Note: the path is embedded as a string literal in the library binary.
+  # Use the HDF5_PLUGIN_KEYSTORE environment variable instead if the path
+  # should not be visible in the binary.
+  if (HDF5_PLUGIN_KEYSTORE_DIR)
+    add_compile_definitions(H5PL_KEYSTORE_DIR="${HDF5_PLUGIN_KEYSTORE_DIR}")
+  else ()
+    message(NOTICE "No compile-time KeyStore directory configured; "
+      "set HDF5_PLUGIN_KEYSTORE environment variable at runtime.")
+  endif ()
+
+  # Enable digital signature verification (goes into H5pubconf.h)
+  set(H5_REQUIRE_DIGITAL_SIGNATURE 1)
+
+  # Security: Disable environment variable override if requested
+  if (HDF5_LOCK_PLUGIN_KEYSTORE)
+    add_compile_definitions(H5PL_DISABLE_ENV_KEYSTORE)
+    message(VERBOSE "HDF5_PLUGIN_KEYSTORE environment variable override: DISABLED (security hardening)")
+  endif ()
+
+  # Add OpenSSL to link libraries for the HDF5 library
+  # Only libcrypto is needed (EVP, PEM, BIO, ERR APIs); libssl (TLS) is not used
+  list(APPEND LINK_LIBS OpenSSL::Crypto)
+
+  message(VERBOSE "Digital signature verification enabled (OpenSSL ${OPENSSL_VERSION})")
+endif ()
+
 #-----------------------------------------------------------------------------
 # Option to Enable MPI Parallel
 #-----------------------------------------------------------------------------

config/cmake/SignPlugin.cmake

@@ -0,0 +1,52 @@
+#
+# Copyright by The HDF Group.
+# All rights reserved.
+#
+# This file is part of HDF5. The full HDF5 copyright notice, including
+# terms governing use, modification, and redistribution, is contained in
+# the COPYING file, which can be found at the root of the source code
+# distribution tree, or in https://www.hdfgroup.org/licenses.
+# If you do not have access to either file, you may request a copy from
+# help@hdfgroup.org.
+#
+
+#[=======================================================================[.rst:
+SignPlugin
+----------
+
+Provides a CMake function to sign plugin libraries when HDF5_REQUIRE_SIGNED_PLUGINS is enabled.
+
+.. command:: sign_plugin_target
+
+  Signs a plugin target using the h5sign tool.
+
+  .. code-block:: cmake
+
+    sign_plugin_target(<target> <plugin_dir>)
+
+  ``target``
+    The CMake target to sign (must be a shared library plugin)
+
+  ``plugin_dir``
+    The directory where the plugin will be located after build
+
+  This function adds a post-build command that:
+  - Signs the plugin using the h5sign tool
+  - Uses the test private key (${CMAKE_BINARY_DIR}/private.pem)
+  - Only executes if HDF5_REQUIRE_SIGNED_PLUGINS is enabled
+
+#]=======================================================================]
+
+function(sign_plugin_target TARGET PLUGIN_DIR)
+  if (HDF5_REQUIRE_SIGNED_PLUGINS)
+    add_dependencies(${TARGET} h5sign)
+    add_custom_command(
+      TARGET ${TARGET}
+      POST_BUILD
+      COMMAND $<TARGET_FILE:h5sign>
+      ARGS -p "${PLUGIN_DIR}/$<TARGET_FILE_NAME:${TARGET}>"
+           -k "${CMAKE_BINARY_DIR}/private.pem"
+      COMMENT "Signing test plugin ${TARGET} for signature verification"
+    )
+  endif()
+endfunction()

config/cmake/runExecute.cmake

@@ -47,7 +47,7 @@ macro (STREAM_STRINGS stream strings_out)
 endmacro()
 
 macro (EXECUTE_TEST)
-  cmake_parse_arguments (TEST "" "NOERRDISPLAY;EXPECT;JAVA;CLASSPATH;PROGRAM;FOLDER;OUTPUT;LIBRARY_DIRECTORY;INPUT;ENV_VAR;ENV_VALUE;EMULATOR;ARGS" "TEST_" ${ARGN})
+  cmake_parse_arguments (TEST "" "NOERRDISPLAY;EXPECT;JAVA;CLASSPATH;PROGRAM;FOLDER;OUTPUT;LIBRARY_DIRECTORY;INPUT;ENV_VAR;ENV_VALUE;KEYSTORE_DIR;EMULATOR;ARGS" "TEST_" ${ARGN})
 if (NOT TEST_PROGRAM)
   message (FATAL_ERROR "Require TEST_PROGRAM to be defined")
 endif ()
@@ -88,6 +88,11 @@ if (TEST_ENV_VAR)
   message (TRACE "ENV:${TEST_ENV_VAR}=$ENV{${TEST_ENV_VAR}}")
 endif ()
 
+if (TEST_KEYSTORE_DIR)
+  set (ENV{HDF5_PLUGIN_KEYSTORE} "${TEST_KEYSTORE_DIR}")
+  message (TRACE "ENV:HDF5_PLUGIN_KEYSTORE=$ENV{HDF5_PLUGIN_KEYSTORE}")
+endif ()
+
 if (NOT TEST_JAVA)
   message (STATUS "COMMAND: ${TEST_EMULATOR} ${TEST_PROGRAM} ${TEST_ARGS}")
   if (NOT TEST_INPUT)

config/cmake/runTest.cmake

@@ -42,6 +42,7 @@ EXECUTE_TEST (TEST_FOLDER ${TEST_FOLDER}
                TEST_LIBRARY_DIRECTORY ${TEST_LIBRARY_DIRECTORY}
                TEST_ENV_VAR ${TEST_ENV_VAR}
                TEST_ENV_VALUE ${TEST_ENV_VALUE}
+               TEST_KEYSTORE_DIR ${TEST_KEYSTORE_DIR}
                TEST_INPUT ${TEST_INPUT}
                TEST_CLASSPATH ${TEST_CLASSPATH}
                TEST_NOERRDISPLAY ${TEST_NOERRDISPLAY}

release_docs/CHANGELOG.md

@@ -92,6 +92,10 @@ We would like to thank the many HDF5 community members who contributed to this r
 
 ## Library
 
+### Added optional digital signature verification for dynamically loaded plugins
+
+   When built with `-DHDF5_REQUIRE_SIGNED_PLUGINS=ON` and OpenSSL, HDF5 will cryptographically verify each plugin before loading it. Plugins are signed with the new `h5sign` tool, which appends an RSA signature and a compact footer to the plugin binary. Verification uses a keystore directory of trusted public keys, configurable at compile time (`-DHDF5_PLUGIN_KEYSTORE_DIR=<path>`) or at runtime via the `HDF5_PLUGIN_KEYSTORE` environment variable. Individual signatures can be revoked without removing the entire public key by listing their SHA-256 hashes in a `revoked_signatures.txt` file in the keystore directory. Supported algorithms include SHA-256, SHA-384, and SHA-512 with both PKCS#1 v1.5 and PSS padding. See `release_docs/PLUGIN_SIGNATURE_README.md` for details.
+
 ### Improve performance of H5Ovisit() with deeply nested group structures
 
    `H5Ovisit()` would previously internally traverse each object's path name from the iteration root group in order to retrieve information about that object, causing severe performance degradation with a deeply nested group structure. Modified the algorithm to instead retrieve information directly from the object. To get this benefit, users should use `H5Ovisit3()`, or use `H5Ovisit2()` with neither `H5O_INFO_HDR` nor `H5O_INFO_META_SIZE` selected in the `fields` parameter. Performance of `H5Ocopy()`, `H5Iget_name()`, and external links with a callback set should also improve in similar situations.
@@ -106,6 +110,10 @@ We would like to thank the many HDF5 community members who contributed to this r
 
 ## Tools
 
+### Added `h5sign` tool for signing plugins with RSA digital signatures
+
+   The `h5sign` command-line tool signs HDF5 plugin shared libraries by appending an RSA signature and a 12-byte footer. It supports SHA-256, SHA-384, SHA-512, and their PSS variants, and accepts passphrase-protected private keys. Use `-f` / `--force` to strip an existing signature before re-signing. The tool is built automatically when `HDF5_REQUIRE_SIGNED_PLUGINS` is enabled.
+
 ## High-Level APIs
 
 ## C Packet Table API