Module com.aoapps.security

Package com.aoapps.security

Enum HashedPassword.Algorithm

java.lang.Object

java.lang.Enum<HashedPassword.Algorithm>

com.aoapps.security.HashedPassword.Algorithm

All Implemented Interfaces:

Serializable, Comparable<HashedPassword.Algorithm>

Enclosing class:

HashedPassword

public static enum HashedPassword.Algorithm
extends Enum<HashedPassword.Algorithm>

See Also:

• SecretKeyFactory

Enum Constant Summary

Enum Constants

Enum Constant	Description
CRYPT	Deprecated. UnixCrypt should not be used for any cryptographic purpose, plus this is barely salted and not iterated so is subject to both dictionary and brute-force attacks.
MD5	Deprecated. MD5 should not be used for any cryptographic purpose, plus this is neither salted nor iterated so is subject to both dictionary and brute-force attacks.
PBKDF2WITHHMACSHA1	Deprecated. This was the previous algorithm used.
PBKDF2WITHHMACSHA224	Deprecated. Collision resistance of at least 128 bits is required
PBKDF2WITHHMACSHA256
PBKDF2WITHHMACSHA384
PBKDF2WITHHMACSHA512
SHA_1	Deprecated. SHA-1 should no longer be used for any cryptographic purpose, plus this is neither salted nor iterated so is subject to both dictionary and brute-force attacks.

Method Summary

Modifier and Type	Method	Description
static HashedPassword.Algorithm	findAlgorithm(String algorithmName)	Case-insensitive lookup by algorithm name.
byte[]	generateSalt()	Generates a random salt of getSaltBytes() bytes in length using a default SecureRandom instance, which is not a strong instance to avoid blocking.
byte[]	generateSalt(SecureRandom secureRandom)	Generates a random salt of getSaltBytes() bytes in length using the provided SecureRandom source.
byte[]	generateSalt(Random random)	Deprecated. Please use SecureRandom.
String	getAlgorithmName()	Gets the SecretKeyFactory algorithm name.
int	getHashBytes()	Gets the number of bytes required to store the generated hash.
int	getMaximumIterations()	Gets the maximum number of iterations allowed or 0 when algorithm is not iterated.
int	getMinimumIterations()	Gets the minimum number of iterations allowed or 0 when algorithm is not iterated.
int	getRecommendedIterations()	Gets the recommended number of iterations for typical usage or 0 when algorithm is not iterated.
int	getSaltBytes()	Gets the number of bytes of cryptographically strong random data that must be used with this algorithm.
byte[]	hash(Password password, byte[] salt, int iterations)	Hash the given password to getHashBytes() bytes.
byte[]	hash(String password, byte[] salt, int iterations)	Deprecated. Please use hash(com.aoapps.security.Password, byte[], int) so the password may be destroyed.
String	toString()
<Ex extends Throwable> void	validate(Function<? super String,Ex> newThrowable, byte[] salt, int iterations, byte[] hash)
<Ex extends Throwable> byte[]	validateHash(Function<? super String,Ex> newThrowable, byte[] hash)
<Ex extends Throwable> int	validateIterations(Function<? super String,Ex> newThrowable, int iterations)
<Ex extends Throwable> byte[]	validateSalt(Function<? super String,Ex> newThrowable, byte[] salt)
static HashedPassword.Algorithm	valueOf(String name)	Returns the enum constant of this type with the specified name.
static HashedPassword.Algorithm[]	values()	Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

CRYPT

@Deprecated
public static final HashedPassword.Algorithm CRYPT

Deprecated.

UnixCrypt should not be used for any cryptographic purpose, plus this is barely salted and not iterated so is subject to both dictionary and brute-force attacks.

MD5

@Deprecated
public static final HashedPassword.Algorithm MD5

Deprecated.

MD5 should not be used for any cryptographic purpose, plus this is neither salted nor iterated so is subject to both dictionary and brute-force attacks.

SHA_1

@Deprecated
public static final HashedPassword.Algorithm SHA_1

Deprecated.

SHA-1 should no longer be used for any cryptographic purpose, plus this is neither salted nor iterated so is subject to both dictionary and brute-force attacks.

PBKDF2WITHHMACSHA1

@Deprecated
public static final HashedPassword.Algorithm PBKDF2WITHHMACSHA1

Deprecated.

This was the previous algorithm used. Please use PBKDF2WITHHMACSHA512, which is the current HashedPassword.RECOMMENDED_ALGORITHM, for new passwords.

From https://crackstation.net/hashing-security.htm

PBKDF2WITHHMACSHA224

@Deprecated
public static final HashedPassword.Algorithm PBKDF2WITHHMACSHA224

Deprecated.

Collision resistance of at least 128 bits is required

PBKDF2WITHHMACSHA256

public static final HashedPassword.Algorithm PBKDF2WITHHMACSHA256

PBKDF2WITHHMACSHA384

public static final HashedPassword.Algorithm PBKDF2WITHHMACSHA384

PBKDF2WITHHMACSHA512

public static final HashedPassword.Algorithm PBKDF2WITHHMACSHA512

Method Details

values

public static HashedPassword.Algorithm[] values()

