org.apache.shiro.authc.credential
Class HashedCredentialsMatcher

java.lang.Object
  org.apache.shiro.codec.CodecSupport
      org.apache.shiro.authc.credential.SimpleCredentialsMatcher
          org.apache.shiro.authc.credential.HashedCredentialsMatcher

All Implemented Interfaces:

CredentialsMatcher

Direct Known Subclasses:

Md2CredentialsMatcher, Md5CredentialsMatcher, Sha1CredentialsMatcher, Sha256CredentialsMatcher, Sha384CredentialsMatcher, Sha512CredentialsMatcher

public abstract class HashedCredentialsMatcher
extends SimpleCredentialsMatcher

A HashedCredentialMatcher provides support for hashing of supplied AuthenticationToken credentials before being compared to those in the AuthenticationInfo from the data store.

Credential hashing is one of the most common security techniques when safeguarding a user's private credentials (passwords, keys, etc). Most developers never want to store their users' credentials in plain form, viewable by anyone, so they often hash the users' credentials before they are saved in the data store.

This class (and its subclasses) function as follows:

It first hashes the AuthenticationToken credentials supplied by the user during their login. It then compares this hashed value directly with the AuthenticationInfo credentials stored in the system. The stored account credentials are expected to already be in hashed form. If these two values are equal, the submitted credentials match.

Salting and Multiple Hash Iterations

Because simple hashing is sometimes not good enough for many applications, this class also supports 'salting' and multiple hash iterations. Please read this excellent Hashing Java article to learn about salting and multiple iterations and why you might want to use them. (Note of sections 5 "Why add salt?" and 6 "Hardening against the attacker's attack").

We should also note here that all of Shiro's Hash implementations (for example, Md5Hash, Sha1Hash, etc) support salting and multiple hash iterations via overloaded constructors.

Salting

Salting of the authentication token's credentials hash is disabled by default, but you may enable it by setting hashSalted to true. If you do enable it, the value used to salt the hash will be obtained from getSalt(authenticationToken).

The default getSalt implementation merely returns token.getPrincipal(), effectively using the user's identity as the salt, a most common technique. If you wish to provide the authentication token's salt another way, you may override this getSalt method.

Multiple Hash Iterations

If you hash your users' credentials multiple times before persisting to the data store, you will also need to set this class's hashIterations property.

Note: MD5 and SHA-1 algorithms are now known to be vulnerable to compromise and/or collisions (read the linked pages for more). While most applications are ok with either of these two, if your application mandates high security, use the SHA-256 (or higher) hashing algorithms and their supporting CredentialsMatcher implementations.

Since:

0.9

Author:

Les Hazlewood

See Also:

Md5Hash, Sha1Hash, Sha256Hash

Field Summary

Fields inherited from class org.apache.shiro.codec.CodecSupport

PREFERRED_ENCODING

Constructor Summary

HashedCredentialsMatcher()

Method Summary

protected Object	getCredentials(AuthenticationInfo info) Returns a Hash instance representing the already-hashed AuthenticationInfo credentials stored in the system.
protected Object	getCredentials(AuthenticationToken token) As this is a HashedCredentialMatcher, this method overrides the parent method by returning a hashed value of the submitted token's credentials.
int	getHashIterations() Returns the number of times a submitted AuthenticationToken's credentials will be hashed before comparing to the credentials stored in the system.
protected Object	getSalt(AuthenticationToken token) Returns a salt value used to hash the token's credentials.
protected abstract Hash	hashProvidedCredentials(Object credentials, Object salt, int hashIterations) Hashes the provided credentials a total of hashIterations times, using the given salt.
boolean	isHashSalted() Returns true if a submitted AuthenticationToken's credentials should be salted when hashing, false if it should not be salted.
boolean	isStoredCredentialsHexEncoded() Returns true if the system's stored credential hash is Hex encoded, false if it is Base64 encoded.
protected abstract AbstractHash	newHashInstance() Returns a new, uninitialized instance, without its byte array set.
void	setHashIterations(int hashIterations) Sets the number of times a submitted AuthenticationToken's credentials will be hashed before comparing to the credentials stored in the system.
void	setHashSalted(boolean hashSalted) Sets whether or not to salt a submitted AuthenticationToken's credentials when hashing.
void	setStoredCredentialsHexEncoded(boolean storedCredentialsHexEncoded) Sets the indicator if this system's stored credential hash is Hex encoded or not.

Methods inherited from class org.apache.shiro.authc.credential.SimpleCredentialsMatcher

doCredentialsMatch, equals

Methods inherited from class org.apache.shiro.codec.CodecSupport

isByteSource, objectToBytes, objectToString, toBytes, toBytes, toBytes, toBytes, toBytes, toBytes, toBytes, toChars, toChars, toString, toString, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

HashedCredentialsMatcher

public HashedCredentialsMatcher()

Method Detail

isStoredCredentialsHexEncoded

public boolean isStoredCredentialsHexEncoded()

Returns true if the system's stored credential hash is Hex encoded, false if it is Base64 encoded.

