JCE: add optional KEK caching to WolfSSLKeyStore for performance

[cconlon]

This PR adds optional KEK (Key Encryption Key) caching to WolfSSLKeyStore to avoid repeated PBKDF2 computations on subsequent getKey() calls. JUnit tests have been added for testing and regression.

Performance

On a Macbook Pro Intel Core i9 2.4 GHz machine, for PrivateKey getKey() operations:

Without KEK cache:

  First call vs subsequent:
    First call:        406.87 ms
    Avg subsequent:    387.83 ms

With KEK cache enabled:

  First call vs subsequent:
    First call:        390.43 ms
    Avg subsequent:    0.34 ms

Configuration

KEK cache is disabled by default. Can be enabled and TTL adjusted using the following Security properties. The cache TTL defaults to 5 minutes (300 sec), and is set in seconds:

Security.setProperty("wolfjce.keystore.kekCacheEnabled", "true");
Security.setProperty("wolfjce.keystore.kekCacheTtlSec", "300");

Cache Lifecycle

Cache is automatically cleared on:

• Entry deletion via deleteEntry()
• Entry overwrite via setKeyEntry()
• KeyStore reload via load()
• TTL expiration
• Explicit clear via clearCache() or object finalization

Benchmark

A benchmark app is included:

/* Run benchmark without KEK cache enabled, default to 100 iterations */
./examples/provider/WolfSSLKeyStoreGetKeyBenchmark.sh

/* Run benchmark with KEK cache enabled, also can set iterations if wanted */
./examples/provider/WolfSSLKeyStoreGetKeyBenchmark.sh -enableCache -iterations 100

[Copilot]

Pull request overview

This PR adds optional KEK (Key Encryption Key) caching to WolfSSLKeyStore to significantly improve performance for repeated getKey() calls by avoiding redundant PBKDF2 computations. The cache is disabled by default and can be enabled via Security properties with configurable TTL.

Key Changes:

• Implements in-memory cache for derived KEK keys with SHA-256-based cache keys and TTL expiration
• Adds cache lifecycle management with automatic clearing on entry deletion, overwrite, KeyStore reload, and TTL expiration
• Includes comprehensive JUnit tests covering cache behavior, invalidation scenarios, and performance characteristics
• Provides benchmark tool and updated documentation for the new feature

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/main/java/com/wolfssl/provider/jce/WolfSSLKeyStore.java	Core KEK cache implementation including cache data structures, key generation, retrieval/storage logic, and integration with key decryption methods
src/test/java/com/wolfssl/provider/jce/test/WolfSSLKeyStoreTest.java	Comprehensive test suite covering cache enabled/disabled behavior, performance improvements, invalidation scenarios, and edge cases
examples/provider/WolfSSLKeyStoreGetKeyBenchmark.java	Benchmark application for measuring getKey() performance with and without cache enabled
examples/provider/WolfSSLKeyStoreGetKeyBenchmark.sh	Shell script wrapper for running the benchmark
docs/design/WolfSSLKeyStore.md	Design documentation covering cache architecture, security properties, lifecycle, and security considerations
README_JCE.md	User-facing documentation describing the new Security properties and usage examples
jni/include/com_wolfssl_provider_jce_WolfSSLKeyStore.h	JNI header update to export KEK_CACHE_DEFAULT_TTL_MS constant

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.