Description

Hash interface.

This class defines the API for hash functions. A hash function takes an arbitrary size message as input and returns a fixed size digest. The subclasses implement specific hash functions, the digests of which are different sizes. For instance, a SHA1 digest is always 20 bytes, and a SHA512 digest is always 64 bytes.

The digest can be computed incrementally by inserting the message in parts using various insert functions. Once the message has been fully inserted, the digest can be obtained with the digest function. The digest can be retrieved repeatedly, but no additional message parts can be added once a digest is retrieved (doing so will result in an Exception being thrown). However, the hasher can be reset to an initial state by calling clear, after which a new message can be inserted. Subclasses that return hashes that are 8 bytes or narrower sometimes have an additional method that returns the digest as an unsigned integer (but the digest method must always be present).

Hasher objects are copyable. The new hasher starts out in the same state as the original hasher, but then they can diverge from one another. For instance, if you have a multi-part message and want an intermediate hash, the easiest way to do that is to insert some message parts into a hasher, then make a copy to obtain its digest, then continue inserting message parts into the original hasher (the copy cannot accept more parts since we called its digest method). Obtaining intermediate hashes this way is usually faster than re-hashing.

The API contains a few functions for printing hashes. There's a toString function that can return the digest as a hexadecimal string and a static version that that converts a given digest to a string. Also, using a hasher in an std::ostream output operator is the same as obtaining the hasher's digest, formatting it, and sending the string to the stream. All these functions (except the static toString) call digest under the covers, thus finalizing the hasher.

New hash functions can be created very easily by subclassing Hasher and defining an append method. Often, this is all that's necessary. Other commonly overridden functions are the constructor, clear, and digest. The subclasses generally have names beginning with the string "Hasher" so they can be found easily in alphabetical class listings. For instance, see the classes and typedefs in the Rose::Combinatorics namespace.

If a hasher uses an external library (like libgcrypt) then it should be designed in such a way that the code that uses the hash compiles, but throws an exception. The Exception class is intended for this purpose, as well as all other situations where hashing fails.

Definition at line 119 of file Combinatorics.h.

#include <Combinatorics.h>

Inheritance diagram for Rose::Combinatorics::Hasher:

[legend]

Collaboration diagram for Rose::Combinatorics::Hasher:

[legend]

Classes
class	Exception
	Exceptions for hashing. More...

class	HasherFactory
	HasherFactory is a singleton that creates and returns Hashers by name. More...

class	HasherMaker
	Templated to create any Hasher and register it with HasherFactory. More...

class	IHasherMaker
	Common subclass all the classes that construct Hashers (for the HasherFactory) More...

Public Types
typedef std::vector< uint8_t >	Digest
	The digest of the input message. More...

Public Member Functions
virtual void	clear ()
	Reset the hasher to its initial state.

virtual const Digest &	digest ()
	Return the digest. More...

virtual void	append (const uint8_t *message, size_t messageSize)=0
	Insert data into the digest. More...

std::string	toString ()
	String representation of the digest. More...

void	print (std::ostream &)
	Print a hash to a stream. More...


void	insert (const std::string &x)
	Insert data into the digest. More...

void	insert (uint64_t x)
	Insert data into the digest. More...

void	insert (const uint8_t *x, size_t size)
	Insert data into the digest. More...

void	insert (const std::vector< uint8_t > &v)
	Insert data into the digest. More...

void	insert (std::istream &stream)
	Insert data into the digest. More...

Static Public Member Functions
static std::string	toString (const Digest &)
	Convert a digest to a hexadecimal string.

Protected Attributes
Digest	digest_

Member Typedef Documentation

◆ Digest

typedef std::vector<uint8_t> Rose::Combinatorics::Hasher::Digest

The digest of the input message.

Since different hash functions have different sized digests, the digest is represented most generically as a vector of bytes.

Definition at line 125 of file Combinatorics.h.

Member Function Documentation

◆ digest()

virtual const Digest& Rose::Combinatorics::Hasher::digest ( )

inlinevirtual

Return the digest.

Finalizes the hash function and returns the digest for all the input. Additional input should not be inserted after this function is called since some hash functions don't support this.

Reimplemented in Rose::Combinatorics::HasherSha256Builtin, Rose::Combinatorics::HasherFnv, and Rose::Combinatorics::HasherGcrypt< hashAlgorithmId >.

Definition at line 148 of file Combinatorics.h.

Referenced by Rose::Combinatorics::HasherGcrypt< hashAlgorithmId >::digest().

Here is the caller graph for this function: