2.5.4Class HashBase

Base class for each hash algorithm, specialized for overloading.

Class HashBase

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.

Overloading HashBase

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.