Package com.globalmentor.security

Class Hash

java.lang.Object
com.globalmentor.security.Hash
public final class Hash extends Object
The encapsulation of message digest output, providing data immutability and convenience methods for updating other message digests.
Author:
Garret Wilson
API Note:
This class provides programming safety mutability but not cryptographic safety again Byzantine attacks. In other words, this class is useful for preventing accidental modification of bytes due to a logic error, and is thus orders of magnitude safer than using a raw byte array. However it would be possible to create a back-door mutable instance by passing a rogue or buggy MessageDigest implementation to fromDigest(MessageDigest). A rogue or buggy MessageDigest implementation could also change the contents of the hash bytes via its MessageDigest.update(byte[]) method when updateMessageDigest(MessageDigest) is called.
Implementation Note:
The immutability of this class in conjunction with MessageDigests depends on all implementation of MessageDigest.digest() and similar methods to return a byte array free from other references; and depends on all implementations of MessageDigest.update(byte[]) not to change any information in the byte array passed to it.

  • Method Details

    • of

      public static Hash of(@Nonnull byte[] bytes)
      Constructs a hash from message digest bytes.
      Implementation Specification:
      A defensive copy is made of the bytes.
      Parameters:
      bytes - The bytes of a message digest.
      Returns:
      The hash encapsulation of the message digest bytes.

    • fromChecksum

      public static Hash fromChecksum(@Nonnull CharSequence checksum)
      Constructs a hash from a checksum string.
      Parameters:
      checksum - A hex checksum string for the hash bytes.
      Returns:
      The resulting hash.
      See Also:

    • fromDigest

      public static Hash fromDigest(@Nonnull MessageDigest messageDigest)
      Constructs a hash for the current contents of the message digest, equivalent to creating a Hash instance from the result of MessageDigest.digest(). The message digest is reset after this call is made.
      Parameters:
      messageDigest - The implementation of a message digest algorithm.
      Returns:
      The resulting hash.
      See Also:

    • updateMessageDigest

      public MessageDigest updateMessageDigest(@Nonnull MessageDigest messageDigest)
      Updates a digest with the bytes of this hash.
      Implementation Note:
      The immutability of this class depends on the implementations of MessageDigest.update(byte[]) not to change any information in the byte array passed to it.
      Parameters:
      messageDigest - The implementation of a message digest algorithm.
      Returns:
      The updated message digest.
      See Also:

    • getBytes

      public byte[] getBytes()
      Returns the message digest bytes. The resulting byte array is guaranteed to be free from other references.
      API Note:
      This method should only be called when the actual bytes are truly needed, because of the overhead in protecting the bytes using e.g. a defensive copy. Otherwise try to use other methods that can access the bytes internally, such as updateMessageDigest(MessageDigest).
      Implementation Specification:
      This implementation makes a defensive copy of the bytes before returning them.
      Returns:
      The message digest bytes.

    • toChecksum

      public String toChecksum()
      Computes a lowercase hex checksum string for the hash bytes.
      API Note:
      This method considers a checksum to be a string version of a message digest, as the former is often used in the context of file contents verification.
      Returns:
      The lowercase hex checksum string of the hash bytes.

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Implementation Specification:
      This implementation delegates to toChecksum().
      See Also:

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
      Implementation Specification:
      This implementation returns a hash code of the hash bytes.
      See Also:

    • equals

      public boolean equals(Object object)
      Overrides:
      equals in class Object
      Implementation Specification:
      This implementation considers another object equal if it is an instance of Hash and contains the same hash bytes.
      See Also: