@c acl_hashes.texi

@section 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.
 
@subsection List of available hash functions
 The following hash functions are currently implemented:
@itemize @bullet 
  @item Blake
  @item BlueMidnightWish
  @item CubeHash
  @item Echo
  @item Grøstl
  @item Keccak
  @item MD5
  @item SHA-256
  @item SHA-1
  @item Shabal
  @item Skein 
@end itemize 

@subsection High frequent parameters:
@table @asis
  @item block size 
  512 bits
  @item hash value size
  128 bits, 160 bits, 224 bits, 256 bits, 384 bits, 512 bits
@end table


@subsection Parts of a hash function 
@itemize @bullet  
  @item initialization function 
  @item compression algorithm
  @item finalization function
@end itemize 

@subsection 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:
@table @code
 @item *_init
 function, which implements the initialisation of the context
 @item *_nextBlock 
 function, which implements the compression algorithm
 @item *_lastBlock 
 function, which implements the the padding algorithm
 @item *_ctx2hash  
 function, which turns a context into an actual hash value
 @item *_ctx_t
 context type, which can contains the state of a hashing process
@end table

@subsubsection @code{*_init} function
 The @code{*_init} function generally takes a pointer to the context as parameter.
 This function initializes the context with algorithm specific values.
 
@subsubsection @code{*_nextBlock} function
 The @code{*_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 @code{*_lastBlock} function described
 below.
 
@subsubsection @code{*_lastBlock} function
 The @code{*_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.

@subsubsection @code{*_ctx2hash} function
 The @code{*_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. 
 

@subsection 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.

@subsection Parts of HFAL
The HFAL is split up in different parts:
@itemize @bullet
  @item HFAL declaration for HFAL decriptors
  @item algorithm specific definitions of HFAL decriptors
  @item HFAL basic context type
  @item HFAL basic functions  
@end itemize

@subsection HFAL declaration for HFAL decriptors
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.

@verbatim
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 */
@end verbatim

@table @var
  @item type
  should be set to @samp{2} to indicate that this descriptor is for a
  hash function.

 @item flags
 currently unused, should be set to zero.

 @item 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, ...).

 @item ctxsize_B
 is the number of bytes which should be allocated for the context variable.

 @item blocksize_b
 is the number of bits on which are hashed by one iteration of the nextBlock 
 function.

 @item hashsize_b
 is the number of bits on which are outputed as final hash value.

 @item init
 is a pointer to the init function.

 @item nextBlock
 is a pointer to the algorithm specific nextBlock function.

 @item lastBlock
 is a pointer to the algorithm specific lastBlock function.

 @item ctx2hash
 is a pointer to the algorithm specific ctx2hash function.

 @item free
 is a pointer to the free function or NULL if there is no free function.

 @item 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.
@end table

@subsection 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:
@verbatim
typedef struct{
	hfdesc_t* desc_ptr;
	void*     ctx;
} hfgen_ctx_t;
@end verbatim
@table @code
@item desc_ptr
a pointer to the HFAL descriptor
@item ctx
pointer to the hash function specific context
@end table

@subsection 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:

@subsubsection @code{hfal_hash_init} 
@code{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 @samp{0} is returned. In the case something fails
 the following codes are returned:
@table @samp
  @item 3
  It was not possible to allocate enough memory to hold the context variable
  for the selected hash function.
@end table

@subsubsection @code{hfal_hash_nextBlock} 
@code{ 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.

@subsubsection @code{hfal_hash_lastBlock} 
@code{ 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.

@subsubsection @code{hfal_hash_ctx2hash} 
@code{ void hfal_hash_ctx2hash(void* dest, hfgen_ctx_t* ctx)}
  this function converts a context into an actual hash value which is stored in
  @code{dest}. The application is responsible for allocating enough room.

@subsubsection @code{hfal_hash_free} 
@code{ void hfal_hash_free(hfgen_ctx_t* ctx)}
  this function differs from the individual hash functions @code{free} function
  in that it is allways provided and must be called to avoid memory holes.
  This function also automatically calls the implementation specific @code{free}
  function if one is provided.

@subsubsection @code{hfal_hash_mem} 
@code{ void hfal_hash_mem(const hfdesc_t* hash_descriptor, void* dest, const void* msg, uint32_t length_b)}
  this function is allways provided (even if the actual algorithm does not 
  specify a @code{mem} function. It hashes an entire message which resides in
  RAM and stores the hash value in @code{dest}. @code{msg} is the pointer to the
  message and @code{length_b} is the message length in bits.

@subsubsection @code{hfal_hash_getBlocksize} 
@code{ uint16_t hfal_hash_getBlocksize(const hfdesc_t* hash_descriptor)}
  returns the blocksize of the described (@code{hash_descriptor}) hash function.

@subsubsection @code{hfal_hash_getHashsize} 
@code{ uint16_t hfal_hash_getHashsize(const hfdesc_t* hash_descriptor)}
  returns the hash value size of the described (@code{hash_descriptor}) hash function.

@subsubsection @code{hfal_hash_getCtxsize} 
@code{ uint16_t hfal_hash_getCtxsize_B(const hfdesc_t* hash_descriptor)}
  returns the size of a context variable of the described (@code{hash_descriptor}) hash function.