Returns an array containing the constants of this enum type, in the order they are declared.

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static HashedPassword.Algorithm valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

findAlgorithm

public static HashedPassword.Algorithm findAlgorithm(String algorithmName)
                                              throws IllegalArgumentException

Case-insensitive lookup by algorithm name.

Returns:

The algorithm or null when algorithmName == null

Throws:

IllegalArgumentException - when no enum with the given algorithm name (case-insensitive) is found

toString

public String toString()

Overrides:

toString in class Enum<HashedPassword.Algorithm>

getAlgorithmName

public String getAlgorithmName()

Gets the SecretKeyFactory algorithm name.

getSaltBytes

public int getSaltBytes()

Gets the number of bytes of cryptographically strong random data that must be used with this algorithm.

validateSalt

public <Ex extends Throwable> byte[] validateSalt(Function<? super String,Ex> newThrowable,
 byte[] salt)
                                           throws Ex

Type Parameters:

Ex - An arbitrary exception type that may be thrown

Throws:

Ex

generateSalt

@Deprecated
public byte[] generateSalt(Random random)

Deprecated.

Please use SecureRandom. This method will stay, but will remain deprecated since it should only be used after careful consideration.

Generates a random salt of getSaltBytes() bytes in length using the provided Random source.

See Also:

• HashedPassword(com.aoapps.security.Password, java.util.Random)
• HashedPassword(com.aoapps.security.Password, com.aoapps.security.HashedPassword.Algorithm, java.util.Random)
• HashedPassword(com.aoapps.security.Password, com.aoapps.security.HashedPassword.Algorithm, int, java.util.Random)

generateSalt

public byte[] generateSalt(SecureRandom secureRandom)

Generates a random salt of getSaltBytes() bytes in length using the provided SecureRandom source.

See Also:

• HashedPassword(com.aoapps.security.Password, java.security.SecureRandom)
• HashedPassword(com.aoapps.security.Password, com.aoapps.security.HashedPassword.Algorithm, java.security.SecureRandom)
• HashedPassword(com.aoapps.security.Password, com.aoapps.security.HashedPassword.Algorithm, int, java.security.SecureRandom)

generateSalt

public byte[] generateSalt()

Generates a random salt of getSaltBytes() bytes in length using a default SecureRandom instance, which is not a strong instance to avoid blocking.

See Also:

• HashedPassword(com.aoapps.security.Password)
• HashedPassword(com.aoapps.security.Password, com.aoapps.security.HashedPassword.Algorithm)
• HashedPassword(com.aoapps.security.Password, com.aoapps.security.HashedPassword.Algorithm, int)

getMinimumIterations

public int getMinimumIterations()

Gets the minimum number of iterations allowed or 0 when algorithm is not iterated.

getMaximumIterations

public int getMaximumIterations()

Gets the maximum number of iterations allowed or 0 when algorithm is not iterated.

getRecommendedIterations

public int getRecommendedIterations()

Gets the recommended number of iterations for typical usage or 0 when algorithm is not iterated.

We may change this value between releases without notice. Only use this value for new password hashes. Always store the iterations with the salt and hash, and use the stored iterations when checking password matches.

It is recommended to re-hash a password during login when the recommended iterations has changed.

This value is selected to complete the hashing in around 100L ms on commodity PC hardware from around the year 2012.

See Also:

• hash(java.lang.String, byte[], int)
• HashedPassword(com.aoapps.security.Password)
• HashedPassword(com.aoapps.security.Password, java.security.SecureRandom)
• HashedPassword(com.aoapps.security.Password, com.aoapps.security.HashedPassword.Algorithm)
• HashedPassword(com.aoapps.security.Password, com.aoapps.security.HashedPassword.Algorithm, java.security.SecureRandom)

validateIterations

public <Ex extends Throwable> int validateIterations(Function<? super String,Ex> newThrowable,
 int iterations)
                                              throws Ex

Type Parameters:

Ex - An arbitrary exception type that may be thrown

Throws:

Ex

getHashBytes

public int getHashBytes()

Gets the number of bytes required to store the generated hash.

validateHash

public <Ex extends Throwable> byte[] validateHash(Function<? super String,Ex> newThrowable,
 byte[] hash)
                                           throws Ex

Type Parameters:

Ex - An arbitrary exception type that may be thrown

Throws:

Ex

validate

public <Ex extends Throwable> void validate(Function<? super String,Ex> newThrowable,
 byte[] salt,
 int iterations,
 byte[] hash)
                                     throws Ex

Type Parameters:

Ex - An arbitrary exception type that may be thrown

Throws:

Ex

hash

public byte[] hash(Password password,
 byte[] salt,
 int iterations)

Hash the given password to getHashBytes() bytes.

Parameters:

password - Is destroyed before this method returns. If the original password is needed, pass a clone to this method.

See Also:

• generateSalt()
• getRecommendedIterations()

hash

@Deprecated
public byte[] hash(String password,
 byte[] salt,
 int iterations)

Deprecated.

Please use hash(com.aoapps.security.Password, byte[], int) so the password may be destroyed.

Hash the given password to getHashBytes() bytes.

See Also:

• generateSalt()
• getRecommendedIterations()