Class SecureString

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, java.lang.CharSequence

    public final class SecureString
    extends java.lang.Object
    implements java.lang.CharSequence, java.io.Closeable
    A String implementations which allows clearing the underlying char array.
    • Constructor Summary

      Constructors 
      Constructor Description
      SecureString​(char[] chars)
      Constructs a new SecureString which controls the passed in char array.
      SecureString​(java.lang.String s)
      Deprecated.
      Only use for compatibility between deprecated string settings and new secure strings
    • Method Summary

      Modifier and Type Method Description
      char charAt​(int index)  
      SecureString clone()
      Returns a new copy of this object that is backed by its own char array.
      void close()
      Closes the string by clearing the underlying char array.
      boolean equals​(java.lang.Object o)
      Constant time equality to avoid potential timing attacks.
      char[] getChars()
      Returns the underlying char[].
      int hashCode()  
      int length()  
      SecureString subSequence​(int start, int end)  
      java.lang.String toString()
      Convert to a String.
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.lang.CharSequence

        chars, codePoints
    • Constructor Detail

      • SecureString

        public SecureString​(char[] chars)
        Constructs a new SecureString which controls the passed in char array. Note: When this instance is closed, the array will be zeroed out.
      • SecureString

        @Deprecated
        public SecureString​(java.lang.String s)
        Deprecated.
        Only use for compatibility between deprecated string settings and new secure strings
        Constructs a new SecureString from an existing String. NOTE: This is not actually secure, since the provided String cannot be deallocated, but this constructor allows for easy compatibility between new and old apis.
    • Method Detail

      • equals

        public boolean equals​(java.lang.Object o)
        Constant time equality to avoid potential timing attacks.
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • length

        public int length()
        Specified by:
        length in interface java.lang.CharSequence
      • charAt

        public char charAt​(int index)
        Specified by:
        charAt in interface java.lang.CharSequence
      • subSequence

        public SecureString subSequence​(int start,
                                        int end)
        Specified by:
        subSequence in interface java.lang.CharSequence
      • toString

        public java.lang.String toString()
        Convert to a String. This should only be used with APIs that do not take CharSequence.
        Specified by:
        toString in interface java.lang.CharSequence
        Overrides:
        toString in class java.lang.Object
      • close

        public void close()
        Closes the string by clearing the underlying char array.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
      • clone

        public SecureString clone()
        Returns a new copy of this object that is backed by its own char array. Closing the new instance has no effect on the instance it was created from. This is useful for APIs which accept a char array and you want to be safe about the API potentially modifying the char array. For example:
             try (SecureString copy = secureString.clone()) {
                 // pass thee char[] to a external API
                 PasswordAuthentication auth = new PasswordAuthentication(username, copy.getChars());
                 ...
             }
         
        Overrides:
        clone in class java.lang.Object
      • getChars

        public char[] getChars()
        Returns the underlying char[]. This is a dangerous operation as the array may be modified while it is being used by other threads or a consumer may modify the values in the array. For safety, it is preferable to use clone() and pass its chars to the consumer when the chars are needed multiple times.