ROSE  0.11.145.0
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
Rose::Combinatorics::Hasher Class Referenceabstract

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

#include <roseSupport/Combinatorics.h>

Inheritance diagram for Rose::Combinatorics::Hasher:
Inheritance graph
[legend]
Collaboration diagram for Rose::Combinatorics::Hasher:
Collaboration graph
[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. More...
 
virtual const Digestdigest ()
 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. More...
 

Protected Attributes

Digest digest_
 

Member Typedef Documentation

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

Member Function Documentation

virtual void Rose::Combinatorics::Hasher::clear ( )
inlinevirtual
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 184 of file Combinatorics.h.

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

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

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

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

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

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

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

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

static std::string Rose::Combinatorics::Hasher::toString ( const Digest )
static

Convert a digest to a hexadecimal string.

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.

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.


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