Class ZeroEchoSession

java.lang.Object
zeroecho.sdk.ZeroEchoSession
public final class ZeroEchoSession extends Object
Immutable, explicitly scoped runtime configuration for ZeroEcho operations.

Each session owns one policy, audit listener, and audit mode. Configuration methods return a new session and never mutate the receiver, so independently created sessions cannot affect one another. The default configuration is a permissive policy, a no-op listener, and AuditMode.OFF.

Sessions share the immutable provider registry owned by CryptoAlgorithms; provider discovery is therefore performed once for the registry lifecycle. Session instances are safe for concurrent use. Configured policy and listener implementations must themselves support any concurrency with which the session is used.

Audit callbacks may receive key and specification objects. Listeners are trusted application components and must not log or retain keys, plaintext, seeds, shared secrets, or sensitive specifications.

Since:
1.0

  • Constructor Details

    • ZeroEchoSession

      public ZeroEchoSession()
      Creates a session with a permissive policy, no-op audit listener, and AuditMode.OFF.

  • Method Details

    • withPolicy

      public ZeroEchoSession withPolicy(CryptoPolicy<ContextSpec, Key> newPolicy)
      Returns a session with the supplied policy and this session's audit configuration.
      Parameters:
      newPolicy - policy applied before context creation; must not be null
      Returns:
      a new independently configured session
      Throws:
      NullPointerException - if newPolicy is null

    • withAuditListener

      public ZeroEchoSession withAuditListener(AuditListener newAuditListener)
      Returns a session with the supplied audit listener and this session's policy and audit mode.
      Parameters:
      newAuditListener - listener receiving audit callbacks; must not be null
      Returns:
      a new independently configured session
      Throws:
      NullPointerException - if newAuditListener is null

    • withAuditMode

      public ZeroEchoSession withAuditMode(AuditMode newAuditMode)
      Returns a session with the supplied audit mode and this session's policy and listener.
      Parameters:
      newAuditMode - audit strategy; must not be null
      Returns:
      a new independently configured session
      Throws:
      NullPointerException - if newAuditMode is null

    • withPbkdf2Limits

      public ZeroEchoSession withPbkdf2Limits(Pbkdf2Limits limits)
      Returns a session with explicit PBKDF2 work-factor limits.
      Parameters:
      limits - deployment-selected limits
      Returns:
      independently configured session
      Throws:
      NullPointerException - if limits is null

    • pbkdf2Limits

      public Pbkdf2Limits pbkdf2Limits()
      Returns configured PBKDF2 limits.
      Returns:
      explicit deployment limits
      Throws:
      IllegalStateException - if limits were not configured

    • policy

      public CryptoPolicy<ContextSpec, Key> policy()
      Returns the policy owned by this session.
      Returns:
      the non-null policy strategy

    • auditListener

      public AuditListener auditListener()
      Returns the audit listener owned by this session.

      The returned listener is the configured strategy, not mutable session state. It is exposed to support manual audit mode.

      Returns:
      the non-null audit listener

    • auditMode

      public AuditMode auditMode()
      Returns the audit mode owned by this session.
      Returns:
      the non-null audit mode

    • available

      public Set<String> available()
      Returns the available algorithm identifiers in deterministic registry order.
      Returns:
      an unmodifiable set of canonical algorithm identifiers

    • require

      public CryptoAlgorithm require(String id)
      Resolves an algorithm from the authoritative registry.
      Parameters:
      id - canonical algorithm identifier
      Returns:
      the registered algorithm
      Throws:
      IllegalArgumentException - if no algorithm is registered under id

    • keyBuilders

      public KeyBuilders keyBuilders()
      Returns exact session-bound key operations.
      Returns:
      immutable grouped key-operation entry point

    • createContext

      public <C extends CryptoContext, K extends Key, S extends ContextSpec> C createContext(String id, KeyUsage role, K key, S spec)
      Creates a context after applying this session's policy and audit configuration.
      Type Parameters:
      C - context type
      K - key type
      S - context specification type
      Parameters:
      id - canonical algorithm identifier
      role - intended key usage
      key - key compatible with the selected algorithm and role
      spec - optional context specification, or null for the algorithm default
      Returns:
      a ready context, possibly audit-wrapped in AuditMode.WRAP
      Throws:
      IllegalArgumentException - if the algorithm identifier is unknown or policy validation rejects the operation
      UnsupportedRoleException - if the algorithm does not support role
      UnsupportedSpecException - if the key or specification is incompatible

    • createContext

      public <C extends CryptoContext, K extends Key> C createContext(String id, KeyUsage role, K key)
      Creates a context using the selected algorithm's default specification.
      Type Parameters:
      C - context type
      K - key type
      Parameters:
      id - canonical algorithm identifier
      role - intended key usage
      key - key compatible with the selected algorithm and role
      Returns:
      a ready context, possibly audit-wrapped in AuditMode.WRAP
      Throws:
      IllegalArgumentException - if the algorithm identifier is unknown or policy validation rejects the operation
      UnsupportedRoleException - if the algorithm does not support role

    • destroyKey

      public boolean destroyKey(String algorithmId, String provider, Key key) throws DestroyFailedException
      Destroys a key and verifies that it entered the destroyed state.
      Parameters:
      algorithmId - algorithm identifier used as audit metadata
      provider - provider name used as audit metadata
      key - key to destroy; must not be null
      Returns:
      true only when this call transitions the key to destroyed; false for a non-destroyable or already destroyed key
      Throws:
      NullPointerException - if key is null
      DestroyFailedException - if destruction fails or the key does not report itself destroyed afterward
      RuntimeException - if the key's lifecycle implementation throws one