Skip to content

feat: S17.01 OpenSSL HMAC-SHA256 at-rest SecurityPolicy (Linux + Windows)#499

Merged
DavidCozens merged 5 commits into
mainfrom
feat/s17-01-openssl-hmac-sha256
May 31, 2026
Merged

feat: S17.01 OpenSSL HMAC-SHA256 at-rest SecurityPolicy (Linux + Windows)#499
DavidCozens merged 5 commits into
mainfrom
feat/s17-01-openssl-hmac-sha256

Conversation

@DavidCozens

@DavidCozens DavidCozens commented May 31, 2026

Copy link
Copy Markdown
Owner

Purpose

Closes #498. Adds SolidSyslogOpenSslHmacSha256Policy, the OpenSSL sibling of S17.02's mbedTLS HMAC policy (#493), delivering cryptographic at-rest integrity (IEC 62443 SR 3.4, SL3/SL4) on Linux and Windows via the shared Platform/OpenSsl/. Purely additive — the keyed-policy vtable shape (self + bool return) already landed in S17.02, and per the E17 correction the SealRecord/OpenRecord/TrailerSize reshape stays deferred to S17.03.

Change Description

The policy is almost entirely platform-agnostic — across the six S17.02 files only three lines touch the crypto backend — so this is a structural mirror with the crypto core swapped, driven test-first to the same refactored end state as the sibling (same function ordering, intent-named helpers, shared ComputeTag, error-source/_Report split).

  • Crypto swap only: mbedtls_md_hmacHMAC(EVP_sha256(), …) (one-shot, not deprecated in OpenSSL 3.x); mbedtls_platform_zeroizeOPENSSL_cleanse. Same key-on-demand contract (SolidSyslogKeyFunction; key fetched into a stack buffer per operation and wiped). The hand-rolled ConstantTimeEquals is kept (not swapped for CRYPTO_memcmp) to keep the two platform siblings symmetrical.
  • New tunable SOLIDSYSLOG_OPEN_SSL_HMAC_SHA256_POLICY_POOL_SIZE (default 1); reuses SOLIDSYSLOG_MAX_HMAC_KEY_SIZE. Sources compiled into libSolidSyslog via Platform/OpenSsl/CMakeLists.txt.
  • OpenSslFake gains deterministic HMAC / EVP_sha256 / OPENSSL_cleanse interposition (mirrors MbedTlsFake_ComputeExpectedTag) so the policy is unit-tested without real libcrypto.
  • --security-policy null|crc16|hmac-sha256 selector ported to the Linux and Windows BDD targets (both previously hard-coded CRC-16), dispatching to the OpenSSL policy with a demo-only GetKey. The existing @hmac power-cycle-replay scenario now runs on the Linux (syslog-ng) and Windows (OTEL) runners — @hmac dropped from both behave tag filters; FreeRTOS-lwip stays excluded via @store.
  • MISRA: mirrored the sibling's three deviations (11.3 downcast, 5.7 shared enum tag, 8.7 public extern error-source under D.014).

