[Design Discussion] Introduce a server-level keystore package and migrate existing key operations behind interfaces

[JeethJJ]

Related Feature Issue

#2047

Problem Summary

The server currently lacks a unified abstraction for cryptographic operations, with different components directly using file-based PKI logic or isolated helpers. This results in tight coupling to a single backend, inconsistent crypto behavior, and duplicated implementations across features. As a result, integrating alternative key management solutions or evolving key handling becomes complex and error-prone.

Derived from : #2253

High-Level Approach

• Introduce a dedicated keystore package as the central abstraction for all cryptographic operations

• Define separate interfaces for:

  • configuration-time crypto (ConfigCryptoProvider)
  • runtime crypto (RuntimeCryptoProvider)

• Implement an initial provider that wraps existing file-based PKI and encryption logic (no behavior change)

• Gradually migrate existing components:

  • JWT signing
  • JWE encryption/decryption
  • JWKS key exposure
  • configuration encryption
  • TLS key access

• Enable pluggable provider architecture to support future backends (e.g., remote KMS, HSM) without modifying feature code

Architecture Overview

• Define and expose ConfigCryptoProvider and RuntimeCryptoProvider as core interfaces
• Add a provider implementation layer behind these interfaces:
  • encapsulates key loading, algorithm handling, and crypto execution
  • hides backend-specific details from the rest of the system
• Integrate the keystore into existing services via dependency injection:
  • services receive the appropriate provider interface instead of accessing crypto utilities directly
• Adapt existing crypto paths into the keystore:
  • PKI logic mapped to runtime provider
  • config encryption mapped to config provider
  • TLS key/cert access routed through runtime provider
• Centralise provider initialisation during server bootstrap and make it available to dependent components
• Establish the keystore as the boundary between feature logic and key management, isolating all crypto interactions behind a consistent interface

Security Considerations

• Centralize cryptographic operations behind the keystore boundary so key usage becomes more consistent and easier to review
• Keep private key handling provider-owned, so feature code does not directly access or manage key material
• Preserve existing cryptographic behavior in the initial implementation to avoid introducing security regressions during migration
• Clearly separate configuration-time and runtime crypto paths to reduce misuse and avoid mixing different security assumptions
• Design the abstraction : so future providers can enforce stronger security controls such as external key custody, non-exportable keys, and backend policy enforcement
• Support better auditability by making crypto operations flow through a single boundary rather than multiple feature-specific paths

Impacted Areas

• Crypto/key-management core
• Existing PKI layer
• JWT layer
• JWKS layer
• JWE layer
• Server initialization + config: provider selection

Alternatives Considered

Multiple different designs for the interface. Considering the pluggability and clear separation of config time and run time crypto operations, we will proceed with the following interface.

type ConfigCryptoProvider interface {
    Encrypt(ctx context.Context, content []byte) error
    Decrypt(ctx context.Context, content []byte) ([]byte, error)
}

type RuntimeCryptoProvider interface {
    Encrypt(ctx context.Context, keyRef KeyRef, algorithm Algorithm, content []byte) ([]byte, error)
    Decrypt(ctx context.Context, keyRef KeyRef, algorithm Algorithm, content []byte) ([]byte, error)
    Sign(ctx context.Context, keyRef KeyRef, algorithm Algorithm, content []byte) ([]byte, error)
    GetPublicKeys(ctx context.Context, filter PublicKeyFilter) ([]PublicKeyInfo, error)
    GetTLSMaterial(ctx context.Context, keyRef KeyRef) (*TLSMaterial, error)
}

Questions for Community Input

1. Should Decrypt() accept a kid so the backend can find the right key for old data?KID support for decryption?
2. Do we need a get all keys method?
3. Do we need to consider key versioning?
4. Do we need to consider the store in encrypt and store operation during ConfigCryptoProvider as an external operation?

[JeethJJ]

Interface plan

---

type ConfigCryptoProvider interface {
    Encrypt(ctx context.Context, content []byte) ([]byte, error)
    Decrypt(ctx context.Context, content []byte) ([]byte, error)
}

type RuntimeCryptoProvider interface {
    Encrypt(ctx context.Context, keyRef KeyRef, algorithm Algorithm, content []byte) ([]byte, error)
    Decrypt(ctx context.Context, keyRef KeyRef, algorithm Algorithm, content []byte) ([]byte, error)
    Sign(ctx context.Context, keyRef KeyRef, algorithm Algorithm, content []byte) ([]byte, error)
    GetPublicKeys(ctx context.Context, filter PublicKeyFilter) ([]PublicKeyInfo, error)
    GetTLSMaterial(ctx context.Context, keyRef KeyRef) (*TLSMaterial, error)
}

---

Method Descriptions

ConfigCryptoProvider

• Encrypt(ctx, content)
  Encrypts configuration-time data using provider-managed keys and algorithms.
  The caller does not supply the key or algorithm. Returns the encrypted representation for storage or later use.

• Decrypt(ctx, content)
  Decrypts previously encrypted configuration data.
  The input is expected to be the stored encrypted representation, and the plaintext is returned.

---

RuntimeCryptoProvider

• Encrypt(ctx, keyRef, algorithm, content)
  Encrypts plaintext using the specified key and algorithm. Returns the encrypted data.

• Decrypt(ctx, keyRef, algorithm, content)
  Decrypts ciphertext using the specified key and algorithm. Returns the plaintext.

• Sign(ctx, keyRef, algorithm, content)
  Generates a digital signature for the given content using the specified key and algorithm.

• GetPublicKeys(ctx, filter)
  Returns public key material for discovery use cases such as JWKS generation. Supports filtering of keys.

• GetTLSMaterial(ctx, keyRef)
  Returns TLS-specific material including the certificate chain and a signer backed by the keystore.
  The certificate chain is used for server identity, and the signer is used by the TLS stack during the handshake to prove ownership of the private key.