com.ibm.websphere.ras
Class ProtectedString

java.lang.Object
  extended by com.ibm.websphere.ras.ProtectedString
All Implemented Interfaces:
com.ibm.ejs.ras.Traceable, FFDCSelfIntrospectable

public final class ProtectedString
extends java.lang.Object
implements com.ibm.ejs.ras.Traceable, FFDCSelfIntrospectable

Password wraps a string to protect it from trace and ffdc. It is immutable NOTE: You may notice that this class does not provide a constructor that takes a String (and that you can only get the characters in the form of an array). This is indeed a nuisance, but is deliberate to encourage you to avoid having the password ever stored in a java String. Unfortunately although String is a nice way to handle a sequence of characters (although there's CharSequence as well...), it has a big drawbacks from a security perspective if you're being really paranoid - Strings will be "intern"ed by the JVM at the slightest excuse. If you were an attacker (running inside the JVM with Java 2 security fully enabled) you could use the intern string pool to guess if a potential password is actually in use (Call potentialPassword.intern() - if you get a different object back it was in the intern string pool). NOTE: This implementation does not protect against the password being visible in clear text and as a sequence of unicode byte-pairs in any JVM memory dumps. It DOES prevent the password being visible in trace, FFDC or via toString(). With Java 2 securiry enabled, the password will only be visible via introspection to authorised classes (assuming that none of those authorised classes set the visibility of instance fields to public....) NOTE: Although this class may claim to be serializable, this is merely for the convenience of admin TaskForm classes. Any attempt to actually serialize instances of this class will result in exceptions. If the user of this class manipulates the password using the char array methods AND the app server is running with correctly configured Java 2 security, the password should be fairly safely protected....


Field Summary
static ProtectedString EMPTY_PROTECTED_STRING
          A password object that holds the equivalent of the empty string
static ProtectedString NULL_PROTECTED_STRING
          A password object that holds null
 
Constructor Summary
ProtectedString(char[] password)
          Construct a ProtectedString (typically a password) from an array of characters.
 
Method Summary
 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 com.ibm.ejs.ras.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.