@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.
+
projects / avr-crypto-lib.git / blobdiff