Package com.atlassian.security.password

Class DefaultPasswordEncoder

java.lang.Object

com.atlassian.security.password.DefaultPasswordEncoder

All Implemented Interfaces:

PasswordEncoder

public final class DefaultPasswordEncoder
extends Object
implements PasswordEncoder

Converts salt and encoded password bytes into a standard base64 encoding for storage. Strings are converted to and from bytes using the UTF-8 encoding. A prefix is added in braces (e.g. "{SHA}") to distinguish between different implementations.

It is strongly recommended that clients use the default implementation returned by getDefaultInstance(), which uses PKCS5S2PasswordHashGenerator with RandomSaltGenerator.

The storage format used by this class is "{" + identifier + "}" + encodedSaltAndHash, where identifier and saltPlusHash are defined as follows:

• identifier: the identifier string provided to the constructor
• encodedSaltAndHash: the result of new String(encodeBase64(saltAndHash), "UTF-8")
• encodeBase64: the result of encodeBase64(saltAndHash)
• saltAndHash: the result of ArrayUtils.add(salt, hash)
• salt: the result of SaltGenerator.generateSalt(int)
• hash: the result of passwordHashGenerator.generateHash(password.getBytes("UTF-8"), salt)

Clients must provide an identifier, hash generator and salt generator in the constructor, or use the default implementation returned by getDefaultInstance().

The thread-safety of this encoder depends on the thread-safety of the hash and salt generators used. The encoder returned by getDefaultInstance() is safe for use on multiple threads.

See Also:

• Base64.encodeBase64(byte[])
• PasswordHashGenerator
• SaltGenerator

Constructor Summary

Constructors

Constructor	Description
DefaultPasswordEncoder(String identifier, PasswordHashGenerator hashGenerator, SaltGenerator saltGenerator)	Constructs a new encoder with specified identifier, hash generator and salt generator.

Method Summary

Modifier and Type	Method	Description
final boolean	canDecodePassword(String encodedPassword)	Returns true if the encodedPassword is in the right format for decoding and verification by this implementation, otherwise false.
final String	encodePassword(String rawPassword)	Encodes a password and returns it as a String suitable for storage by the client.
static PasswordEncoder	getDefaultInstance()	Returns a new encoder with identifier "PKCS5S2" using PKCS5S2PasswordHashGenerator as the hash generator and RandomSaltGenerator as the salt generator.
final boolean	isValidPassword(String rawPassword, String prefixedEncodedPassword)	Returns true if the rawPassword matches the stored password hash in encodedPassword, otherwise false.
static PasswordEncoder	newInstance(String identifier, PasswordHashGenerator hashGenerator)	Returns a new encoder with specified identifier and hash generator, usingRandomSaltGenerator as the salt generator.

Methods inherited from class java.lang.Object

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

Constructor Details

DefaultPasswordEncoder

public DefaultPasswordEncoder(String identifier,
 PasswordHashGenerator hashGenerator,
 SaltGenerator saltGenerator)

Constructs a new encoder with specified identifier, hash generator and salt generator.

The thread-safety of this instance depends on the thread-safety of the hash and salt generator implementations.

Method Details

getDefaultInstance

public static PasswordEncoder getDefaultInstance()

Returns a new encoder with identifier "PKCS5S2" using PKCS5S2PasswordHashGenerator as the hash generator and RandomSaltGenerator as the salt generator.

This instance is safe for use by multiple threads.

See Also:

• PKCS5S2PasswordHashGenerator
• RandomSaltGenerator

newInstance

public static PasswordEncoder newInstance(String identifier,
 PasswordHashGenerator hashGenerator)

Returns a new encoder with specified identifier and hash generator, usingRandomSaltGenerator as the salt generator.

The thread-safety of this instance depends on the thread-safety of the hash generator implementation.

canDecodePassword

public final boolean canDecodePassword(String encodedPassword)

Description copied from interface: PasswordEncoder

Returns true if the encodedPassword is in the right format for decoding and verification by this implementation, otherwise false. For example, implementations might check the length of the encoded password or look for a particular prefix in the encoded string.

Specified by:

canDecodePassword in interface PasswordEncoder

Parameters:

encodedPassword - the stored password associated with this user

Returns:

true if the encodedPassword can be decoded by this implementation, otherwise false

encodePassword

public final String encodePassword(String rawPassword)
                            throws IllegalArgumentException

Description copied from interface: PasswordEncoder

Encodes a password and returns it as a String suitable for storage by the client.

Implementations must perform a one-way hashing operation on the rawPassword so that the rawPassword cannot practically be derived from the encoded result by an attacker.

It is recommended that implementations include a unique prefix in their encoded form which will allow PasswordEncoder.canDecodePassword(String) to be implemented easily.

Specified by:

encodePassword in interface PasswordEncoder

Parameters:

rawPassword - the password provided by the user

Returns:

the encoded password

Throws:

IllegalArgumentException - if the rawPassword is null or empty

isValidPassword

public final boolean isValidPassword(String rawPassword,
 String prefixedEncodedPassword)
                              throws IllegalArgumentException

Description copied from interface: PasswordEncoder

Returns true if the rawPassword matches the stored password hash in encodedPassword, otherwise false. The encodedPassword parameter should be the result of an earlier call to PasswordEncoder.encodePassword(String). If the encoded password is not in a format which is handled by this encoder, this method will return false.

If multiple encodings are supported by an application, the client should call PasswordEncoder.canDecodePassword(String) to check that the password was generated by this encoder before calling this method.

Specified by:

isValidPassword in interface PasswordEncoder

Parameters:

rawPassword - the raw password provided by the user for authentication

prefixedEncodedPassword - the stored password associated with the user

Returns:

true if the rawPassword is a match for the

Throws:

IllegalArgumentException - if either rawPassword or encodedPassword is null or empty