Class AuditedContexts

java.lang.Object
zeroecho.core.audit.AuditedContexts
public final class AuditedContexts extends Object
Lightweight dynamic proxy that audits crypto contexts without changing their behavior.

This utility wraps an existing context instance and transparently intercepts selected operations in order to emit audit events. The wrapper delegates all calls to the underlying context and does not alter the functional results.

What is audited

  • attach(InputStream): classic byte counting over the processed body.
  • wrap(InputStream) on TagEngine-style contexts (SIGN/VERIFY, MAC, DIGEST): trailer-aware accounting that distinguishes body bytes from the authentication tag trailer; verification success or failure is inferred at EOF when possible.
  • KEM: encapsulate() and decapsulate(byte[]) are observed to report ciphertext and shared-secret lengths.
  • Agreement: peer material assignment and secret derivation are captured with non-reversible fingerprints and byte sizes.

Events and correlation

Creation, progress, failure, and closure events are emitted. Each wrapped instance is associated with a generated correlation id that is included with progress and failure notifications. When available, algorithm id, provider label, key fingerprint, and a best-effort summary of the context specification are recorded at creation time.

Behavioral guarantees

  • The proxy preserves the original semantics and exceptions of the wrapped context. Any failure reported to the listener mirrors the underlying failure.
  • Counting is performed by decorating the returned InputStreams; no buffering beyond normal FilterInputStream forwarding is introduced.
  • Idempotent wrapping: contexts already wrapped by this utility are returned unchanged. Unrelated JDK proxies are wrapped normally.

Usage example

AuditListener listener = ...;
KeyUsage role = KeyUsage.ENCRYPTION;
CryptoContext original = ...; // e.g., an EncryptionContext

CryptoContext audited = AuditedContexts.wrap(original, listener, role);
try (InputStream in = audited.attach(sourceStream)) {
    in.transferTo(sink);
}

  • Method Details

    • wrap

      public static CryptoContext wrap(CryptoContext ctx, AuditListener audit, KeyUsage role)
      Wraps a crypto context with an auditing proxy that emits lifecycle, progress, and error events while preserving the original behavior.

      If ctx is null, this method returns null. A context already backed by this utility's auditing handler is returned as-is to keep wrapping idempotent; unrelated JDK proxies are wrapped normally.

      The returned proxy implements the same set of interfaces as the original object. It observes:

      • attach(InputStream) for classic cumulative byte counts,
      • wrap(InputStream) for TagEngine-style contexts to account for body vs. authentication tag trailer and to report tag production or verify results at EOF when the tag length is known,
      • encapsulate() and decapsulate(byte[]) on KEM contexts to report ciphertext and secret lengths,
      • agreement operations (peer material assignment and secret derivation) with non-reversible key fingerprints and derived sizes.
      Creation metadata includes a generated correlation id, algorithm id, provider label, a public-key fingerprint or safe key type label, and a best-effort, non-secret spec summary when available. Private and secret key encodings are never requested.

      This call does not invoke any context operations other than the minimal, best-effort introspection used to produce creation metadata. Functional results and exceptions from the wrapped object are forwarded unchanged.

      Thread-safety: the proxy does not introduce additional synchronization. It is safe only to the extent the wrapped ctx is safe.

      Parameters:
      ctx - the context to wrap; may be null
      audit - the listener that will receive audit events; must not be null
      role - the usage role associated with the context (for example, ENCRYPTION, DECRYPTION, SIGNING); must not be null
      Returns:
      the auditing proxy for ctx, the original ctx if it is already wrapped by this utility, or null if ctx is null