Default value is true for convenience - all of Shiro's Hash#toString() implementations return Hex encoded values by default, making this class's use with those implementations easier.

Returns:

true if the system's stored credential hash is Hex encoded, false if it is Base64 encoded. Default is true

setStoredCredentialsHexEncoded

public void setStoredCredentialsHexEncoded(boolean storedCredentialsHexEncoded)

Sets the indicator if this system's stored credential hash is Hex encoded or not.

A value of true will cause this class to decode the system credential from Hex, a value of false will cause this class to decode the system credential from Base64.

Unless overridden via this method, the default value is true for convenience - all of Shiro's Hash#toString() implementations return Hex encoded values by default, making this class's use with those implementations easier.

Parameters:

storedCredentialsHexEncoded - the indicator if this system's stored credential hash is Hex encoded or not ('not' automatically implying it is Base64 encoded).

isHashSalted

public boolean isHashSalted()

Returns true if a submitted AuthenticationToken's credentials should be salted when hashing, false if it should not be salted.

If enabled, the salt used will be obtained via the getSalt method.

The default value is false.

Returns:

true if a submitted AuthenticationToken's credentials should be salted when hashing, false if it should not be salted.

setHashSalted

public void setHashSalted(boolean hashSalted)

Sets whether or not to salt a submitted AuthenticationToken's credentials when hashing.

If enabled, the salt used will be obtained via the getSalt method.

The default value is false.

Parameters:

hashSalted - whether or not to salt a submitted AuthenticationToken's credentials when hashing.

getHashIterations

public int getHashIterations()

Returns the number of times a submitted AuthenticationToken's credentials will be hashed before comparing to the credentials stored in the system.

Unless overridden, the default value is 1, meaning a normal hash execution will occur.

Returns:

the number of times a submitted AuthenticationToken's credentials will be hashed before comparing to the credentials stored in the system.

setHashIterations

public void setHashIterations(int hashIterations)

Sets the number of times a submitted AuthenticationToken's credentials will be hashed before comparing to the credentials stored in the system.

Unless overridden, the default value is 1, meaning a normal single hash execution will occur.

If this argument is less than 1 (i.e. 0 or negative), the default value of 1 is applied. There must always be at least 1 hash iteration (otherwise there would be no hash).

Parameters:

hashIterations - the number of times to hash a submitted AuthenticationToken's credentials.

getSalt

protected Object getSalt(AuthenticationToken token)

Returns a salt value used to hash the token's credentials.

This default implementation merely returns token.getPrincipal(), effectively using the user's identity (username, user id, etc) as the salt, a most common technique. If you wish to provide the authentication token's salt another way, you may override this method.

Parameters:

token - the AuthenticationToken submitted during the authentication attempt.

Returns:

a salt value to use to hash the authentication token's credentials.

getCredentials

protected Object getCredentials(AuthenticationToken token)

As this is a HashedCredentialMatcher, this method overrides the parent method by returning a hashed value of the submitted token's credentials.

Based on this class's configuration, the return value may be salted and/or hashed multiple times (see the class-level JavaDoc for more information on salting and multiple hash iterations).

Overrides:

getCredentials in class SimpleCredentialsMatcher

Parameters:

token - the authentication token submitted during the authentication attempt.

Returns:

the hashed value of the authentication token's credentials.

getCredentials

protected Object getCredentials(AuthenticationInfo info)

Returns a Hash instance representing the already-hashed AuthenticationInfo credentials stored in the system.

This method reconstructs a Hash instance based on a info.getCredentials call, but it does not hash that value - it is expected that method call will return an already-hashed value.

This implementation's reconstruction effort functions as follows:

1. Convert account.getCredentials() to a byte array via the toBytes method.
2. If account.getCredentials() was originally a String or char[] before toBytes was called, check for encoding:
3. If storedCredentialsHexEncoded, Hex decode that byte array, otherwise Base64 decode the byte array
4. Set the byte[] array directly on the Hash implementation and return it.

Overrides:

getCredentials in class SimpleCredentialsMatcher

Parameters:

info - the AuthenticationInfo from which to retrieve the credentials which assumed to be in already-hashed form.

Returns:

a Hash instance representing the given AuthenticationInfo's stored credentials.

hashProvidedCredentials

protected abstract Hash hashProvidedCredentials(Object credentials,
                                                Object salt,
                                                int hashIterations)

Hashes the provided credentials a total of hashIterations times, using the given salt. The hash implementation/algorithm used is left to subclasses.

Parameters:

credentials - the submitted authentication token's credentials to hash

salt - the value to salt the hash, or null if a salt will not be used.

hashIterations - the number of times to hash the credentials. At least one hash will always occur though, even if this argument is 0 or negative.

Returns:

the hashed value of the provided credentials, according to the specified salt and hash iterations.

newHashInstance

protected abstract AbstractHash newHashInstance()

Returns a new, uninitialized instance, without its byte array set. Used as a utility method in the getCredentials(AuthenticationInfo) implementation.

Returns:

a new, uninitialized instance, without its byte array set.