Package io.github.pratiyush.totp.internal

Class SecureBytes

java.lang.Object
io.github.pratiyush.totp.internal.SecureBytes
All Implemented Interfaces:
AutoCloseable
public final class SecureBytes extends Object implements AutoCloseable
A wrapper for byte arrays containing sensitive data that ensures secure clearing.

This class implements AutoCloseable to enable automatic memory clearing when used in try-with-resources blocks. This is critical for secrets and keys that should not remain in memory longer than necessary.

Usage Example


 try (SecureBytes secret = SecureBytes.wrap(secretBytes)) {
     // Use secret.getBytes() for operations
     byte[] hash = computeHmac(secret.getBytes(), data);
 }
 // secret is automatically cleared here

Security Notes

  • Always use try-with-resources to ensure clearing
  • After close(), the bytes are zeroed
  • The toString() method never reveals the data
  • Clone operations are not supported to prevent copies

Warning: This class provides best-effort memory clearing. In Java, we cannot guarantee that the JVM hasn't made copies of the data. For maximum security, consider using dedicated security hardware (HSM).

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Clears the underlying byte array by overwriting with zeros.
    static boolean
    constantTimeEquals(byte[] a, byte[] b)
    Constant-time comparison of two byte arrays.
    static SecureBytes
    copyOf(byte[] data)
    Creates a copy of the given byte array.
    static SecureBytes
    copyOfRange(byte[] data, int offset, int length)
    Creates a SecureBytes from a portion of the given array.
    byte[]
    getBytes()
    Returns the underlying byte array.
    boolean
    isCleared()
    Returns whether this instance has been cleared.
    int
    length()
    Returns the length of the data.
    String
    toString()
    Returns a safe string representation that never reveals the data.
    static SecureBytes
    wrap(byte[] data)
    Wraps an existing byte array.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Method Details

    • wrap

      public static SecureBytes wrap(byte[] data)
      Wraps an existing byte array.

      Warning: The caller must not retain the original reference as it would bypass the secure clearing mechanism.

      Parameters:
      data - the byte array to wrap
      Returns:
      new SecureBytes instance
      Throws:
      NullPointerException - if data is null

    • copyOf

      public static SecureBytes copyOf(byte[] data)
      Creates a copy of the given byte array.

      Use this when the original array must remain unchanged.

      Parameters:
      data - the byte array to copy
      Returns:
      new SecureBytes instance with a copy of the data
      Throws:
      NullPointerException - if data is null

    • copyOfRange

      public static SecureBytes copyOfRange(byte[] data, int offset, int length)
      Creates a SecureBytes from a portion of the given array.
      Parameters:
      data - the source array
      offset - starting offset
      length - number of bytes to copy
      Returns:
      new SecureBytes instance
      Throws:
      NullPointerException - if data is null
      ArrayIndexOutOfBoundsException - if offset/length are invalid

    • getBytes

      public byte[] getBytes()
      Returns the underlying byte array.

      Warning: Do not store references to this array. It will be cleared when close() is called.

      Returns:
      the byte array
      Throws:
      IllegalStateException - if already cleared

    • length

      public int length()
      Returns the length of the data.
      Returns:
      length in bytes

    • isCleared

      public boolean isCleared()
      Returns whether this instance has been cleared.
      Returns:
      true if cleared

    • close

      public void close()
      Clears the underlying byte array by overwriting with zeros.

      This method is idempotent - calling it multiple times is safe.

      Specified by:
      close in interface AutoCloseable

    • toString

      public String toString()
      Returns a safe string representation that never reveals the data.
      Overrides:
      toString in class Object
      Returns:
      safe description string

    • constantTimeEquals

      public static boolean constantTimeEquals(byte[] a, byte[] b)
      Constant-time comparison of two byte arrays.

      This method always compares all bytes to prevent timing attacks. The comparison time is proportional to the minimum length of the arrays.

      Parameters:
      a - first array
      b - second array
      Returns:
      true if arrays are equal in length and content