Class HashBase[in hash]

Base class for each hash algorithm, specialized for overloading.

class HashBase

more...

Summary

class HashBase

Base class for each hash algorithm, specialized for overloading.

The HashBase class provides a set of shared interfaces that are syntactically equivalent for each specialized hash.

Hashes are generated by creating an instance of a specialized class and putting data into it. When the result is requested, a hash is finalized, which means that no more data can be added; any attempts to do so will raise an exception.

Basic usage example:

    crc = CRC32()
    crc.update("abc")
    > crc // prints "352441c2"

Note: Instantiating HashBase directly and calling any method will raise an error.

To easily implement other hash algorithms in native falcon code, HashBase can be overloaded. For simplicity, only 2 methods have to be overloaded, and 2 new methods have to be added:

    class MyHash from HashBase
        state = nil // internal state
        outp = nil
        function bytes(): return 12       // must be overloaded and return a constant integer > 0
        function toMemBuf(): return self.outp  // must be overloaded and return a MemBuf with wordSize 1 and length equal to bytes()
        function process(buf)             // must be declared, as it is invoked by the module on update() calls
            // *mangle MemBuf and update state*
        end
        function finalize()               // must be declared, as it is invoked by the module to produce the actual digest
            // *transform state and assign result MemBuf(1, bytes()) to outp*
        end
    end

How this works:

• bytes() is internally invoked by bits() (once, the returned integer is cached by the module)
• process() is invoked by update() and updateInt(), beeing passed a MemBuf with word size 1
• toMemBuf() is invoked by toString() and toInt()
• finalize() is called ONCE before toMemBuf() and is intended to do process remaining buffers, and produce the actual digest. Does not have to be called manually.

Note: You are strongly advised NOT to overload any other methods except the four above, unless you REALLY know what you're doing.

Advantages of doing it this way:

• It is not necessary to implement update() in native falcon code.
• All value endian conversions, type mangling, and error checking is done by the module, so focus can be set on the algorithm itself.
• The values returned by bytes(), toMemBuf() and toInt() are cached by the module, means less calls, less time.
• The module ensures that finalize() is called only once, no explicit checking required.

Methods

bits()

Returns the bit length of the hash result.

HashBase.bits( )

The bit length of a hash function is a rough indicator for its safety - long hashes take exponentially longer to find a collision, or to break them.

Note: This method is a shortcut for bytes() * 8

bytes()

Returns the byte length of the hash result.

HashBase.bytes( )

The amount of returned bytes is specific for each hash algorithm.

isFinalized()

Checks if a hash is finalized.

HashBase.isFinalized( )

When a result from a hash is obtained, the hash will be finalized, making it impossible to add additional data. This method can be used if the finalization state of a hash is unknown.

reset()

Clears the hash state

HashBase.reset( )

Clears a hash and sets it back to the state when it was created.

toInt()

Returns the result as an Integer value.

HashBase.toInt( )

Converts up to 8 bytes from the actual hash result to an integer value and returns it, depending on its length. If the hash is longer, the 8 lowest bytes are taken. (MemBuf[0] to MemBuf[7])

Note: Calling this method will finalize the hash.

Note: The returned int is in native endianness.

toMemBuf()

Returns the hash result in a MemBuf.

HashBase.toMemBuf( )

Note: Calling this method will finalize the hash.

toString()

Returns the hash result as a hexadecimal string.

HashBase.toString( )

Note: Calling this method will finalize the hash.

update()

Feeds data into the hash function.

HashBase.update( )

This method accepts an arbitrary amount of parameters, each treated differently:

• Strings and MemBufs are hashed with respect to their byte count (1, 2, or 4 byte strings) and endianness.
• Lists and Arrays are traversed, each item beeing hashed.
• Dictionaries: only the values are hashed (the keys not). Note that the order in which the values are processed depends on the keys!
• Nil as parameter is always skipped, even if contained in a Sequence.
• If a parameter provides a toMemBuf method, it is called and the returned result hashed (does not have to be a MemBuf, actually). This allows direct hashing of finalized hashes.
• In all other cases, the parameter is converted to a string.
• To hash integer values, use updateInt(), as it respects their memory layout. If put into update(), they will be hashed as a string!
• All parameters are hashed in the order they are passed.
• Sequences can be nested.

Note: Multiple calls can be chained, e.g. hash.update(x).update(y).update(z)

updateInt()

Hashes an integer of a specified byte length.

HashBase.updateInt( num, bytes )

This method can be used to avoid creating a MemBuf to hash integer values. It supports 1 up to 8 bytes (uint64).

All integers are internally converted to little-endian. Floating-point numbers are automatically converted to Integers, all other types raise an error.

Note: Multiple calls can be chained, e.g. hash.updateInt(x).updateInt(y).updateInt(z)