Package com.ongres.stringprep

Class SecureStringBuilder

java.lang.Object
com.ongres.stringprep.SecureStringBuilder
All Implemented Interfaces:
AutoCloseable
final class SecureStringBuilder extends Object implements AutoCloseable
A memory-safe string builder alternative designed specifically for cryptographic operations.

Standard String and StringBuilder classes leave sensitive data (like passwords or encryption keys) in memory until garbage collection occurs. This class mitigates that risk by ensuring that internal character arrays are explicitly zeroed out when the buffer is resized, and when the resource is closed.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private char[]
    buffer
     
    private int
    length
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    SecureStringBuilder(int initialCapacity)
    Constructs a new SecureStringBuilder with the specified initial capacity.

  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) void
    appendCodePoint(int codePoint)
    Appends a single Unicode code point to this buffer.
    void
    close()
    Securely wipes the internal buffer by overwriting all contents with null characters ('\0') and resets the length to zero.
    private void
    ensureCapacity(int minCapacity)
    Ensures that the internal buffer has enough capacity to hold the specified minimum number of characters.
    (package private) char[]
    toCharArray()
    Extracts a copy of the current buffer sized exactly to the appended content.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • buffer

      private char[] buffer

    • length

      private int length

  • Constructor Details

    • SecureStringBuilder

      SecureStringBuilder(int initialCapacity)
      Constructs a new SecureStringBuilder with the specified initial capacity.
      Parameters:
      initialCapacity - the initial capacity of the secure buffer.
      Throws:
      IllegalArgumentException - if initialCapacity is negative.

  • Method Details

    • ensureCapacity

      private void ensureCapacity(int minCapacity)
      Ensures that the internal buffer has enough capacity to hold the specified minimum number of characters. If a resize is required, the old array is securely wiped before being discarded.
      Parameters:
      minCapacity - the desired minimum capacity.
      Throws:
      OutOfMemoryError - if the required size exceeds JVM array limits.

    • appendCodePoint

      void appendCodePoint(int codePoint)
      Appends a single Unicode code point to this buffer.

      This method correctly handles supplementary characters by converting them into their corresponding UTF-16 surrogate pairs if necessary.

      Parameters:
      codePoint - the Unicode code point to append.
      Throws:
      IllegalArgumentException - if the specified code point is not a valid Unicode code point.
      IllegalStateException - if the builder has been closed.

    • toCharArray

      char[] toCharArray()
      Extracts a copy of the current buffer sized exactly to the appended content.

      Security Warning: This method allocates a new array containing the sensitive data. The internal buffer remains intact until close() is called. The caller assumes full responsibility for securely wiping the returned array (e.g., using Arrays.fill(char[], char)) as soon as it is no longer needed.

      Returns:
      a new, exact-sized character array containing the buffer's contents.
      Throws:
      IllegalStateException - if the builder has been closed.

    • close

      public void close()
      Securely wipes the internal buffer by overwriting all contents with null characters ('\0') and resets the length to zero.

      This method should be called inside a finally block or implicitly via a try-with-resources statement to guarantee cleanup.

      Specified by:
      close in interface AutoCloseable