Rose::Combinatorics::Hasher Class Reference

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 173 of file Combinatorics.h.

#include <roseSupport/Combinatorics.h>

Inheritance diagram for Rose::Combinatorics::Hasher:

Collaboration diagram for Rose::Combinatorics::Hasher:

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.

Public Member Functions
virtual void	clear ()
	Reset the hasher to its initial state.
virtual const Digest &	digest ()
	Return the digest.
virtual void	append (const uint8_t *message, size_t messageSize)=0
	Insert data into the digest.
std::string	toString ()
	String representation of the digest.
void	print (std::ostream &)
	Print a hash to a stream.
void	insert (const std::string &x)
	Insert data into the digest.
void	insert (uint64_t x)
	Insert data into the digest.
void	insert (const uint8_t *x, size_t size)
	Insert data into the digest.
void	insert (const std::vector< uint8_t > &v)
	Insert data into the digest.
void	insert (std::istream &stream)
	Insert data into the digest.
uint64_t	make64Bits ()
	Returns the hash as a 64 bit int.
uint64_t	make64Bits (const Digest &)
	Returns the hash as a 64 bit int.

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 179 of file Combinatorics.h.

Constructor & Destructor Documentation

~Hasher()

virtual Rose::Combinatorics::Hasher::~Hasher ( )

inlinevirtual

Definition at line 193 of file Combinatorics.h.

Member Function Documentation

clear()

virtual void Rose::Combinatorics::Hasher::clear ( )

inlinevirtual

Reset the hasher to its initial state.

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

Definition at line 196 of file Combinatorics.h.

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

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::HasherGcrypt< hashAlgorithmId >, Rose::Combinatorics::HasherFnv, and Rose::Combinatorics::HasherSha256Builtin.

Definition at line 202 of file Combinatorics.h.

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

insert() [1/5]

void Rose::Combinatorics::Hasher::insert ( const std::string &  x )

inline

Insert data into the digest.

This method inserts data into a digest. Data can only be inserted if the user has not called digest yet.

Definition at line 209 of file Combinatorics.h.

Referenced by Rose::BinaryAnalysis::InstructionSemantics::NullSemantics::SValue::hash().

insert() [2/5]

void Rose::Combinatorics::Hasher::insert ( uint64_t  x )

inline

Insert data into the digest.

This method inserts data into a digest. Data can only be inserted if the user has not called digest yet.

Definition at line 210 of file Combinatorics.h.

insert() [3/5]

void Rose::Combinatorics::Hasher::insert ( const uint8_t *  x, size_t  size  )

inline

Insert data into the digest.

This method inserts data into a digest. Data can only be inserted if the user has not called digest yet.

Definition at line 211 of file Combinatorics.h.

insert() [4/5]

void Rose::Combinatorics::Hasher::insert ( const std::vector< uint8_t > &  v )

inline

Insert data into the digest.

This method inserts data into a digest. Data can only be inserted if the user has not called digest yet.

Definition at line 212 of file Combinatorics.h.

insert() [5/5]

void Rose::Combinatorics::Hasher::insert ( std::istream &  stream )

inline

Insert data into the digest.

This method inserts data into a digest. Data can only be inserted if the user has not called digest yet.

Definition at line 213 of file Combinatorics.h.

append()

virtual void Rose::Combinatorics::Hasher::append ( const uint8_t *  message, size_t  messageSize  )

pure virtual

Insert data into the digest.

This is the lowest level method of inserting new message content into the digest. This can be called as often as desired, building a digest incrementally.

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

toString()

std::string Rose::Combinatorics::Hasher::toString

(

)

String representation of the digest.

This works by first calling digest, which finalizes the hasher and thus later calls to insert will not be permitted unless the hasher is first reset.

make64Bits() [1/2]

uint64_t Rose::Combinatorics::Hasher::make64Bits

(

)

Returns the hash as a 64 bit int.

The return value is computed by a sequence of shift and xor operations across all bytes of the digest. If the digest is eight or fewer bytes, then this degenerates to the uint64_t interpretation of the big-endian digest

make64Bits() [2/2]

uint64_t Rose::Combinatorics::Hasher::make64Bits

(

const Digest &

)

Returns the hash as a 64 bit int.

The return value is computed by a sequence of shift and xor operations across all bytes of the digest. If the digest is eight or fewer bytes, then this degenerates to the uint64_t interpretation of the big-endian digest

print()

void Rose::Combinatorics::Hasher::print

(

std::ostream &

)

Print a hash to a stream.

This is a wrapper that calls the digest function to finalize the hash, converts the digest to a hexadecimal string, and sends it to the stream.

Member Data Documentation

digest_

Digest Rose::Combinatorics::Hasher::digest_

protected

Definition at line 190 of file Combinatorics.h.

---

The documentation for this class was generated from the following file:

• Combinatorics.h