Package com.globalmentor.security

Class MessageDigests.Algorithm

java.lang.Object
com.globalmentor.security.MessageDigests.Algorithm
All Implemented Interfaces:
Named<String>
Enclosing class:
MessageDigests
public static final class MessageDigests.Algorithm extends Object implements Named<String>
Encapsulation of a standard MessageDigest algorithm, which may or may not be implemented by any particular Java platform.
Author:
Garret Wilson
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    checksum(byte input)
    Computes a lowercase hex checksum string using this algorithm for the given input byte.
    String
    checksum(byte[] input)
    Computes a lowercase hex checksum string using this algorithm for the given input bytes.
    String
    checksum(byte[] input, int offset, int length)
    Computes a lowercase hex checksum string using this algorithm for the given input bytes.
    String
    checksum(char[] characters)
    Computes a lowercase hex checksum string using this algorithm for the given characters using the UTF-8 charset.
    String
    checksum(InputStream inputStream)
    Computes a lowercase hex checksum string using this algorithm for the contents of the given input stream.
    String
    checksum(CharSequence charSequence)
    Computes a lowercase hex checksum string using this algorithm for the given character sequence using the UTF-8 charset.
    String
    checksum(ByteBuffer byteBuffer)
    Computes a lowercase hex checksum string using this algorithm for the given input byte buffer.
    String
    checksum(Path file)
    Computes a lowercase hex checksum string using this algorithm for the contents of the given file.
    byte[]
    digest(byte b)
    Computes a digest using this algorithm for the given byte.
    byte[]
    digest(byte[] bytes)
    Computes a digest using this algorithm for the specified array of bytes.
    byte[]
    digest(byte[] bytes, int offset, int length)
    Computes a digest using this algorithm for the specified array of bytes, starting at the specified offset.
    byte[]
    digest(char[] characters)
    Computes a digest using this algorithm for the given characters using the UTF-8 charset.
    byte[]
    digest(InputStream inputStream)
    Computes a digest using this algorithm for the contents of the given input stream.
    byte[]
    digest(CharSequence... charSequences)
    Computes a digest using this algorithm for the given character sequences using the UTF-8 charset.
    byte[]
    digest(ByteBuffer byteBuffer)
    Computes a digest for the specified byte buffer.
    byte[]
    digest(Charset charset, char[] characters)
    Computes a digest using this algorithm for the given characters, using the given charset.
    byte[]
    digest(Charset charset, CharSequence... charSequences)
    Computes a digest using this algorithm for the given character sequences, using the given charset.
    byte[]
    digest(Path file)
    Computes a digest using this algorithm for the contents of the given file.
    Hash
    emptyHash()
    Returns an "empty" hash using this algorithm.
    boolean
    equals(Object object)
    MessageDigest
    getInstance()
    Deprecated.
    in favor of newMessageDigest(), which has a clearer and less misleading name.
    String
    getName()
     
    Hash
    hash(byte b)
    Computes a hash using this algorithm for the given byte.
    Hash
    hash(byte[] bytes)
    Computes a hash using this algorithm for the specified array of bytes.
    Hash
    hash(byte[] bytes, int offset, int length)
    Computes a hash using this algorithm for the specified array of bytes, starting at the specified offset.
    Hash
    hash(char[] characters)
    Computes a hash using this algorithm for the given characters using the UTF-8 charset.
    Hash
    hash(Hash... hashes)
    Computes a hash using this algorithm for the given hashes.
    Hash
    hash(InputStream inputStream)
    Computes a hash using this algorithm for the contents of the given input stream.
    Hash
    hash(CharSequence... charSequences)
    Computes a hash using this algorithm for the given character sequences using the UTF-8 charset.
    Hash
    hash(ByteBuffer byteBuffer)
    Computes a hash using this algorithm for the specified byte buffer.
    Hash
    hash(Charset charset, char[] characters)
    Computes a hash using this algorithm for the given characters, using the given charset.
    Hash
    hash(Charset charset, CharSequence... charSequences)
    Computes a hash using this algorithm for the given character sequences, using the given charset.
    Hash
    hash(Path file)
    Computes a hash using this algorithm for the contents of the given file.
    int
    hashCode()
    boolean
    isEmpty(Hash hash)
    Determines whether the given hash is "empty", that is, equivalent to hashing no content
    MessageDigest
    newMessageDigest()
    Creates a new message digest instance for this algorithm.
    String
    toString()

    Methods inherited from class java.lang.Object

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

  • Method Details

    • getName

      public String getName()
      Specified by:
      getName in interface Named<String>
      Returns:
      The name of the object, or null if the object has no name.

    • newMessageDigest

      public MessageDigest newMessageDigest()
      Creates a new message digest instance for this algorithm.
      API Note:
      This method differs from MessageDigest.getInstance(String) in that it throws an unchecked exception if the algorithm is not supported.
      Implementation Specification:
      This method delegates to MessageDigest.getInstance(String).
      Returns:
      An instance of a message digest for this algorithm.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • getInstance

      @Deprecated public MessageDigest getInstance()
      Deprecated.
      in favor of newMessageDigest(), which has a clearer and less misleading name.
      Creates a new message digest instance for this algorithm.
      Returns:
      An instance of a message digest for this algorithm.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • digest

      public byte[] digest(@Nonnull byte b)
      Computes a digest using this algorithm for the given byte.
      Parameters:
      b - The byte to digest.
      Returns:
      The array of bytes for the resulting hash value.

    • digest

      public byte[] digest(@Nonnull byte[] bytes, int offset, int length)
      Computes a digest using this algorithm for the specified array of bytes, starting at the specified offset.
      Parameters:
      bytes - The array of bytes to digest.
      offset - The offset to start from in the array of bytes.
      length - The number of bytes to use, starting at the offset.
      Returns:
      The array of bytes for the resulting hash value.

    • digest

      public byte[] digest(@Nonnull byte[] bytes)
      Computes a digest using this algorithm for the specified array of bytes.
      Implementation Specification:
      This implementation delegates to MessageDigest.digest(byte[]).
      Parameters:
      bytes - The array of bytes to digest.
      Returns:
      The array of bytes for the resulting hash value.

    • digest

      public byte[] digest(@Nonnull ByteBuffer byteBuffer)
      Computes a digest for the specified byte buffer.
      Parameters:
      byteBuffer - The byte buffer containing the bytes to digest.
      Returns:
      The array of bytes for the resulting hash value.

    • digest

      public byte[] digest(@Nonnull CharSequence... charSequences)
      Computes a digest using this algorithm for the given character sequences using the UTF-8 charset.
      Implementation Specification:
      This convenience method delegates to MessageDigests.digest(MessageDigest, CharSequence...).
      Parameters:
      charSequences - The character sequences to digest.
      Returns:
      The array of bytes for the resulting hash value.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • digest

      public byte[] digest(@Nonnull Charset charset, @Nonnull CharSequence... charSequences)
      Computes a digest using this algorithm for the given character sequences, using the given charset.
      Implementation Specification:
      This convenience method delegates to MessageDigests.digest(MessageDigest, Charset, CharSequence...).
      Parameters:
      charset - The charset to use when converting characters to bytes.
      charSequences - The character sequences to digest.
      Returns:
      The array of bytes for the resulting hash value.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • digest

      public byte[] digest(@Nonnull char[] characters)
      Computes a digest using this algorithm for the given characters using the UTF-8 charset.
      Implementation Specification:
      This convenience method delegates to MessageDigests.digest(MessageDigest, char[]).
      Parameters:
      characters - The characters to digest.
      Returns:
      The array of bytes for the resulting hash value.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • digest

      public byte[] digest(@Nonnull Charset charset, @Nonnull char[] characters)
      Computes a digest using this algorithm for the given characters, using the given charset.
      Implementation Specification:
      This convenience method delegates to MessageDigests.digest(MessageDigest, Charset, char[]).
      Parameters:
      charset - The charset to use when converting characters to bytes.
      characters - The arrays of characters to digest.
      Returns:
      The array of bytes for the resulting hash value.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • digest

      public byte[] digest(@Nonnull InputStream inputStream) throws IOException
      Computes a digest using this algorithm for the contents of the given input stream. All the remaining contents of the input stream are consumed.
      Implementation Specification:
      This convenience method delegates to MessageDigests.digest(MessageDigest, InputStream).
      Parameters:
      inputStream - The input stream on which to perform a digest.
      Returns:
      The array of bytes for the resulting hash value.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.
      IOException - if there is an I/O exception reading from the input stream.

    • digest

      public byte[] digest(@Nonnull Path file) throws IOException
      Computes a digest using this algorithm for the contents of the given file.
      Implementation Specification:
      This convenience method delegates to MessageDigests.digest(MessageDigest, Path).
      Parameters:
      file - The path to the file on which to perform a digest.
      Returns:
      The array of bytes for the resulting hash value.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.
      IOException - if there is an I/O exception reading from the file.

    • emptyHash

      public Hash emptyHash()
      Returns an "empty" hash using this algorithm. This method is equivalent to creating a message digest and not adding any content, such as calling hash(CharSequence...) with an empty array of strings.
      API Note:
      This method is preferred over calling another hash method and providing no content, not only because this method is more semantically appropriate, but also because this implementation is likely much more efficient.
      Implementation Specification:
      This method maintains a lazy cache of empty hashes for algorithms. Although these caches are never released, very few message digest algorithms are common (and typically only one or two used in a single application), wasted space is nominal.
      Returns:
      A hash for a message digest from this algorithm that has not processed any content..
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • isEmpty

      public boolean isEmpty(@Nonnull Hash hash)
      Determines whether the given hash is "empty", that is, equivalent to hashing no content
      Parameters:
      hash - The hash to check.
      Returns:
      Whether the given hash is equal to a hash created from a new message digest which has hashed no content.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.
      See Also:

    • hash

      public Hash hash(@Nonnull byte b)
      Computes a hash using this algorithm for the given byte.
      Parameters:
      b - The byte to digest.
      Returns:
      The resulting hash.

    • hash

      public Hash hash(@Nonnull byte[] bytes)
      Computes a hash using this algorithm for the specified array of bytes.
      Parameters:
      bytes - The array of bytes to digest.
      Returns:
      The array of bytes for the resulting hash value.

    • hash

      public Hash hash(@Nonnull byte[] bytes, int offset, int length)
      Computes a hash using this algorithm for the specified array of bytes, starting at the specified offset.
      Parameters:
      bytes - The array of bytes to digest.
      offset - The offset to start from in the array of bytes.
      length - The number of bytes to use, starting at the offset.
      Returns:
      The resulting hash.

    • hash

      public Hash hash(@Nonnull ByteBuffer byteBuffer)
      Computes a hash using this algorithm for the specified byte buffer.
      Parameters:
      byteBuffer - The byte buffer containing the bytes to digest.
      Returns:
      The resulting hash.

    • hash

      public Hash hash(@Nonnull CharSequence... charSequences)
      Computes a hash using this algorithm for the given character sequences using the UTF-8 charset.
      Implementation Specification:
      This convenience method delegates to MessageDigests.hash(MessageDigest, CharSequence...).
      Parameters:
      charSequences - The character sequences to digest.
      Returns:
      The resulting hash.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • hash

      public Hash hash(@Nonnull Charset charset, @Nonnull CharSequence... charSequences)
      Computes a hash using this algorithm for the given character sequences, using the given charset.
      Implementation Specification:
      This convenience method delegates to MessageDigests.hash(MessageDigest, Charset, CharSequence...).
      Parameters:
      charset - The charset to use when converting characters to bytes.
      charSequences - The character sequences to digest.
      Returns:
      The resulting hash.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • hash

      public Hash hash(@Nonnull char[] characters)
      Computes a hash using this algorithm for the given characters using the UTF-8 charset.
      Implementation Specification:
      This convenience method delegates to MessageDigests.hash(MessageDigest, char[]).
      Parameters:
      characters - The characters to digest.
      Returns:
      The resulting hash.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • hash

      public Hash hash(@Nonnull Charset charset, @Nonnull char[] characters)
      Computes a hash using this algorithm for the given characters, using the given charset.
      Implementation Specification:
      This convenience method delegates to MessageDigests.hash(MessageDigest, Charset, char[]).
      Parameters:
      charset - The charset to use when converting characters to bytes.
      characters - The arrays of characters to digest.
      Returns:
      The resulting hash.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • hash

      public Hash hash(@Nonnull Hash... hashes)
      Computes a hash using this algorithm for the given hashes.
      Implementation Specification:
      This convenience method delegates to MessageDigests.hash(MessageDigest, Hash...).
      Parameters:
      hashes - The hashes to digest.
      Returns:
      The resulting hash.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • hash

      public Hash hash(@Nonnull InputStream inputStream) throws IOException
      Computes a hash using this algorithm for the contents of the given input stream. All the remaining contents of the input stream are consumed.
      Implementation Specification:
      This convenience method delegates to MessageDigests.hash(MessageDigest, InputStream).
      Parameters:
      inputStream - The input stream on which to perform a digest.
      Returns:
      The resulting hash.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.
      IOException - if there is an I/O exception reading from the input stream.

    • hash

      public Hash hash(@Nonnull Path file) throws IOException
      Computes a hash using this algorithm for the contents of the given file.
      Implementation Specification:
      This convenience method delegates to MessageDigests.hash(MessageDigest, Path).
      Parameters:
      file - The path to the file on which to perform a digest.
      Returns:
      The resulting hash.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.
      IOException - if there is an I/O exception reading from the file.

    • checksum

      public String checksum(byte input)
      Computes a lowercase hex checksum string using this algorithm for the given input byte.
      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.
      Implementation Specification:
      This implementation delegates to MessageDigests.checksum(MessageDigest, byte).
      Parameters:
      input - The byte for which a digest and then a checksum string should be created.
      Returns:
      The lowercase hex checksum string of the resulting hash value.

    • checksum

      public String checksum(@Nonnull byte[] input)
      Computes a lowercase hex checksum string using this algorithm for the given input 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.
      Implementation Specification:
      This implementation delegates to MessageDigests.checksum(MessageDigest, byte[]).
      Parameters:
      input - The sequence of bytes for which a digest and then a checksum string should be created.
      Returns:
      The lowercase hex checksum string of the resulting hash value.
      See Also:

    • checksum

      public String checksum(@Nonnull byte[] input, int offset, int length)
      Computes a lowercase hex checksum string using this algorithm for the given input 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.
      Implementation Specification:
      This implementation delegates to MessageDigests.checksum(MessageDigest, byte[], int, int).
      Parameters:
      input - The array of bytes for which a digest and then a checksum string should be created.
      offset - The offset to start from in the array of bytes.
      length - The number of bytes to use, starting at the offset.
      Returns:
      The lowercase hex checksum string of the resulting hash value.

    • checksum

      public String checksum(@Nonnull ByteBuffer byteBuffer)
      Computes a lowercase hex checksum string using this algorithm for the given input byte buffer.
      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.
      Implementation Specification:
      This implementation delegates to MessageDigests.checksum(MessageDigest, ByteBuffer).
      Parameters:
      byteBuffer - The byte buffer containing the bytes for which a digest and then a checksum string should be created.
      Returns:
      The lowercase hex checksum string of the resulting hash value.

    • checksum

      public String checksum(@Nonnull CharSequence charSequence)
      Computes a lowercase hex checksum string using this algorithm for the given character sequence using the UTF-8 charset.
      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.
      Implementation Specification:
      This implementation delegates to MessageDigests.checksum(MessageDigest, CharSequence).
      Parameters:
      charSequence - The character sequence for which a checksum should be created.
      Returns:
      The lowercase hex checksum string of the resulting hash value.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.

    • checksum

      public String checksum(@Nonnull char[] characters)
      Computes a lowercase hex checksum string using this algorithm for the given characters using the UTF-8 charset.
      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.
      Implementation Specification:
      This implementation delegates to MessageDigests.checksum(MessageDigest, char[]).
      Parameters:
      characters - The characters for which a checksum should be created.
      Returns:
      The lowercase hex checksum string of the resulting hash value.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.
      See Also:

    • checksum

      public String checksum(@Nonnull InputStream inputStream) throws IOException
      Computes a lowercase hex checksum string using this algorithm for the contents of the given input stream. All the remaining contents of the input stream are consumed.
      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.
      Implementation Specification:
      This implementation delegates to MessageDigests.checksum(MessageDigest, InputStream).
      Parameters:
      inputStream - The input stream for which a checksum should be created.
      Returns:
      The lowercase hex checksum string of the resulting hash value.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.
      IOException - if there is an I/O exception reading from the input stream.
      See Also:

    • checksum

      public String checksum(@Nonnull Path file) throws IOException
      Computes a lowercase hex checksum string using this algorithm for the contents of the given file.
      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.
      Implementation Specification:
      This implementation delegates to MessageDigests.checksum(MessageDigest, Path).
      Parameters:
      file - The path to the file for which a checksum should be created.
      Returns:
      The lowercase hex checksum string of the resulting hash value.
      Throws:
      RuntimeException - if no Provider supports a MessageDigestSpi implementation for this algorithm.
      IOException - if there is an I/O exception reading from the file.
      See Also:

    • hashCode

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

    • equals

      public boolean equals(@Nonnull Object object)
      Overrides:
      equals in class Object
      Implementation Specification:
      This implementation considers two algorithms equal if they have the same name.
      See Also:

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Implementation Specification:
      This version return the algorithm name.
      See Also: