Package org.apache.shiro.crypto.hash

Class AbstractCryptHash

java.lang.Object
org.apache.shiro.crypto.hash.AbstractCryptHash
All Implemented Interfaces:
Serializable, Hash, org.apache.shiro.lang.util.ByteSource
public abstract class AbstractCryptHash extends Object implements Hash, Serializable
Abstract class for hashes following the posix crypt(3) format.

These implementations must contain a salt, a salt length, can format themselves to a valid String suitable for the /etc/shadow file.

It also defines the hex and base64 output by wrapping the output of formatToCryptString().

Implementation notice: Implementations should provide a static fromString() method.

Since:
2.0
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
    Modifier and Type
    Field
    Description
    protected static final Pattern
    DELIMITER
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    AbstractCryptHash(String algorithmName, byte[] hashedData, org.apache.shiro.lang.util.ByteSource salt)
    Constructs an AbstractCryptHash using the algorithm name, hashed data and salt parameters.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected final void
    checkValid()
     
    protected abstract void
    checkValidAlgorithm()
    Algorithm-specific checks of the algorithm’s parameters.
    protected void
    checkValidSalt()
    Default check method for a valid salt.
    boolean
    equals(Object other)
    Returns true if the specified object is an AbstractCryptHash and its formatToCryptString() formatted output} is identical to this AbstractCryptHash's formatted output, false otherwise.
    abstract String
    formatToCryptString()
    This method MUST return a single-lined string which would also be recognizable by a posix /etc/passwd file.
    String
    getAlgorithmName()
    Implemented by subclasses, this specifies the KDF algorithm name to use when performing the hash.
    byte[]
    getBytes()
    Returns only the hashed data.
    org.apache.shiro.lang.util.ByteSource
    getSalt()
    Returns a salt used to compute the hash or null if no salt was used.
    abstract int
    getSaltLength()
    The length in number of bytes of the salt which is needed for this algorithm.
    int
    hashCode()
    Hashes the formatted crypt string.
    boolean
    isEmpty()
     
    String
    toBase64()
    Returns a Base64-encoded string of the underlying formatToCryptString() formatted output}.
    String
    toHex()
    Returns a hex-encoded string of the underlying formatToCryptString() formatted output}.
    String
    toString()
    Simple implementation that merely returns toHex().

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.apache.shiro.crypto.hash.Hash

    getIterations, matchesPassword

  • Field Details

    • DELIMITER

      protected static final Pattern DELIMITER

  • Constructor Details

    • AbstractCryptHash

      public AbstractCryptHash(String algorithmName, byte[] hashedData, org.apache.shiro.lang.util.ByteSource salt)
      Constructs an AbstractCryptHash using the algorithm name, hashed data and salt parameters.

      Other required parameters must be stored by the implementation.

      Parameters:
      algorithmName - internal algorithm name, e.g. 2y for bcrypt and argon2id for argon2.
      hashedData - the hashed data as a byte array. Does not include the salt or other parameters.
      salt - the salt which was used when generating the hash.
      Throws:
      IllegalArgumentException - if the salt is not the same size as getSaltLength().

  • Method Details

    • checkValid

      protected final void checkValid()

    • checkValidAlgorithm

      protected abstract void checkValidAlgorithm()
      Algorithm-specific checks of the algorithm’s parameters.

      While the salt length will be checked by default, other checks will be useful. Examples are: Argon2 checking for the memory and parallelism parameters, bcrypt checking for the cost parameters being in a valid range.

      Throws:
      IllegalArgumentException - if any of the parameters are invalid.

    • checkValidSalt

      protected void checkValidSalt()
      Default check method for a valid salt. Can be overridden, because multiple salt lengths could be valid.

      By default, this method checks if the number of bytes in the salt are equal to the int returned by getSaltLength().

      Throws:
      IllegalArgumentException - if the salt length does not match the returned value of getSaltLength().

    • getAlgorithmName

      public String getAlgorithmName()
      Implemented by subclasses, this specifies the KDF algorithm name to use when performing the hash.

      When multiple algorithm names are acceptable, then this method should return the primary algorithm name.

      Example: Bcrypt hashed can be identified by 2y and 2a. The method will return 2y for newly generated hashes by default, unless otherwise overridden.

      Specified by:
      getAlgorithmName in interface Hash
      Returns:
      the KDF algorithm name to use when performing the hash.

    • getSaltLength

      public abstract int getSaltLength()
      The length in number of bytes of the salt which is needed for this algorithm.
      Returns:
      the expected length of the salt (in bytes).

    • 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.

    • getBytes

      public byte[] getBytes()
      Returns only the hashed data. Those are of no value on their own. If you need to serialize the hash, please refer to formatToCryptString().
      Specified by:
      getBytes in interface org.apache.shiro.lang.util.ByteSource
      Returns:
      A copy of the hashed data as bytes.
      See Also:

    • 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 formatToCryptString() formatted output}.

      This implementation caches the resulting hex string so multiple calls to this method remain efficient.

      Specified by:
      toHex in interface org.apache.shiro.lang.util.ByteSource
      Returns:
      a hex-encoded string of the underlying formatToCryptString() formatted output}.

    • toBase64

      public String toBase64()
      Returns a Base64-encoded string of the underlying formatToCryptString() formatted output}.

      This implementation caches the resulting Base64 string so multiple calls to this method remain efficient.

      Specified by:
      toBase64 in interface org.apache.shiro.lang.util.ByteSource
      Returns:
      a Base64-encoded string of the underlying formatToCryptString() formatted output}.

    • formatToCryptString

      public abstract String formatToCryptString()
      This method MUST return a single-lined string which would also be recognizable by a posix /etc/passwd file.
      Returns:
      a formatted string, e.g. $2y$10$7rOjsAf2U/AKKqpMpCIn6e$tuOXyQ86tp2Tn9xv6FyXl2T0QYc3.G. for bcrypt.

    • equals

      public boolean equals(Object other)
      Returns true if the specified object is an AbstractCryptHash and its formatToCryptString() formatted output} is identical to this AbstractCryptHash's formatted output, false otherwise.
      Overrides:
      equals in class Object
      Parameters:
      other - the object (AbstractCryptHash) to check for equality.
      Returns:
      true if the specified object is a AbstractCryptHash and its formatToCryptString() formatted output} is identical to this AbstractCryptHash's formatted output, false otherwise.

    • hashCode

      public int hashCode()
      Hashes the formatted crypt string.

      Implementations should not override this method, as different algorithms produce different output formats and require different parameters.

      Overrides:
      hashCode in class Object
      Returns:
      a hashcode from the formatted output.

    • toString

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