Class StreamingAead

java.lang.Object
cloud.opencode.base.crypto.streaming.StreamingAead
All Implemented Interfaces:
AutoCloseable
public final class StreamingAead extends Object implements AutoCloseable
Streaming Authenticated Encryption with Associated Data (AEAD) for large data 用于大数据的流式认证加密（AEAD）

Encrypts data in fixed-size segments, each independently authenticated. Supports AES-256-GCM and ChaCha20-Poly1305. Each segment has its own nonce derived from a base nonce and segment counter, and includes segment metadata in AAD to prevent reordering and truncation attacks.

以固定大小的段加密数据，每个段独立认证。支持 AES-256-GCM 和 ChaCha20-Poly1305。 每个段有自己的 nonce（从基础 nonce 和段计数器派生），并在 AAD 中包含段元数据以防止 重排和截断攻击。

Wire Format | 数据格式:

[4-byte header: segment plaintext size (big-endian)]
[base nonce (12 bytes)]
[segment 0: nonce(12) + ciphertext + tag(16)]
[segment 1: nonce(12) + ciphertext + tag(16)]
...
[final segment: nonce(12) + ciphertext(shorter or equal) + tag(16)]

Features | 主要功能:

  • AES-256-GCM streaming encryption - AES-256-GCM 流式加密
  • ChaCha20-Poly1305 streaming encryption - ChaCha20-Poly1305 流式加密
  • Per-segment authentication with anti-reorder AAD - 每段认证，AAD 防重排
  • Anti-truncation via final-segment marker - 通过最终段标记防截断
  • File encryption/decryption convenience methods - 文件加解密便捷方法

Usage Examples | 使用示例:

// AES-256-GCM streaming encryption
try (StreamingAead aead = StreamingAead.aesGcm(key256)
        .setSegmentSize(1024 * 1024)
        .setAad(associatedData)) {
    aead.encryptFile(Path.of("input.bin"), Path.of("output.enc"));
    aead.decryptFile(Path.of("output.enc"), Path.of("restored.bin"));
}

// ChaCha20-Poly1305
try (StreamingAead chacha = StreamingAead.chaCha20(key256)) {
    chacha.encrypt(inputStream, outputStream);
}

Security | 安全性:

  • Thread-safe: No (not designed for concurrent use) - 线程安全: 否（非并发设计）
  • Null-safe: No (null key throws exception) - 空值安全: 否（空密钥抛出异常）
Since:
JDK 25, opencode-base-crypto V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • aesGcm

      public static StreamingAead aesGcm(byte[] key)
      Create a StreamingAead instance using AES-GCM. 创建使用 AES-GCM 的 StreamingAead 实例。
      Parameters:
      key - AES key (16, 24, or 32 bytes) | AES 密钥（16、24 或 32 字节）
      Returns:
      new StreamingAead instance | 新的 StreamingAead 实例
      Throws:
      OpenKeyException - if the key is null or has invalid length | 当密钥为空或长度无效时抛出

    • chaCha20

      public static StreamingAead chaCha20(byte[] key)
      Create a StreamingAead instance using ChaCha20-Poly1305. 创建使用 ChaCha20-Poly1305 的 StreamingAead 实例。
      Parameters:
      key - 256-bit (32-byte) ChaCha20 key | 256 位（32 字节）ChaCha20 密钥
      Returns:
      new StreamingAead instance | 新的 StreamingAead 实例
      Throws:
      OpenKeyException - if the key is null or not 32 bytes | 当密钥为空或长度不是 32 字节时抛出

    • setSegmentSize

      public StreamingAead setSegmentSize(int bytes)
      Set the plaintext segment size in bytes. 设置明文段大小（字节）。

      Each segment of this size will be independently encrypted and authenticated. Default is 1 MB (1048576 bytes). Minimum is 256 bytes, maximum is 64 MB.

      此大小的每个段将被独立加密和认证。默认为 1 MB（1048576 字节）。 最小为 256 字节，最大为 64 MB。

      Parameters:
      bytes - segment size in bytes | 段大小（字节）
      Returns:
      this instance for chaining | 当前实例以支持链式调用
      Throws:
      IllegalArgumentException - if bytes is out of range | 当字节数超出范围时抛出

    • setAad

      public StreamingAead setAad(byte[] aad)
      Set additional authenticated data (AAD) for all segments. 为所有段设置附加认证数据（AAD）。

      The AAD is included in authentication but not encrypted. Per-segment metadata (base nonce, counter, final flag) is appended internally.

      AAD 包含在认证中但不加密。每段的元数据（基础 nonce、计数器、最终段标记）在内部追加。

      Parameters:
      aad - additional authenticated data (may be null) | 附加认证数据（可以为 null）
      Returns:
      this instance for chaining | 当前实例以支持链式调用

    • close

      public void close()
      Securely erase key material and AAD from memory. 安全擦除内存中的密钥材料和 AAD。
      Specified by:
      close in interface AutoCloseable

    • encrypt

      public void encrypt(InputStream in, OutputStream out)
      Encrypt data from an input stream to an output stream. 从输入流加密数据到输出流。
      Parameters:
      in - source plaintext stream | 源明文流
      out - destination ciphertext stream | 目标密文流
      Throws:
      OpenCryptoException - if encryption fails | 当加密失败时抛出

    • decrypt

      public void decrypt(InputStream in, OutputStream out)
      Decrypt data from an input stream to an output stream. 从输入流解密数据到输出流。
      Parameters:
      in - source ciphertext stream | 源密文流
      out - destination plaintext stream | 目标明文流
      Throws:
      OpenCryptoException - if decryption or authentication fails | 当解密或认证失败时抛出

    • encryptFile

      public void encryptFile(Path source, Path target)
      Encrypt a file. 加密文件。
      Parameters:
      source - source file path | 源文件路径
      target - target file path | 目标文件路径
      Throws:
      OpenCryptoException - if encryption fails | 当加密失败时抛出

    • decryptFile

      public void decryptFile(Path source, Path target)
      Decrypt a file. Writes to a temp file and atomically renames on success to avoid leaving partial unauthenticated plaintext on disk. 解密文件。写入临时文件并在成功时原子性重命名，避免在磁盘上留下部分未认证的明文。
      Parameters:
      source - source (encrypted) file path | 源（加密）文件路径
      target - target (decrypted) file path | 目标（解密）文件路径
      Throws:
      OpenCryptoException - if decryption fails | 当解密失败时抛出