Interface EncryptionContext

All Superinterfaces:
AutoCloseable, Closeable, CryptoContext
All Known Implementing Classes:
AesCipherContext, ChaChaCipherContext, ElgamalCipherContext, RsaCipherContext
public non-sealed interface EncryptionContext extends CryptoContext
Context for performing encryption or decryption in streaming pipelines.

An EncryptionContext transforms data on-the-fly as it is read from an upstream source. It provides a passthrough InputStream that transparently applies encryption or decryption according to the configured algorithm, key, and parameters.

Lifecycle

  • Create a context via ZeroEchoSession#createContext(...) for the KeyUsage.ENCRYPT or KeyUsage.DECRYPT role.
  • Call attach(InputStream) to obtain a wrapped stream.
  • Read from the returned stream; data is encrypted or decrypted on demand until end-of-file.
  • Consume the returned stream through end-of-file to complete the transform and observe finalization or authentication errors, then close that stream.
  • Close the context separately. Context closure is not a substitute for completing or closing the returned stream.

Security considerations

  • When using AEAD modes (e.g., AES-GCM), callers must preserve the associated authentication tag and any nonces or IVs required for decryption.
  • Reading the stream to completion is usually required for integrity checks to succeed; truncation can result in verification failures.
  • Contexts are not guaranteed to be thread-safe; use one context per pipeline.
Since:
1.0

  • Method Details

    • attach

      InputStream attach(InputStream upstream) throws IOException
      Attaches this context to an upstream input stream.

      The returned stream applies encryption or decryption as bytes are read. Implementations may buffer internally. Callers must read the stream through end-of-file and handle any final authentication error before treating a decrypted message as valid. Closing a partially consumed stream is cleanup, not proof that the complete message was authenticated. Close the returned stream separately from the context; upstream ownership follows the concrete implementation's stream contract.

      Parameters:
      upstream - the source stream supplying plaintext (for encryption) or ciphertext (for decryption)
      Returns:
      a new input stream that transforms data according to the context
      Throws:
      IOException - if the stream cannot be wrapped or the underlying cipher initialization fails