255 lines
9.2 KiB
Plaintext
255 lines
9.2 KiB
Plaintext
@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.
|
|
|
|
|
|
|