X-Git-Url: https://git.cryptolib.org/avr-crypto-lib.git?a=blobdiff_plain;f=doc%2Facl_hashes.texi;h=8b351ca2785a11b251be65a876d788b3ac25e4a4;hb=6cddae4d0fa8acf9d3bfd5e0f42c789c32f3a992;hp=29a0ca0d97ce34118e047acb07565c272c96afb5;hpb=8fcc61325708d1e3b90e7b23135b9a1ab206d115;p=avr-crypto-lib.git diff --git a/doc/acl_hashes.texi b/doc/acl_hashes.texi index 29a0ca0..8b351ca 100644 --- a/doc/acl_hashes.texi +++ b/doc/acl_hashes.texi @@ -83,5 +83,172 @@ @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. +