Out of scope (per #498): integration-harness coverage (unit + BDD only); the Seal/Open reshape and AES-256-GCM (S17.03); key management.

Test Evidence

Driven red-green-refactor against OpenSslFake, mirroring the S17.02 test:

  • 19 policy tests (Tests/SolidSyslogOpenSslHmacSha256PolicyTest.cpp): create/distinct-from-fallback, IntegritySize == 32, pool exhaustion + error, NULL config / NULL GetKey + bad-config error, config-lock acquire/release on create + destroy, unknown/stale-handle destroy warnings, HMAC-with-fetched-key, tag written to buffer, HMAC-failure + key-unavailable reporting, key-buffer wiped after use, verify round-trip / tamper rejection / fail-closed-when-key-unavailable.
  • 5 parser tests added to BddTargetCommandLineTest (default crc16, crc16/hmac-sha256/null accepted, invalid rejected).
  • Local (debug preset, container): SolidSyslogTests 1358/1358, BddTargetTests 53/53, OpenSslIntegrationTests 9/9 — all green.
  • Gates run locally: cppcheck-misra (0 unsuppressed violations tree-wide), IWYU (clean on all touched files), clang-format --dry-run --Werror (clean tree-wide). BDD scenarios themselves run in CI.

Areas Affected

  • Platform/OpenSsl/{Interface,Source}/ — new policy (6 files), compiled into libSolidSyslog.
  • Core/Interface/SolidSyslogTunablesDefaults.h — new pool-size tunable.
  • Tests/Support/OpenSslFake.{c,h}, Tests/, Tests/Bdd/Targets/ — fake interposition + tests.
  • Bdd/Targets/{Linux,Windows}/--security-policy selector; ci/docker-compose.bdd.yml + .github/workflows/ci.yml (Windows) — @hmac enabled.
  • misra_suppressions.txt, docs/misra-deviations.md (D.014 scope), DEVLOG.md.
  • No change to existing public API or to derived projects beyond the additive header.

Note for review: the CLAUDE.md header-audiences table has no row for either HMAC policy (S17.02 didn't add the mbedTLS one); left consistent rather than documenting one sibling unilaterally — flagged in the DEVLOG for a doc-sweep decision.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Added OpenSSL HMAC-SHA256 at-rest security policy support on Linux and Windows platforms.
    • Added --security-policy command-line option to select between crc16, hmac-sha256, and null integrity policies (default: crc16).
  • Tests

    • Extended test coverage for the new security policy selection option and OpenSSL HMAC-SHA256 functionality.
  • Documentation

    • Updated feature documentation and MISRA deviations to reflect OpenSSL HMAC-SHA256 support.

DavidCozens and others added 4 commits May 31, 2026 19:59
OpenSSL sibling of the mbedTLS HMAC policy (S17.02). Same key-on-demand
contract (SolidSyslogKeyFunction; key fetched per operation, wiped with
OPENSSL_cleanse), same pool/lifecycle/error shape — only the crypto core
differs: HMAC(EVP_sha256(), ...) and OPENSSL_cleanse in place of
mbedtls_md_hmac / mbedtls_platform_zeroize.

- Platform/OpenSsl/{Interface,Source}/SolidSyslogOpenSslHmacSha256Policy*
- SOLIDSYSLOG_OPEN_SSL_HMAC_SHA256_POLICY_POOL_SIZE tunable (default 1)
- OpenSslFake gains deterministic HMAC/EVP_sha256/OPENSSL_cleanse
  interposition; unit test driven against it (lifecycle, pool, bad-config,
  round-trip, tamper, wrong-key, key-unavailable, key-wipe)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…BDD targets

Both targets gain the --security-policy null|crc16|hmac-sha256 selector
(ported from the FreeRTOS parser) dispatching to the OpenSSL HMAC policy,
with a demo-only GetKey. The existing @hmac power-cycle-replay scenario now
runs on the Linux (syslog-ng) and Windows (OTEL) runners too — the @hmac
exclusion is dropped from both behave tag filters. FreeRTOS-lwip stays
excluded via @store.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Mirror the mbedTLS sibling's three deviations for the new OpenSSL HMAC
policy TUs: 11.3 (downcast in SelfFromBase), 5.7 (shared HMAC_SHA256_TAG_SIZE
enum tag), 8.7 (public extern error-source object, D.014). Verified with the
CI cppcheck-misra invocation: 0 unsuppressed violations tree-wide.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented May 31, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

@DavidCozens, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 46 minutes and 35 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b010cf43-787d-411c-901d-6949a53154be

📥 Commits

Reviewing files that changed from the base of the PR and between 7213f85 and 2cca1f9.

📒 Files selected for processing (1)
  • Bdd/Targets/Linux/BddTargetCommandLine.c
📝 Walkthrough

Walkthrough

This PR implements the OpenSSL HMAC-SHA256 at-rest SecurityPolicy (S17.01), adding configurable cryptographic integrity for syslog records on Linux and Windows. Core policy files mirror the mbedTLS sibling with OpenSSL crypto primitives. Linux and Windows BDD targets gain --security-policy CLI selector and runtime integration. Test infrastructure and comprehensive unit tests validate seal/verify semantics and key-wipe behavior. BDD scenarios re-enabled to verify HMAC-SHA256 in power-cycle replay.

Changes

OpenSSL HMAC-SHA256 Integrity Policy and BDD Integration

Layer / File(s) Summary
OpenSSL HMAC-SHA256 policy public contract and error definitions
Platform/OpenSsl/Interface/SolidSyslogOpenSslHmacSha256Policy.h, Platform/OpenSsl/Interface/SolidSyslogOpenSslHmacSha256PolicyErrors.h
Public-facing structs and function declarations define config with key callback, create/destroy API, and error enum with error-source export for the OpenSSL HMAC policy.
OpenSSL HMAC-SHA256 policy seal/verify and lifecycle
Platform/OpenSsl/Source/SolidSyslogOpenSslHmacSha256PolicyPrivate.h, Platform/OpenSsl/Source/SolidSyslogOpenSslHmacSha256Policy.c, Platform/OpenSsl/Source/SolidSyslogOpenSslHmacSha256PolicyMessages.c
Core integrity computation using HMAC(EVP_sha256(), …) with on-demand key fetching and post-use OPENSSL_cleanse wiping; constant-time tag comparison for verification; error message lookup and reporting.
OpenSSL HMAC-SHA256 policy pool, static create/destroy, and tunable
Core/Interface/SolidSyslogTunablesDefaults.h, Platform/OpenSsl/Source/SolidSyslogOpenSslHmacSha256PolicyStatic.c
Fixed-size policy pool allocator with config validation, create function acquiring and initializing slots, destroy function releasing slots with cleanup, and SOLIDSYSLOG_OPEN_SSL_HMAC_SHA256_POLICY_POOL_SIZE tunable (default 1U).
OpenSSL platform CMake configuration
Platform/OpenSsl/CMakeLists.txt
Build configuration adds three OpenSSL HMAC-SHA256 policy source files to libSolidSyslog compilation.
Linux BDD target --security-policy option
Bdd/Targets/Linux/BddTargetCommandLine.h, Bdd/Targets/Linux/BddTargetCommandLine.c, Tests/Bdd/Targets/BddTargetCommandLineTest.cpp
Linux command-line parser adds SecurityPolicy field to options, implements validation of crc16/hmac-sha256/null values, wires --security-policy flag, and includes test cases for default and flag-driven behavior.
Windows BDD target --security-policy option
Bdd/Targets/Windows/BddTargetWindowsCommandLine.h, Bdd/Targets/Windows/BddTargetWindowsCommandLine.c
Windows command-line parser adds SecurityPolicy field to options and implements argv iteration to accept and assign --security-policy value.
Linux BDD target security-policy runtime selection and lifecycle
Bdd/Targets/Linux/main.c
Adds demo HMAC key provider, creates selected policy (hmac-sha256/null/crc16) based on CLI option, wires policy to file-store config, and releases policy during store teardown.
Windows BDD target security-policy runtime selection and lifecycle
Bdd/Targets/Windows/BddTargetWindows.c
Adds demo HMAC key provider, creates selected policy (hmac-sha256/null/crc16) based on CLI option, wires policy to BlockStore config, and releases policy during store teardown with proper lifecycle handling.
OpenSSL fake for HMAC and key-wipe verification
Tests/Support/OpenSslFake.h, Tests/Support/OpenSslFake.c
Test support interposes EVP_sha256, HMAC, and OPENSSL_cleanse; adds deterministic tag generation and captured-state tracking (call counts, key/input buffers, lengths) with test accessors.
Unit test suite for OpenSSL HMAC-SHA256 policy
Tests/CMakeLists.txt, Tests/SolidSyslogOpenSslHmacSha256PolicyTest.cpp
Comprehensive CppUTest suite covering policy creation (handle types, pool exhaustion, bad config), destruction (cleanup, unknown handles), seal/integrity (HMAC invocation, tag output, key wiping), and verify (authentic tags, tampering, unavailable keys).
BDD scenario updates and CI tag filter changes
Bdd/features/power_cycle_replay.feature, ci/docker-compose.bdd.yml, .github/workflows/ci.yml
BDD feature file narrative updated to document HMAC-SHA256-at-rest across FreeRTOS-plustcp and Linux/Windows; CI workflows remove @hmac tag exclusions to enable HMAC tests.
DEVLOG entry and MISRA deviations documentation
DEVLOG.md, docs/misra-deviations.md, misra_suppressions.txt
DEVLOG documents S17.01 copy-mirror strategy and scope; MISRA D.014 scope expanded to include OpenSSL error-source file; suppressions added for OpenSSL policy files.

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

  • DavidCozens/solid-syslog#498 — This PR directly implements the S17.01 story objectives: OpenSSL HMAC-SHA256 SecurityPolicy (pool/static/lifecycle), CLI selector on Linux/Windows, test infrastructure, and BDD scenario integration.
  • DavidCozens/solid-syslog#493 — The mbedTLS HMAC-SHA256 story (S17.02) that provided the structural template for this PR's OpenSSL implementation; both define the same per-instance pooled HMAC policy concept with Create/Destroy API, error sources, tunable pool sizes, and seal/verify behavior.
  • DavidCozens/solid-syslog#105 — Parent epic for S17 cryptographic integrity stories; this PR completes the OpenSSL HMAC-SHA256 sibling within the at-rest SecurityPolicy feature.

Possibly related PRs

  • DavidCozens/solid-syslog#156 — Both PRs modify GitHub Actions ci.yml Windows BDD behave --tags=... filter to remove @hmac exclusion and enable HMAC-backed scenarios in the Windows CI lane.
  • DavidCozens/solid-syslog#100 — Both PRs update Bdd/features/power_cycle_replay.feature; this PR updates the HMAC-SHA256-at-rest scope/narrative that the retrieved PR introduced.

Poem

🐰 A cryptographic feast for records at rest,
With OpenSSL HMAC serving up integrity best,
From Linux to Windows, the policy pools align,
Keys wiped clean, constants compared—security divine! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 9.78% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The PR title 'feat: S17.01 OpenSSL HMAC-SHA256 at-rest SecurityPolicy (Linux + Windows)' is clear, specific, and accurately describes the main change — adding OpenSSL-backed HMAC-SHA256 integrity policy for Linux and Windows platforms.
Description check ✅ Passed The PR description comprehensively covers Purpose (issue closure #498), Change Description (crypto swap details, tunables, fake updates, selector addition), Test Evidence (unit and parser test counts, validation results), and Areas Affected (file locations, module boundaries).
Linked Issues check ✅ Passed The changeset fully implements the scope of issue #498: adds SolidSyslogOpenSslHmacSha256Policy under Platform/OpenSsl with OpenSSL crypto swaps, introduces SOLIDSYSLOG_OPEN_SSL_HMAC_SHA256_POLICY_POOL_SIZE tunable, extends OpenSslFake for testing, wires --security-policy selector into Linux and Windows BDD targets, and runs @hmac power-cycle-replay scenarios on those platforms.
Out of Scope Changes check ✅ Passed All changes remain in scope: policy implementation (Platform/OpenSsl), test infrastructure (OpenSslFake, unit tests), BDD selectors and CI updates, tunables, and documentation — none address out-of-scope items like SealRecord/OpenRecord reshape, AES-256-GCM, or key management.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/s17-01-openssl-hmac-sha256

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions

Copy link
Copy Markdown
Contributor

☀️   Quality Summary

   🚦   build-linux-gcc: 100% successful (✔️ 1369 passed)
   🚦   build-freertos-host-tdd-plustcp: 100% successful (✔️ 1677 passed)
   🚦   build-linux-clang: 100% successful (✔️ 1316 passed)
   🚦   sanitize-linux-gcc: 100% successful (✔️ 1316 passed)
   🚦   integration-linux-openssl: 100% successful (✔️ 9 passed)
   🚦   integration-linux-mbedtls: 100% successful (✔️ 7 passed)
   🚦   integration-windows-openssl: No test results available
   🚦   bdd-linux-syslog-ng: 94% successful (✔️ 47 passed, 🙈 3 skipped)
   🚦   bdd-windows-otel: 90% successful (✔️ 45 passed, 🙈 5 skipped)
   🚦   bdd-freertos-qemu-plustcp: 86% successful (✔️ 43 passed, 🙈 7 skipped)
   🚦   bdd-freertos-qemu-lwip: 64% successful (✔️ 32 passed, 🙈 18 skipped)
   🚦   build-windows-msvc: 100% successful (✔️ 1169 passed)
   🚦   build-linux-tunable-override: 100% successful (✔️ 1316 passed)
   ⚠️   Clang-Tidy: 1 warning (high: 1)
   ⚠️   CPPCheck: No warnings


🚧   Error Messages

Quality Monitor Errors:
No matching report files found when using pattern '**/junit-integration-windows-openssl/cpputest_*.xml'! Configuration error for 'integration-windows-openssl'?

Created by Quality Monitor v1.14.0 (#f3859fd). More details are shown in the GitHub Checks Result.

Adding the --security-policy case pushed BddTargetCommandLine_Parse to
cognitive complexity 26 (clang-tidy threshold 25). Extract the getopt switch
into a static ApplyOption helper so _Parse is a thin driver loop — drops the
complexity well under threshold and reads top-down. Verified: tidy preset
clean on lib + BDD target + test targets; BddTargetTests 53/53 green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

☀️   Quality Summary

   🚦   build-linux-gcc: 100% successful (✔️ 1369 passed)
   🚦   build-freertos-host-tdd-plustcp: 100% successful (✔️ 1677 passed)
   🚦   build-linux-clang: 100% successful (✔️ 1316 passed)
   🚦   sanitize-linux-gcc: 100% successful (✔️ 1316 passed)
   🚦   integration-linux-openssl: 100% successful (✔️ 9 passed)
   🚦   integration-linux-mbedtls: 100% successful (✔️ 7 passed)
   🚦   integration-windows-openssl: No test results available
   🚦   bdd-linux-syslog-ng: 94% successful (✔️ 47 passed, 🙈 3 skipped)
   🚦   bdd-windows-otel: 90% successful (✔️ 45 passed, 🙈 5 skipped)
   🚦   bdd-freertos-qemu-plustcp: 86% successful (✔️ 43 passed, 🙈 7 skipped)
   🚦   bdd-freertos-qemu-lwip: 64% successful (✔️ 32 passed, 🙈 18 skipped)
   🚦   build-windows-msvc: 100% successful (✔️ 1169 passed)
   🚦   build-linux-tunable-override: 100% successful (✔️ 1316 passed)
   ⚠️   Clang-Tidy: No warnings
   ⚠️   CPPCheck: No warnings


🚧   Error Messages

Quality Monitor Errors:
No matching report files found when using pattern '**/junit-integration-windows-openssl/cpputest_*.xml'! Configuration error for 'integration-windows-openssl'?

Created by Quality Monitor v1.14.0 (#f3859fd). More details are shown in the GitHub Checks Result.

@github-actions

Copy link
Copy Markdown
Contributor

☀️   Quality Summary

   🚦   build-linux-gcc: 100% successful (✔️ 1369 passed)
   🚦   build-freertos-host-tdd-plustcp: 100% successful (✔️ 1677 passed)
   🚦   build-linux-clang: 100% successful (✔️ 1316 passed)
   🚦   sanitize-linux-gcc: 100% successful (✔️ 1316 passed)
   🚦   integration-linux-openssl: 100% successful (✔️ 9 passed)
   🚦   integration-linux-mbedtls: 100% successful (✔️ 7 passed)
   🚦   integration-windows-openssl: 100% successful (✔️ 9 passed)
   🚦   bdd-linux-syslog-ng: 94% successful (✔️ 47 passed, 🙈 3 skipped)
   🚦   bdd-windows-otel: 90% successful (✔️ 45 passed, 🙈 5 skipped)
   🚦   bdd-freertos-qemu-plustcp: 86% successful (✔️ 43 passed, 🙈 7 skipped)
   🚦   bdd-freertos-qemu-lwip: 64% successful (✔️ 32 passed, 🙈 18 skipped)
   🚦   build-windows-msvc: 100% successful (✔️ 1169 passed)
   🚦   build-linux-tunable-override: 100% successful (✔️ 1316 passed)
   ⚠️   Clang-Tidy: No warnings
   ⚠️   CPPCheck: No warnings


Created by Quality Monitor v1.14.0 (#f3859fd). More details are shown in the GitHub Checks Result.

@DavidCozens DavidCozens merged commit 08d347b into main May 31, 2026
52 of 53 checks passed
@DavidCozens DavidCozens deleted the feat/s17-01-openssl-hmac-sha256 branch May 31, 2026 20:46
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.

S17.01: Cryptographic integrity for at-rest records — HMAC-SHA256 (OpenSSL, Linux + Windows)

1 participant