Package org.apache.shiro.crypto.hash

Class SimpleHash

java.lang.Object
org.apache.shiro.lang.codec.CodecSupport
org.apache.shiro.crypto.hash.SimpleHash
All Implemented Interfaces:
Serializable, Hash, org.apache.shiro.lang.util.ByteSource
Direct Known Subclasses:
Sha256Hash, Sha384Hash, Sha512Hash
public class SimpleHash extends org.apache.shiro.lang.codec.CodecSupport implements Hash, Serializable
A Hash implementation that allows any MessageDigest algorithm name to be used. This class is a less type-safe variant than the other AbstractHash subclasses (e.g. Sha512Hash, etc.), but it does allow for any algorithm name to be specified in case the other subclass implementations do not represent an algorithm that you may want to use.

As of Shiro 1.1, this class effectively replaces the (now-deprecated) AbstractHash class. It subclasses AbstractHash only to retain backwards-compatibility.

Since:
1.1
See Also:

  • Nested Class Summary

    Nested classes/interfaces inherited from interface org.apache.shiro.lang.util.ByteSource

    org.apache.shiro.lang.util.ByteSource.Util

  • Field Summary

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

    PREFERRED_ENCODING

  • Constructor Summary

    Constructors
    Constructor
    Description
    SimpleHash(String algorithmName)
    Creates an new instance with only its algorithmName set - no hashing is performed.
    SimpleHash(String algorithmName, Object source)
    Creates an algorithmName-specific hash of the specified source with no salt using a single hash iteration.
    SimpleHash(String algorithmName, Object source, int hashIterations)
    Creates an algorithmName-specific hash of the specified source using the given salt using a single hash iteration.
    SimpleHash(String algorithmName, Object source, Object salt)
    Creates an algorithmName-specific hash of the specified source using the given salt using a single hash iteration.
    SimpleHash(String algorithmName, Object source, Object salt, int hashIterations)
    Creates an algorithmName-specific hash of the specified source using the given salt a total of hashIterations times.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected org.apache.shiro.lang.util.ByteSource
    convertSaltToBytes(Object salt)
    Acquires the specified salt argument's bytes and returns them in the form of a ByteSource instance.
    protected org.apache.shiro.lang.util.ByteSource
    convertSourceToBytes(Object source)
    Acquires the specified source argument's bytes and returns them in the form of a ByteSource instance.
    boolean
    equals(Object o)
    Returns true if the specified object is a Hash and its byte array is identical to this Hash's byte array, false otherwise.
    String
    getAlgorithmName()
    Returns the MessageDigest algorithm name to use when performing the hash.
    byte[]
    getBytes()
     
    protected MessageDigest
    getDigest(String algorithmName)
    Returns the JDK MessageDigest instance to use for executing the hash.
    int
    getIterations()
    Returns the number of hash iterations used to compute the hash.
    org.apache.shiro.lang.util.ByteSource
    getSalt()
    Returns a salt used to compute the hash or null if no salt was used.
    protected byte[]
    hash(byte[] bytes)
    Hashes the specified byte array without a salt for a single iteration.
    protected byte[]
    hash(byte[] bytes, byte[] salt)
    Hashes the specified byte array using the given salt for a single iteration.
    protected byte[]
    hash(byte[] bytes, byte[] salt, int hashIterations)
    Hashes the specified byte array using the given salt for the specified number of iterations.
    int
    hashCode()
    Simply returns toHex().hashCode();
    boolean
    isEmpty()
     
    boolean
    matchesPassword(org.apache.shiro.lang.util.ByteSource plaintextBytes)
    Tests if a given passwords matches with this instance.
    void
    setBytes(byte[] alreadyHashedBytes)
    Sets the raw bytes stored by this hash instance.
    void
    setIterations(int iterations)
    Sets the iterations used to previously compute AN ALREADY GENERATED HASH.
    void
    setSalt(org.apache.shiro.lang.util.ByteSource salt)
    Sets the salt used to previously compute AN ALREADY GENERATED HASH.
    String
    toBase64()
    Returns a Base64-encoded string of the underlying byte array.
    protected org.apache.shiro.lang.util.ByteSource
    toByteSource(Object object)
    Converts a given object into a ByteSource instance.
    String
    toHex()
    Returns a hex-encoded string of the underlying byte array.
    String
    toString()
    Simple implementation that merely returns toHex().

    Methods inherited from class org.apache.shiro.lang.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, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • SimpleHash

      public SimpleHash(String algorithmName)
      Creates an new instance with only its algorithmName set - no hashing is performed.

      Because all other constructors in this class hash the source constructor argument, this constructor is useful in scenarios when you have a byte array that you know is already hashed and just want to set the bytes in their raw form directly on an instance. After using this constructor, you can then immediately call setBytes to have a fully-initialized instance.

      N.B.The algorithm identified by the algorithmName parameter must be available on the JVM. If it is not, a UnknownAlgorithmException will be thrown when the hash is performed (not at instantiation).

      Parameters:
      algorithmName - the MessageDigest algorithm name to use when performing the hash.
      See Also:
      • UnknownAlgorithmException

    • SimpleHash

      public SimpleHash(String algorithmName, Object source) throws org.apache.shiro.lang.codec.CodecException, org.apache.shiro.crypto.UnknownAlgorithmException
      Creates an algorithmName-specific hash of the specified source with no salt using a single hash iteration.

      This is a convenience constructor that merely executes this( algorithmName, source, null, 1);.

      Please see the SimpleHashHash(algorithmName, Object,Object,int) constructor for the types of Objects that may be passed into this constructor, as well as how to support further types.

      Parameters:
      algorithmName - the MessageDigest algorithm name to use when performing the hash.
      source - the object to be hashed.
      Throws:
      org.apache.shiro.lang.codec.CodecException - if the specified source cannot be converted into a byte array (byte[]).
      org.apache.shiro.crypto.UnknownAlgorithmException - if the algorithmName is not available.

    • SimpleHash

      public SimpleHash(String algorithmName, Object source, Object salt) throws org.apache.shiro.lang.codec.CodecException, org.apache.shiro.crypto.UnknownAlgorithmException
      Creates an algorithmName-specific hash of the specified source using the given salt using a single hash iteration.

      It is a convenience constructor that merely executes this( algorithmName, source, salt, 1);.

      Please see the SimpleHashHash(algorithmName, Object,Object,int) constructor for the types of Objects that may be passed into this constructor, as well as how to support further types.

      Parameters:
      algorithmName - the MessageDigest algorithm name to use when performing the hash.
      source - the source object to be hashed.
      salt - the salt to use for the hash
      Throws:
      org.apache.shiro.lang.codec.CodecException - if either constructor argument cannot be converted into a byte array.
      org.apache.shiro.crypto.UnknownAlgorithmException - if the algorithmName is not available.

    • SimpleHash

      public SimpleHash(String algorithmName, Object source, int hashIterations) throws org.apache.shiro.lang.codec.CodecException, org.apache.shiro.crypto.UnknownAlgorithmException
      Creates an algorithmName-specific hash of the specified source using the given salt using a single hash iteration.

      It is a convenience constructor that merely executes this( algorithmName, source, salt, 1);.

      Please see the SimpleHashHash(algorithmName, Object,Object,int) constructor for the types of Objects that may be passed into this constructor, as well as how to support further types.

      Parameters:
      algorithmName - the MessageDigest algorithm name to use when performing the hash.
      source - the source object to be hashed.
      hashIterations - the number of times the source argument hashed for attack resiliency.
      Throws:
      org.apache.shiro.lang.codec.CodecException - if either constructor argument cannot be converted into a byte array.
      org.apache.shiro.crypto.UnknownAlgorithmException - if the algorithmName is not available.

    • SimpleHash

      public SimpleHash(String algorithmName, Object source, Object salt, int hashIterations) throws org.apache.shiro.lang.codec.CodecException, org.apache.shiro.crypto.UnknownAlgorithmException
      Creates an algorithmName-specific hash of the specified source using the given salt a total of hashIterations times.

      By default, this class only supports Object method arguments of type byte[], char[], String, File, InputStream or ByteSource. If either argument is anything other than these types a CodecException will be thrown.

      If you want to be able to hash other object types, or use other salt types, you need to override the toBytes(Object) method to support those specific types. Your other option is to convert your arguments to one of the default supported types first before passing them in to this constructor}.

      Parameters:
      algorithmName - the MessageDigest algorithm name to use when performing the hash.
      source - the source object to be hashed.
      salt - the salt to use for the hash
      hashIterations - the number of times the source argument hashed for attack resiliency.
      Throws:
      org.apache.shiro.lang.codec.CodecException - if either Object constructor argument cannot be converted into a byte array.
      org.apache.shiro.crypto.UnknownAlgorithmException - if the algorithmName is not available.

  • Method Details

    • convertSourceToBytes

      protected org.apache.shiro.lang.util.ByteSource convertSourceToBytes(Object source)
      Acquires the specified source argument's bytes and returns them in the form of a ByteSource instance.

      This implementation merely delegates to the convenience toByteSource(Object) method for generic conversion. Can be overridden by subclasses for source-specific conversion.

      Parameters:
      source - the source object to be hashed.
      Returns:
      the source's bytes in the form of a ByteSource instance.
      Since:
      1.2

    • convertSaltToBytes

      protected org.apache.shiro.lang.util.ByteSource convertSaltToBytes(Object salt)
      Acquires the specified salt argument's bytes and returns them in the form of a ByteSource instance.

      This implementation merely delegates to the convenience toByteSource(Object) method for generic conversion. Can be overridden by subclasses for salt-specific conversion.

      Parameters:
      salt - the salt to be use for the hash.
      Returns:
      the salt's bytes in the form of a ByteSource instance.
      Since:
      1.2

    • toByteSource

      protected org.apache.shiro.lang.util.ByteSource toByteSource(Object object)
      Converts a given object into a ByteSource instance. Assumes the object can be converted to bytes.
      Parameters:
      object - the Object to convert into a ByteSource instance.
      Returns:
      the ByteSource representation of the specified object's bytes.
      Since:
      1.2

    • getAlgorithmName

      public String getAlgorithmName()
      Returns the MessageDigest algorithm name to use when performing the hash.
      Specified by:
      getAlgorithmName in interface Hash
      Returns:
      the MessageDigest algorithm name to use when performing the hash.

    • getSalt

      public org.apache.shiro.lang.util.ByteSource getSalt()
      Description copied from interface: Hash
      Returns a salt used to compute the hash or null if no salt was used.
      Specified by:
      getSalt in interface Hash
      Returns:
      a salt used to compute the hash or null if no salt was used.

    • getIterations

      public int getIterations()
      Description copied from interface: Hash
      Returns the number of hash iterations used to compute the hash.
      Specified by:
      getIterations in interface Hash
      Returns:
      the number of hash iterations used to compute the hash.

    • matchesPassword

      public boolean matchesPassword(org.apache.shiro.lang.util.ByteSource plaintextBytes)
      Description copied from interface: Hash
      Tests if a given passwords matches with this instance.

      Usually implementations will re-create this but with the given plaintext bytes as secret.

      Specified by:
      matchesPassword in interface Hash
      Parameters:
      plaintextBytes - the plaintext bytes from a user.
      Returns:
      true if the given plaintext generates an equal hash with the same parameters as from this hash.

    • getBytes

      public byte[] getBytes()
      Specified by:
      getBytes in interface org.apache.shiro.lang.util.ByteSource

    • setBytes

      public void setBytes(byte[] alreadyHashedBytes)
      Sets the raw bytes stored by this hash instance.

      The bytes are kept in raw form - they will not be hashed/changed. This is primarily a utility method for constructing a Hash instance when the hashed value is already known.

      Parameters:
      alreadyHashedBytes - the raw already-hashed bytes to store in this instance.

    • setIterations

      public void setIterations(int iterations)
      Sets the iterations used to previously compute AN ALREADY GENERATED HASH.

      This is provided ONLY to reconstitute an already-created Hash instance. It should ONLY ever be invoked when re-constructing a hash instance from an already-hashed value.

      Parameters:
      iterations - the number of hash iterations used to previously create the hash/digest.
      Since:
      1.2

    • setSalt

      public void setSalt(org.apache.shiro.lang.util.ByteSource salt)
      Sets the salt used to previously compute AN ALREADY GENERATED HASH.

      This is provided ONLY to reconstitute a Hash instance that has already been computed. It should ONLY ever be invoked when re-constructing a hash instance from an already-hashed value.

      Parameters:
      salt - the salt used to previously create the hash/digest.
      Since:
      1.2

    • getDigest

      protected MessageDigest getDigest(String algorithmName) throws org.apache.shiro.crypto.UnknownAlgorithmException
      Returns the JDK MessageDigest instance to use for executing the hash.
      Parameters:
      algorithmName - the algorithm to use for the hash, provided by subclasses.
      Returns:
      the MessageDigest object for the specified algorithm.
      Throws:
      org.apache.shiro.crypto.UnknownAlgorithmException - if the specified algorithm name is not available.

    • hash

      protected byte[] hash(byte[] bytes) throws org.apache.shiro.crypto.UnknownAlgorithmException
      Hashes the specified byte array without a salt for a single iteration.
      Parameters:
      bytes - the bytes to hash.
      Returns:
      the hashed bytes.
      Throws:
      org.apache.shiro.crypto.UnknownAlgorithmException - if the configured algorithmName is not available.

    • hash

      protected byte[] hash(byte[] bytes, byte[] salt) throws org.apache.shiro.crypto.UnknownAlgorithmException
      Hashes the specified byte array using the given salt for a single iteration.
      Parameters:
      bytes - the bytes to hash
      salt - the salt to use for the initial hash
      Returns:
      the hashed bytes
      Throws:
      org.apache.shiro.crypto.UnknownAlgorithmException - if the configured algorithmName is not available.

    • hash

      protected byte[] hash(byte[] bytes, byte[] salt, int hashIterations) throws org.apache.shiro.crypto.UnknownAlgorithmException
      Hashes the specified byte array using the given salt for the specified number of iterations.
      Parameters:
      bytes - the bytes to hash
      salt - the salt to use for the initial hash
      hashIterations - the number of times the the bytes will be hashed (for attack resiliency).
      Returns:
      the hashed bytes.
      Throws:
      org.apache.shiro.crypto.UnknownAlgorithmException - if the algorithmName is not available.

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface org.apache.shiro.lang.util.ByteSource

    • toHex

      public String toHex()
      Returns a hex-encoded string of the underlying byte array.

      This implementation caches the resulting hex string so multiple calls to this method remain efficient. However, calling setBytes will null the cached value, forcing it to be recalculated the next time this method is called.

      Specified by:
      toHex in interface org.apache.shiro.lang.util.ByteSource
      Returns:
      a hex-encoded string of the underlying byte array.

    • toBase64

      public String toBase64()
      Returns a Base64-encoded string of the underlying byte array.

      This implementation caches the resulting Base64 string so multiple calls to this method remain efficient. However, calling setBytes will null the cached value, forcing it to be recalculated the next time this method is called.

      Specified by:
      toBase64 in interface org.apache.shiro.lang.util.ByteSource
      Returns:
      a Base64-encoded string of the underlying byte array.

    • toString

      public String toString()
      Simple implementation that merely returns toHex().
      Overrides:
      toString in class Object
      Returns:
      the toHex() value.

    • equals

      public boolean equals(Object o)
      Returns true if the specified object is a Hash and its byte array is identical to this Hash's byte array, false otherwise.
      Overrides:
      equals in class Object
      Parameters:
      o - the object (Hash) to check for equality.
      Returns:
      true if the specified object is a Hash and its byte array is identical to this Hash's byte array, false otherwise.

    • hashCode

      public int hashCode()
      Simply returns toHex().hashCode();
      Overrides:
      hashCode in class Object
      Returns:
      toHex().hashCode()