org.mozilla.jss.util

Class Password

Implemented Interfaces:
Cloneable, PasswordCallback, java.io.Serializable

public class Password
extends java.lang.Object
implements PasswordCallback, Cloneable, java.io.Serializable

Stores a password. clear should be called when the password is no longer needed so that the sensitive information is not left in memory.

A Password can be used as a hard-coded PasswordCallback.

See Also:
PasswordCallback, Serialized Form

Constructor Summary

Password(char[] pw)
Creates a Password from a char array, then wipes the char array.

Method Summary

static byte[]
charToByte(char[] charArray)
Converts a char array to a null-terminated byte array using a standard encoding, which is currently UTF8.
void
clear()
Clears the password so that sensitive data is no longer present in memory.
Object
clone()
Clones the password.
boolean
equals(Object obj)
Compares this password to another and returns true if they are the same.
protected void
finalize()
The finalizer clears the sensitive information before releasing it to the garbage collector, but it should have been cleared manually before this point anyway.
char[]
getCharCopy()
Returns a char array that is a copy of the password.
char[]
getChars()
Returns the char array underlying this password.
Password
getPasswordAgain(PasswordCallbackInfo info)
An implementation of PasswordCallback.getPasswordAgain.
Password
getPasswordFirstAttempt(PasswordCallbackInfo info)
An implementation of PasswordCallback.getPasswordFirstAttempt.
static Password
readPasswordFromConsole()
Reads a password from the console with echo disabled.
static void
wipeBytes(byte[] byteArray)
Wipes a byte array by setting all its elements to zero.
static void
wipeChars(char[] charArray)
Wipes a char array by setting all its elements to zero.

Constructor Details

Password

public Password(char[] pw)
Creates a Password from a char array, then wipes the char array.
Parameters:
pw - A char[] containing the password. This array will be cleared (set to zeroes) by the constructor.

Method Details

charToByte

public static byte[] charToByte(char[] charArray)
Converts a char array to a null-terminated byte array using a standard encoding, which is currently UTF8. The caller is responsible for clearing the copy (with wipeBytes, for example).
Parameters:
charArray - A character array, which should not be null. It will be wiped with zeroes.
Returns:
A copy of the charArray, converted from Unicode to UTF8. It is the responsibility of the caller to clear the output byte array; wipeBytes is ideal for this purpose.

clear

public void clear()
Clears the password so that sensitive data is no longer present in memory. This should be called as soon as the password is no longer needed.

clone

public Object clone()
Clones the password. The resulting clone will be completely independent of the parent, which means it will have to be separately cleared.

equals

public boolean equals(Object obj)
Compares this password to another and returns true if they are the same.

finalize

protected void finalize()
            throws Throwable
The finalizer clears the sensitive information before releasing it to the garbage collector, but it should have been cleared manually before this point anyway.

getCharCopy

public char[] getCharCopy()
Returns a char array that is a copy of the password. The caller is responsible for wiping the returned array, for example using wipeChars.

getChars

public char[] getChars()
Returns the char array underlying this password. It must not be modified in any way.

getPasswordAgain

public Password getPasswordAgain(PasswordCallbackInfo info)
            throws PasswordCallback.GiveUpException
An implementation of PasswordCallback.getPasswordAgain. This allows a Password object to be used as a PasswordCallback. This method is only called after a call to getPasswordFirstAttempt returned the wrong password. This means the password is incorrect and there's no sense returning it again, so a GiveUpException is thrown.
Specified by:
getPasswordAgain in interface PasswordCallback

getPasswordFirstAttempt

public Password getPasswordFirstAttempt(PasswordCallbackInfo info)
            throws PasswordCallback.GiveUpException
An implementation of PasswordCallback.getPasswordFirstAttempt. This allows a Password object to be treated as a PasswordCallback. This method simply returns a clone of the password.
Specified by:
getPasswordFirstAttempt in interface PasswordCallback
Returns:
A copy of the password. The caller is responsible for clearing this copy.

readPasswordFromConsole

public static Password readPasswordFromConsole()
            throws PasswordCallback.GiveUpException
Reads a password from the console with echo disabled. This is a blocking call which will return after the user types a newline. It only works with ASCII password characters. The call is synchronized because it alters terminal settings in a way that is not thread-safe.
Returns:
The password the user entered at the command line.
Throws:
PasswordCallback.GiveUpException - If the user enters no password (just hits <enter>).

wipeBytes

public static void wipeBytes(byte[] byteArray)
Wipes a byte array by setting all its elements to zero. null must not be passed in.

wipeChars

public static void wipeChars(char[] charArray)
Wipes a char array by setting all its elements to zero. null must not be passed in.