+Hash functions
+==============
+A hash function is an algorithm to map an arbitrary long message (in the form
+of a bit string) to a fixed length message digest or hash value.
+The hash function aims to be collision free, which means that it is not
+practicable to find two messages with the same hash value (although this
+collision must exist). Also it should not be practicable to construct a
+message which maps to a given hash value.
+
+List of available hash functions
+--------------------------------
+The following hash functions are currently implemented:
+
+* Blake
+* BlueMidnightWish
+* CubeHash
+* Echo
+* Grøstl
+* Keccak
+* MD5
+* SHA-256
+* SHA-1
+* Shabal
+* Skein
+
+High frequent parameters
+------------------------
++-----------------+------------------------------------------------------------+
+| block size | 512 bits |
++-----------------+------------------------------------------------------------+
+| hash value size | 128 bits, 160 bits, 224 bits, 256 bits, 384 bits, 512 bits |
++-----------------+------------------------------------------------------------+
+
+Parts of a hash function
+------------------------
+* initialization function
+* compression algorithm
+* finalization function
+
+hash function API
+-----------------
+The API is not always consistent due to the fact that we tried to optimize the
+code for size (flash, heap and stack) and speed (runtime of the different
+components).
+
+Generally the API of the implemented block ciphers consists of:
+
++--------------+--------------------------------------------------------------+
+| \*_init | function, which implements the initialization of the context |
++--------------+--------------------------------------------------------------+
+| \*_nextBlock | function, which implements the compression algorithm |
++--------------+--------------------------------------------------------------+
+| \*_lastBlock | function, which implements the padding algorithm |
++--------------+--------------------------------------------------------------+
+| \*_ctx2hash | function, which turns a context into an actual hash value |
++--------------+--------------------------------------------------------------+
+| \*_ctx_t | context type, which can contains the state of a hashing |
+| | process |
++--------------+--------------------------------------------------------------+
+
+``*_init`` function
+~~~~~~~~~~~~~~~~~~~
+The ``*_init`` function generally takes a pointer to the context as parameter.
+This function initializes the context with algorithm specific values.
+
+``*_nextBlock`` function
+~~~~~~~~~~~~~~~~~~~~~~~~
+The ``*_nextBlock`` function is the core of each hash function. It updates the
+hash state with a given message block. So this function uses a context pointer
+and a message pointer as parameters. The size of a message block is fixed for
+each hash function (mostly 512 bit). For the last block of a messages which may
+be smaller than the blocksize you have to use the ``*_lastBlock`` function
+described below.
+
+``*_lastBlock`` function
+~~~~~~~~~~~~~~~~~~~~~~~~
+The ``*_lastBlock`` function finalizes the context with the last bits of a
+message. Since the last block is not required to have the blocksize you have
+to specify the length of the last block (normally in bits). This function
+performs the padding and final processing.
+
+``*_ctx2hash`` function
+~~~~~~~~~~~~~~~~~~~~~~~
+The ``*_ctx2hash`` function turns a given hash context into an actual hash
+value. If multiple sized hash value may be created from a context it is
+necessary to give the the size of the hash value as parameter.
+
+
+Hash function abstraction layer (HFAL)
+======================================
+The HashFunctionAbstractionLayer (BCAL) is an abstraction layer which allows
+usage of all implemented hash functions in a simple way. It abstracts specific
+function details and is suitable for implementations which want to be flexible
+in the choosing of specific hash functions. Another important aspect is that
+this abstraction layer enables the implementation of hash function operating
+modes independently from concrete hash function. It is very simple to use and
+reassembles the API used to implement individual hash functions.
+
+The main component is a hash function descriptor which contains the details of
+the individual hash functions.
+
+Parts of HFAL
+-------------
+The HFAL is split up in different parts:
+
+* HFAL declaration for HFAL descriptors
+* algorithm specific definitions of HFAL descriptors
+* HFAL basic context type
+* HFAL basic functions
+
+HFAL declaration for HFAL descriptors
+-------------------------------------
+The HFAL descriptor is a structure which is usually placed in FLASH or ROM since
+modification is unnecessary. It contains all information required to use the
+according hash function.
+
+::
+
+ typedef struct {
+ uint8_t type; /* 2 == hashfunction */
+ uint8_t flags;
+ PGM_P name;
+ uint16_t ctxsize_B;
+ uint16_t blocksize_b;
+ uint16_t hashsize_b;
+ hf_init_fpt init;
+ hf_nextBlock_fpt nextBlock;
+ hf_lastBlock_fpt lastBlock;
+ hf_ctx2hash_fpt ctx2hash;
+ hf_free_fpt free;
+ hf_mem_fpt mem;
+ } hfdesc_t; /* hashfunction descriptor type */
+
++-------------+----------------------------------------------------------------+
+| type | should be set to ``2`` to indicate that this descriptor is for |
+| | a hash function. |
++-------------+----------------------------------------------------------------+
+| flags | currently unused, should be set to zero. |
++-------------+----------------------------------------------------------------+
+| name | is a pointer to a zero terminated ASCII string giving the name |
+| | of the implemented primitive. On targets with |
+| | Harvard-architecture the string resides in code memory |
+| | (FLASH, ROM, ...). |
++-------------+----------------------------------------------------------------+
+| ctxsize_B | is the number of bytes which should be allocated for the |
+| | context variable. |
++-------------+----------------------------------------------------------------+
+| blocksize_b | is the number of bits on which are hashed by one iteration of |
+| | the nextBlock function. |
++-------------+----------------------------------------------------------------+
+| hashsize_b | is the number of bits on which are output as final hash value. |
++-------------+----------------------------------------------------------------+
+| init | is a pointer to the init function. |
++-------------+----------------------------------------------------------------+
+| nextBlock | is a pointer to the algorithm specific nextBlock function. |
++-------------+----------------------------------------------------------------+
+| lastBlock | is a pointer to the algorithm specific lastBlock function. |
++-------------+----------------------------------------------------------------+
+| ctx2hash | is a pointer to the algorithm specific ctx2hash function. |
++-------------+----------------------------------------------------------------+
+| free | is a pointer to the free function or NULL if there is no free |
+| | function. |
++-------------+----------------------------------------------------------------+
+| mem | is a pointer to the algorithm specific mem function. This |
+| | function hashes a complete message which has to reside |
+| | entirely in RAM. This value may be NULL if there is no such |
+| | function. |
++-------------+----------------------------------------------------------------+
+
+HFAL-Basic context
+------------------
+Besides the context types for individual hash functions there is a generic context
+type for HFAL. This is the context to use when using HFAL based functions.
+The HFAL context has the following structure:
+
+::
+
+ typedef struct{
+ hfdesc_t* desc_ptr;
+ void* ctx;
+ } hfgen_ctx_t;
+
++----------+-----------------------------------------------+
+| desc_ptr | a pointer to the HFAL descriptor |
++----------+-----------------------------------------------+
+| ctx | pointer to the hash function specific context |
++----------+-----------------------------------------------+
+
+HFAL-Basic
+----------
+HFAL-Basic provides the basic features of an hash function on top of the
+HFAL. To use it you simply have to include the algorithms you want to use,
+the HFAL descriptor file and of course the HFAL-Basic implementation.
+
+The following functions are provided:
+
+``hfal_hash_init``
+~~~~~~~~~~~~~~~~~~
+::
+
+ uint8_t hfal_hash_init(const hfdesc_t* hash_descriptor, hfgen_ctx_t* ctx)
+
+this function initializes a HFAL context based on the given HFAL descriptor
+pointer (first parameter). The context to initialize is designated by the
+pointer passed as second parameter.
+
+If everything works fine ``0`` is returned. In the case something fails the
+following codes are returned:
+
++---+-------------------------------------------------------------------+
+| 3 | It was not possible to allocate enough memory to hold the context |
+| | variable for the selected hash function. |
++---+-------------------------------------------------------------------+
+
+``hfal_hash_nextBlock``
+~~~~~~~~~~~~~~~~~~~~~~~
+::
+
+ void hfal_hash_nextBlock(hfgen_ctx_t* ctx, const void* block)
+
+this function hashes a block of memory (of algorithm specific length) and
+updates the context accordingly.
+
+``hfal_hash_lastBlock``
+~~~~~~~~~~~~~~~~~~~~~~~
+::
+
+ void hfal_hash_lastBlock(hfgen_ctx_t* ctx, const void* block, uint16_t length_b)
+
+this function is used to hash the last block of a message. Since messages are
+not required to consist of full blocks (or even full bytes) the length of the
+block must be given in bits. The context is updated accordingly. This function
+already performs padding and related stuff.
+
+``hfal_hash_ctx2hash``
+~~~~~~~~~~~~~~~~~~~~~~
+::
+
+ void hfal_hash_ctx2hash(void* dest, hfgen_ctx_t* ctx)
+
+this function converts a context into an actual hash value which is stored in
+``dest``. The application is responsible for allocating enough room.
+
+``hfal_hash_free``
+~~~~~~~~~~~~~~~~~~
+::
+
+ void hfal_hash_free(hfgen_ctx_t* ctx)
+
+this function differs from the individual hash functions ``free`` function
+in that it is always provided and must be called to avoid memory holes.
+This function also automatically calls the implementation specific ``free``
+function if one is provided.
+
+``hfal_hash_mem``
+~~~~~~~~~~~~~~~~~
+::
+
+ void hfal_hash_mem(const hfdesc_t* hash_descriptor, void* dest, const void* msg, uint32_t length_b)
+
+this function is always provided (even if the actual algorithm does not
+specify a ``mem`` function. It hashes an entire message which resides in
+RAM and stores the hash value in ``dest``. ``msg`` is the pointer to the
+message and ``length_b`` is the message length in bits.
+
+``hfal_hash_getBlocksize``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
+
+ uint16_t hfal_hash_getBlocksize(const hfdesc_t* hash_descriptor)
+
+returns the blocksize of the described (``hash_descriptor``) hash function.
+
+``hfal_hash_getHashsize``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+::
+
+ uint16_t hfal_hash_getHashsize(const hfdesc_t* hash_descriptor)
+
+returns the hash value size of the described (``hash_descriptor``) hash
+function.
+
+``hfal_hash_getCtxsize``
+~~~~~~~~~~~~~~~~~~~~~~~~
+::
+
+ uint16_t hfal_hash_getCtxsize_B(const hfdesc_t* hash_descriptor)
+
+returns the size of a context variable of the described (``hash_descriptor``)
+hash function.
+
+
+
projects / avr-crypto-lib.git / commitdiff