Package com.globalmentor.security
Class Hash
java.lang.Object
com.globalmentor.security.Hash
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 tofromDigest(MessageDigest)
. A rogue or buggyMessageDigest
implementation could also change the contents of the hash bytes via itsMessageDigest.update(byte[])
method whenupdateMessageDigest(MessageDigest)
is called. - Implementation Note:
- The immutability of this class in conjunction with
MessageDigests
depends on all implementation ofMessageDigest.digest()
and similar methods to return a byte array free from other references; and depends on all implementations ofMessageDigest.update(byte[])
not to change any information in the byte array passed to it.
-
Method Summary
Modifier and TypeMethodDescriptionboolean
static Hash
fromChecksum
(CharSequence checksum) Constructs a hash from a checksum string.static Hash
fromDigest
(MessageDigest messageDigest) Constructs a hash for the current contents of the message digest, equivalent to creating aHash
instance from the result ofMessageDigest.digest()
.byte[]
getBytes()
Returns the message digest bytes.int
hashCode()
static Hash
of
(byte[] bytes) Constructs a hash from message digest bytes.Computes a lowercase hex checksum string for the hash bytes.toString()
updateMessageDigest
(MessageDigest messageDigest) Updates a digest with the bytes of this hash.
-
Method Details
-
of
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
Constructs a hash from a checksum string.- Parameters:
checksum
- A hex checksum string for the hash bytes.- Returns:
- The resulting hash.
- See Also:
-
fromDigest
Constructs a hash for the current contents of the message digest, equivalent to creating aHash
instance from the result ofMessageDigest.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
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
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
- Overrides:
toString
in classObject
- Implementation Specification:
- This implementation delegates to
toChecksum()
. - See Also:
-
hashCode
public int hashCode() -
equals
-