CAMEL-23248 - Camel-PQC: Add stateful key usage tracking and warnings for XMSS/LMS

[oscerd]

Description

Target

• I checked that the commit is targeting the correct branch (Camel 4 uses the main branch)

Tracking

• If this is a large change, bug fix, or code improvement, I checked there is a JIRA issue filed for the change (usually before you start working on it).

Apache Camel coding standards and style

• I checked that each commit in the pull request has a meaningful subject line and body.

• I have run mvn clean install -DskipTests locally from root folder and I have committed all auto-generated changes.

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using build-all, build-dependents, skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[github-actions]

🧪 CI tested the following changed modules:

• catalog/camel-catalog
• components/camel-pqc
• dsl/camel-componentdsl
• dsl/camel-endpointdsl

All tested modules (72 modules)

• Camel :: All Components Sync point
• Camel :: All Components Sync point [pom]
• Camel :: Assembly
• Camel :: Assembly [pom]
• Camel :: Catalog :: CSimple Maven Plugin (deprecated) [maven-plugin]
• Camel :: Catalog :: CSimple Maven Plugin (deprecated) SUCCESS [ 1.430 s]
• Camel :: Catalog :: Camel Catalog
• Camel :: Catalog :: Camel Catalog [jar]
• Camel :: Catalog :: Camel Report Maven Plugin
• Camel :: Catalog :: Camel Report Maven Plugin [maven-plugin]
• Camel :: Catalog :: Camel Route Parser
• Camel :: Catalog :: Camel Route Parser [jar]
• Camel :: Catalog :: Console
• Camel :: Catalog :: Console [jar]
• Camel :: Catalog :: Dummy Component
• Camel :: Catalog :: Dummy Component [jar]
• Camel :: Catalog :: Lucene (deprecated)
• Camel :: Catalog :: Lucene (deprecated) [jar]
• Camel :: Catalog :: Maven
• Camel :: Catalog :: Maven [jar]
• Camel :: Catalog :: Suggest
• Camel :: Catalog :: Suggest [jar]
• Camel :: Component DSL
• Camel :: Component DSL [jar]
• Camel :: Coverage
• Camel :: Coverage [pom]
• Camel :: Docs
• Camel :: Docs [pom]
• Camel :: Endpoint DSL
• Camel :: Endpoint DSL [jar]
• Camel :: Endpoint DSL :: Support
• Camel :: Endpoint DSL :: Support [jar]
• Camel :: Integration Tests
• Camel :: Integration Tests [jar]
• Camel :: JBang :: Core
• Camel :: JBang :: Core [jar]
• Camel :: JBang :: Integration tests
• Camel :: JBang :: Integration tests [jar]
• Camel :: JBang :: MCP
• Camel :: JBang :: MCP [jar]
• Camel :: JBang :: Main
• Camel :: JBang :: Main [jar]
• Camel :: JBang :: Plugin :: Edit
• Camel :: JBang :: Plugin :: Edit [jar]
• Camel :: JBang :: Plugin :: Generate
• Camel :: JBang :: Plugin :: Generate [jar]
• Camel :: JBang :: Plugin :: Kubernetes
• Camel :: JBang :: Plugin :: Kubernetes [jar]
• Camel :: JBang :: Plugin :: Route Parser
• Camel :: JBang :: Plugin :: Route Parser [jar]
• Camel :: JBang :: Plugin :: Testing
• Camel :: JBang :: Plugin :: Testing [jar]
• Camel :: JBang :: Plugin :: Validate
• Camel :: JBang :: Plugin :: Validate [jar]
• Camel :: Kamelet Main
• Camel :: Kamelet Main [jar]
• Camel :: Launcher
• Camel :: Launcher [jar]
• Camel :: Launcher :: Container
• Camel :: Launcher :: Container [pom]
• Camel :: PQC
• Camel :: PQC [jar]
• Camel :: YAML DSL
• Camel :: YAML DSL [jar]
• Camel :: YAML DSL :: Deserializers
• Camel :: YAML DSL :: Deserializers [jar]
• Camel :: YAML DSL :: Maven Plugins
• Camel :: YAML DSL :: Maven Plugins [maven-plugin]
• Camel :: YAML DSL :: Validator
• Camel :: YAML DSL :: Validator [jar]
• Camel :: YAML DSL :: Validator Maven Plugin
• Camel :: YAML DSL :: Validator Maven Plugin [maven-plugin]

[gnodet]

@oscerd Thanks for this contribution! Since it's already merged, here are some findings that may warrant a follow-up:

1. Redundant condition in checkStatefulKeyBeforeSign()

In PQCProducer.java, after if (remaining < 0) { return; }, the next check if (remaining <= 0) is equivalent to remaining == 0. The <= is misleading since negative values were already handled.

2. Health check reads key from configuration, not from the producer

PQCStatefulKeyHealthCheck.doCall() reads configuration.getKeyPair(), but the producer stores its own keyPair field (set during doStart()). If these diverge, the health check would report stale/incorrect state.

3. Health check never reports degraded state

When the fraction remaining is below the warning threshold, the health check still reports UP. It computes fraction_remaining and warning_threshold as details but never calls builder.degraded(). Monitoring systems won't see any state change until the key is fully exhausted (DOWN).

4. No input validation on statefulKeyWarningThreshold

Values > 1.0 or < 0.0 are silently accepted. A value > 1.0 would trigger warnings on every signing operation; negative values silently disable warnings.

5. persistStatefulKeyStateAfterSign may call storeKey with null metadata

KeyMetadata metadata = klm.getKeyMetadata(keyId);
if (metadata != null) {
    metadata.updateLastUsed();
    klm.updateKeyMetadata(keyId, metadata);
}
klm.storeKey(keyId, keyPair, metadata);  // metadata could be null here

6. testKeyExhaustion doesn't test the Camel component

The test exercises BouncyCastle's XMSS directly, not the PQC producer. It doesn't verify that the producer's checkStatefulKeyBeforeSign() actually throws IllegalStateException when the key is exhausted.

7. Duplicated instanceof dispatch pattern

The instanceof XMSSPrivateKey / XMSSMTPrivateKey / LMSPrivateKey dispatch is repeated in 4 places (getStatefulKeyRemaining, getStatefulKeyIndex, PQCStatefulKeyHealthCheck.doCall, statefulGetKeyState). The health check could reuse the producer's helpers or the StatefulKeyState model.

8. Hybrid signing not covered

hybridSign doesn't call checkStatefulKeyBeforeSign(), so exhaustion protection doesn't cover hybrid signatures with stateful keys.

None of these are critical, but items 2, 3, 5, and 6 would improve reliability if addressed in a follow-up.

Claude Code on behalf of Guillaume Nodet

[oscerd]

Thanks. Will add this to My backlog