Package zeroecho.core.audit

package zeroecho.core.audit
Auditing utilities for cryptographic contexts, including event contracts and a JUL-backed listener.

This package provides a lightweight dynamic-proxy wrapper that observes selected operations of crypto contexts and emits structured audit events without changing behavior. It also defines the listener API and a production-ready java.util.logging-based implementation.

Scope and responsibilities

  • Wrap existing contexts and transparently intercept lifecycle, progress, verification, and failure signals while preserving functional results and exceptions.
  • Offer a stable, structured callback surface suitable for logs, metrics, and policy hooks.
  • Summarize non-secret specification attributes for diagnostics (mode, tag length, IV length, and similar).

Key elements

  • AuditedContexts - creates a dynamic proxy around a context and emits creation metadata, streaming progress, verification outcomes, KEM/Agreement signals, closure totals, and failure notifications. The wrapper delegates all calls to the target and does not alter return values or exceptions.
  • AuditListener - event sink interface; default methods are no-ops so implementors override only what they need. Callbacks cover creation, progress, headers, random material, KDF usage, verify results, failures, and closure.
  • JulAuditListenerStd - concrete listener that emits parameterized java.util.logging records in a stable key=value format; a fluent builder configures logger, levels, and stack-trace inclusion.
  • SpecIntrospector - internal helper that summarizes non-secret ContextSpec attributes for diagnostics.

Typical usage

// Configure a JUL-backed listener.
AuditListener audit = JulAuditListenerStd.builder()
    .progressLevel(java.util.logging.Level.FINE)
    .includeStackTraces(false)
    .build();

// Create a context and wrap it for auditing.
zeroecho.core.context.CryptoContext raw = ...; // created by an algorithm descriptor
zeroecho.core.KeyUsage role = zeroecho.core.KeyUsage.ENCRYPT;
zeroecho.core.context.CryptoContext ctx = AuditedContexts.wrap(raw, audit, role);

// Use as usual; the proxy emits structured events.
try (java.io.InputStream in =
        ((zeroecho.core.context.EncryptionContext) ctx).attach(upstream)) {
    in.transferTo(out);
}

Privacy and safety

  • No secret material is logged; keys are summarized by short, non-reversible fingerprints.
  • Counting uses passthrough streams; the wrapper introduces no buffering beyond normal streaming.
  • Thread-safety follows the wrapped context; no additional synchronization is added.
Since:
1.0
  • Class
    Description
    AuditedContexts
    Lightweight dynamic proxy that audits crypto contexts without changing their behavior.
    AuditListener
    Listener for structured audit events emitted by audited crypto contexts.
    AuditListeners
    Utilities for enforcing the best-effort audit-listener contract.
    AuditMode
    Defines the session-owned automatic auditing strategy.
    JulAuditListenerStd
    AuditListener implementation that emits structured Java Util Logging records.
    JulAuditListenerStd.Builder
    Fluent factory for JulAuditListenerStd.