Module com.aoapps.security

Package com.aoapps.security

Class HashedKey

java.lang.Object

com.aoapps.security.HashedKey

All Implemented Interfaces:

Serializable, Comparable<HashedKey>

public final class HashedKey
extends Object
implements Comparable<HashedKey>, Serializable

A hashed random key.

Author:

AO Industries, Inc.

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	HashedKey.Algorithm	See MessageDigest Algorithms.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ALGORITHM	Deprecated. This is the value matching the previous default algorithm, please use HashedKey.Algorithm.getAlgorithmName() instead.
static final int	HASH_BYTES	Deprecated. This is the value matching the previous default algorithm, please use HashedKey.Algorithm.getHashBytes() instead.
static final HashedKey	NO_KEY	A singleton that must be used in places where no key is set.
static final String	NO_KEY_VALUE	Indicates that no key is set.
static final HashedKey.Algorithm	RECOMMENDED_ALGORITHM	The algorithm recommended for use with new keys.

Constructor Summary

Constructors

Constructor	Description
HashedKey(byte[] hash)	Deprecated. This represents a hash using the previous default algorithm, please use HashedKey(com.aoapps.security.HashedKey.Algorithm, byte[]) instead.
HashedKey(HashedKey.Algorithm algorithm, byte[] hash)	Deprecated. Please use valueOf(com.aoapps.security.HashedKey.Algorithm, byte[]), which is able to automatically return the NO_KEY singleton.

Method Summary

Modifier and Type	Method	Description
int	compareTo(HashedKey other)
boolean	equals(Object obj)	Checks if equal to another hashed key, always false when either is NO_KEY.
static byte[]	generateKey()	Deprecated. This generates a key for the previous default algorithm, using the previous default of 256-bit length, please use HashedKey.Algorithm.generateKey() instead.
HashedKey.Algorithm	getAlgorithm()
byte[]	getHash()
static byte[]	hash(byte[] key)	Deprecated. This generates a hash for the previous default algorithm and does not zero the key, please use HashedKey.Algorithm.hash(byte[]) instead.
int	hashCode()	The hash code is taken from the last 32 bits of the hash.
static void	main(String... args)
boolean	matches(Key key)	Checks if this matches the provided key, always false when is NO_KEY.
String	toString()	Gets the string representation of the hashed key The format is subject to change over time, but will maintain backward compatibility.
static HashedKey	valueOf(HashedKey.Algorithm algorithm, byte[] hash)	Restores a HashedKey from its individual fields.
static HashedKey	valueOf(String hashedKey)	Parses the result of toString().

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

NO_KEY_VALUE

public static final String NO_KEY_VALUE

Indicates that no key is set.

See Also:

• Constant Field Values

ALGORITHM

@Deprecated
public static final String ALGORITHM

Deprecated.

This is the value matching the previous default algorithm, please use HashedKey.Algorithm.getAlgorithmName() instead.

RECOMMENDED_ALGORITHM

public static final HashedKey.Algorithm RECOMMENDED_ALGORITHM

The algorithm recommended for use with new keys. This may change at any time, but previous algorithms will remain supported.

HASH_BYTES

@Deprecated
public static final int HASH_BYTES

Deprecated.

This is the value matching the previous default algorithm, please use HashedKey.Algorithm.getHashBytes() instead.

The number of bytes in the SHA-256 hash.

NO_KEY

public static final HashedKey NO_KEY

A singleton that must be used in places where no key is set.

Constructor Details

HashedKey

@Deprecated
public HashedKey(HashedKey.Algorithm algorithm,
 byte[] hash)
          throws IllegalArgumentException

Deprecated.

Please use valueOf(com.aoapps.security.HashedKey.Algorithm, byte[]), which is able to automatically return the NO_KEY singleton.

Parameters:

algorithm - The algorithm previously used to hash the key

Throws:

IllegalArgumentException - when hash.length != algorithm.getHashBytes()

HashedKey

@Deprecated
public HashedKey(byte[] hash)
          throws IllegalArgumentException

Deprecated.

This represents a hash using the previous default algorithm, please use HashedKey(com.aoapps.security.HashedKey.Algorithm, byte[]) instead.

Throws:

IllegalArgumentException - when hash.length != HASH_BYTES

Method Details

generateKey

@Deprecated
public static byte[] generateKey()

Deprecated.

This generates a key for the previous default algorithm, using the previous default of 256-bit length, please use HashedKey.Algorithm.generateKey() instead.

Generates a random plaintext key of HASH_BYTES bytes in length using a default SecureRandom instance, which is not a strong instance to avoid blocking.

Returns:

The caller must zero this array once no longer needed.

See Also:

• hash(byte[])

hash

@Deprecated
public static byte[] hash(byte[] key)

Deprecated.

This generates a hash for the previous default algorithm and does not zero the key, please use HashedKey.Algorithm.hash(byte[]) instead.

Hashes the given key.

Parameters:

key - Is not zeroed

See Also:

• generateKey()

valueOf

public static HashedKey valueOf(String hashedKey)
                         throws IllegalArgumentException

Parses the result of toString().

Parameters:

hashedKey - when null, returns null

Throws:

IllegalArgumentException

valueOf

public static HashedKey valueOf(HashedKey.Algorithm algorithm,
 byte[] hash)
                         throws IllegalArgumentException

Restores a HashedKey from its individual fields. This is useful for reading the object from a database, for example.

Parameters:

algorithm - The algorithm previously used to hash the key

Throws:

IllegalArgumentException - when hash.length != algorithm.getHashBytes()

toString

public String toString()

Gets the string representation of the hashed key The format is subject to change over time, but will maintain backward compatibility.

Please see valueOf(java.lang.String) for the inverse operation.

Overrides:

toString in class Object

equals

public boolean equals(Object obj)

Checks if equal to another hashed key, always false when either is NO_KEY.

Performs comparisons in length-constant time. https://crackstation.net/hashing-security.htm

Overrides:

equals in class Object

hashCode

public int hashCode()

The hash code is taken from the last 32 bits of the hash. The last 32 bits are selected because the first bits might include zero padding when the hash length is not a multiple of Byte.SIZE.

Overrides:

hashCode in class Object

compareTo

public int compareTo(HashedKey other)

Specified by:

compareTo in interface Comparable<HashedKey>

getAlgorithm

public HashedKey.Algorithm getAlgorithm()

getHash

public byte[] getHash()

Returns:

Defensive copy

matches

public boolean matches(Key key)

Checks if this matches the provided key, always false when is NO_KEY.

This is most direct when the specific hash to verify against is already known. However, when searching for a hashed value by original key, such as in a mapping or database table, one would create a new instance to act as the look-up value.

Performs comparisons in length-constant time. https://crackstation.net/hashing-security.htm

Parameters:

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

See Also:

• HashedKey.Algorithm.validateKey(java.util.function.Function, com.aoapps.security.Key)

main

public static void main(String... args)