Class SecureBytes

java.lang.Object
cloud.opencode.base.crypto.util.SecureBytes
All Implemented Interfaces:
AutoCloseable
public final class SecureBytes extends Object implements AutoCloseable
Secure byte array wrapper with automatic memory erasure on close 安全字节数组包装器，关闭时自动擦除内存

Wraps sensitive byte data (keys, plaintext, etc.) and ensures the underlying memory is zeroed when the wrapper is closed. Implements AutoCloseable for use with try-with-resources.

包装敏感字节数据（密钥、明文等），确保在关闭包装器时底层内存被清零。 实现 AutoCloseable 以支持 try-with-resources 用法。

Features | 主要功能:

  • Defensive copy via of() or zero-copy via wrap() - 通过 of() 防御性拷贝或通过 wrap() 零拷贝
  • Automatic memory erasure on close - 关闭时自动擦除内存
  • Constant-time equality comparison - 常量时间相等性比较
  • Safe toString that never leaks content - 安全的 toString 不泄露内容

Usage Examples | 使用示例:

try (SecureBytes key = SecureBytes.of(rawKey)) {
    byte[] copy = key.getBytes();
    // use copy...
} // rawKey copy is zeroed here

Security | 安全性:

  • Thread-safe: No - 线程安全: 否
  • Null-safe: No (null input throws NullPointerException) - 空值安全: 否（空输入抛出 NullPointerException）
Since:
JDK 25, opencode-base-crypto V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Close this SecureBytes by zeroing the internal data.
    boolean
    equals(Object o)
    Constant-time equality comparison using ConstantTimeUtil.
    byte[]
    getBytes()
    Return a defensive copy of the internal byte data.
    byte[]
    getBytesUnsafe()
    Return a direct reference to the internal byte data (hot-path optimization).
    int
    hashCode()
    Returns a constant hash code to prevent leaking key content via hash-based data structures.
    boolean
    isClosed()
    Check whether this SecureBytes has been closed.
    int
    length()
    Return the length of the byte data.
    static SecureBytes
    of(byte[] data)
    Create a SecureBytes instance with a defensive copy of the input data.
    String
    toString()
    Return a safe string representation that does not leak content.
    static SecureBytes
    wrap(byte[] data)
    Create a SecureBytes instance that takes ownership of the given array (zero-copy).

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • of

      public static SecureBytes of(byte[] data)
      Create a SecureBytes instance with a defensive copy of the input data. 创建 SecureBytes 实例，对输入数据进行防御性拷贝。

      The caller retains ownership of the original array.

      调用者保留对原始数组的所有权。

      Parameters:
      data - the byte array to copy | 要拷贝的字节数组
      Returns:
      a new SecureBytes wrapping a copy of the data | 包装数据副本的新 SecureBytes
      Throws:
      NullPointerException - if data is null | 当 data 为 null 时抛出

    • wrap

      public static SecureBytes wrap(byte[] data)
      Create a SecureBytes instance that takes ownership of the given array (zero-copy). 创建 SecureBytes 实例，接管给定数组的所有权（零拷贝）。

      The caller must not modify or reference the array after calling this method.

      调用者在调用此方法后不得修改或引用该数组。

      Parameters:
      data - the byte array to take ownership of | 要接管所有权的字节数组
      Returns:
      a new SecureBytes wrapping the data directly | 直接包装数据的新 SecureBytes
      Throws:
      NullPointerException - if data is null | 当 data 为 null 时抛出

    • getBytes

      public byte[] getBytes()
      Return a defensive copy of the internal byte data. 返回内部字节数据的防御性拷贝。
      Returns:
      a copy of the data | 数据的副本
      Throws:
      IllegalStateException - if this SecureBytes has been closed | 当此 SecureBytes 已关闭时抛出

    • getBytesUnsafe

      public byte[] getBytesUnsafe()
      Return a direct reference to the internal byte data (hot-path optimization). 返回内部字节数据的直接引用（热路径优化）。

      Warning: The caller must not modify the returned array or retain a reference beyond the lifetime of this SecureBytes.

      警告：调用者不得修改返回的数组，也不得在此 SecureBytes 生命周期之外保留引用。

      Returns:
      direct reference to internal data | 内部数据的直接引用
      Throws:
      IllegalStateException - if this SecureBytes has been closed | 当此 SecureBytes 已关闭时抛出

    • length

      public int length()
      Return the length of the byte data. 返回字节数据的长度。
      Returns:
      length in bytes | 字节长度
      Throws:
      IllegalStateException - if this SecureBytes has been closed | 当此 SecureBytes 已关闭时抛出

    • isClosed

      public boolean isClosed()
      Check whether this SecureBytes has been closed. 检查此 SecureBytes 是否已关闭。
      Returns:
      true if closed, false otherwise | 如果已关闭返回 true，否则返回 false

    • close

      public void close()
      Close this SecureBytes by zeroing the internal data. 通过清零内部数据来关闭此 SecureBytes。

      After calling this method, all accessor methods will throw IllegalStateException. Calling close multiple times is safe.

      调用此方法后，所有访问器方法将抛出 IllegalStateException。 多次调用 close 是安全的。

      Specified by:
      close in interface AutoCloseable

    • equals

      public boolean equals(Object o)
      Constant-time equality comparison using ConstantTimeUtil. 使用 ConstantTimeUtil 进行常量时间相等性比较。
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare | 要比较的对象
      Returns:
      true if equal, false otherwise | 如果相等返回 true，否则返回 false

    • hashCode

      public int hashCode()
      Returns a constant hash code to prevent leaking key content via hash-based data structures. 返回常量哈希码，防止通过基于哈希的数据结构泄露密钥内容。

      SecureBytes should not be used as HashMap keys. A constant hash code eliminates the timing oracle that a data-dependent hash would create.

      Overrides:
      hashCode in class Object
      Returns:
      constant hash code | 常量哈希码

    • toString

      public String toString()
      Return a safe string representation that does not leak content. 返回不泄露内容的安全字符串表示。
      Overrides:
      toString in class Object
      Returns:
      "SecureBytes[length=N]" or "SecureBytes[closed]" | "SecureBytes[length=N]" 或 "SecureBytes[closed]"