Class ProtectedString

  • All Implemented Interfaces:
    Traceable, FFDCSelfIntrospectable

    public final class ProtectedString
    extends java.lang.Object
    implements Traceable, FFDCSelfIntrospectable
    The ProtectedString class wraps a String to protect sensitive strings from accidentally being printed in trace, FFDC, or via toString(). Instances of this class are immutable.

    This class does not provide a constructor that takes a String, and it does not have a method to convert the contents to a String. This is deliberate to encourage the caller to never store passwords in a String, which might be accidentally logged in trace or FFDC. In particular, callers must avoid storing a String even indirectly, such as in a Map. Additionally, callers must be careful to avoid accidentally logging in trace or FFDC the char[] used to construct the instance or that is returned from getChars().

    This implementation does not protect against the string being visible in clear text in JVM memory dumps. This class does not provide additional protection against the string being accessible via reflection, so callers should be careful to use private accessibility.

    • Constructor Summary

      Constructors 
      Constructor Description
      ProtectedString​(char[] password)
      Construct a ProtectedString (typically a password) from an array of characters.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object o)
      Determine if this password is the same as another object NOTE: As with all equals() methods, this implementation obeys the requirements of java.lang.Object.equals().
      char[] getChars()
      Return the protected password (Note: it is then the job of the caller to prevent its copies reaching trace, ffdc or converting it to a string
      int hashCode()
      return a hash code for this Password
      java.lang.String[] introspectSelf()
      Provide details on the state of this object to ffdc, hiding the actual contents of the password
      boolean isEmpty()
      Return true if password is either null or has no characters (use in situations where some kind of password is required)
      java.lang.String toString()
      Convert the password to a string, revealing only if it is null or non-null.
      java.lang.String toTraceString()
      Convert the password to a string for tracing purposes.
      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • NULL_PROTECTED_STRING

        public static final ProtectedString NULL_PROTECTED_STRING
        A password object that holds null
      • EMPTY_PROTECTED_STRING

        public static final ProtectedString EMPTY_PROTECTED_STRING
        A password object that holds the equivalent of the empty string
    • Constructor Detail

      • ProtectedString

        public ProtectedString​(char[] password)
        Construct a ProtectedString (typically a password) from an array of characters. The characters will not be revealed to trace or ffdc by this class
        Parameters:
        chars - The password to be protected
    • Method Detail

      • getChars

        public char[] getChars()
        Return the protected password (Note: it is then the job of the caller to prevent its copies reaching trace, ffdc or converting it to a string
        Returns:
        char[] The protected password
      • toString

        public java.lang.String toString()
        Convert the password to a string, revealing only if it is null or non-null. In particular note that it is NOT the password.
        Overrides:
        toString in class java.lang.Object
        Returns:
        String A string representation of the password that can be used in trace etc.
      • toTraceString

        public java.lang.String toTraceString()
        Convert the password to a string for tracing purposes. This provides a string that, for the same password, will be the same string, but will be different for different password (well, almost certainly different) and/or different class loaders (of Password). The password cannot be deduced from the trace string
        Specified by:
        toTraceString in interface Traceable
        Returns:
        String A string for the password for trace purposes
      • introspectSelf

        public java.lang.String[] introspectSelf()
        Provide details on the state of this object to ffdc, hiding the actual contents of the password
        Specified by:
        introspectSelf in interface FFDCSelfIntrospectable
        Returns:
        String[] An array of strings to be added to the ffdc log
      • equals

        public boolean equals​(java.lang.Object o)
        Determine if this password is the same as another object NOTE: As with all equals() methods, this implementation obeys the requirements of java.lang.Object.equals(). In particular that requires that if a.equals(b), then b.equals(a). That means that we only check against other ProtectedString objects. If we returned true for any String that was passed in, we would then need to modify java.lang.String's implementation so that it returned true when passed in the correct ProtectedString....
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - The other object
        Returns:
        boolean true if the other object is a Password and is the same of this one
      • hashCode

        public int hashCode()
        return a hash code for this Password
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        int The hash code of this password
      • isEmpty

        public boolean isEmpty()
        Return true if password is either null or has no characters (use in situations where some kind of password is required)
        Returns:
        true if password is null or has no characters.