From ca330e4062c4d93a75ac5046b80937acbadf7794 Mon Sep 17 00:00:00 2001 From: bg Date: Sun, 26 Jun 2011 23:55:31 +0000 Subject: [PATCH] more docu --- doc/acl-guide.texi | 297 +---------------------------- doc/acl_blockciphers.texi | 379 +++++++++++++++++++++++++++++++++++++ doc/acl_hashes.texi | 87 +++++++++ doc/acl_streamciphers.texi | 76 ++++++++ 4 files changed, 545 insertions(+), 294 deletions(-) create mode 100644 doc/acl_blockciphers.texi create mode 100644 doc/acl_hashes.texi create mode 100644 doc/acl_streamciphers.texi diff --git a/doc/acl-guide.texi b/doc/acl-guide.texi index 474c78c..bf004ab 100644 --- a/doc/acl-guide.texi +++ b/doc/acl-guide.texi @@ -43,304 +43,13 @@ to use the library. @chapter Symmetric primitives -@section Block ciphers -@subsection What a block cipher does - A block cipher is a algorithm which turn an input of fixed length into an - output of the same length (enciphering or encrypting). The transformation is - specified by a key which has to be of a fixed length, or a length of a given - set or range. - Generally there is also an algorithm which turns the output back to the - previous input (deciphering or decrypting) when supplied with the same key. - -@subsection List of available block ciphers -This is a list of the currently supported block ciphers: -@itemize @bullet - @item AES (Advanced Encryption Standard) - @item Camellia - @item CAST5 - @item CAST6 - @item CS-Cipher - @item DES (Data Encryption Standard) - @item Khazad - @item Noekeon - @item Present - @item RC5 - @item RC6 - @item Seed - @item Serpent (AES finalist) - @item Shacal1 - @item Shacal2 - @item Skipjack - @item TDES (Tripple DES) - @item Threefish - @item XTEA -@end itemize +@include acl_blockciphers.texi -@subsection high frequent parameters: - block size: 64 bits, 128 bits - key size: 64 bits, 80 bits, 128 bits, 192 bits, 256 bits - (note that some block ciphers use different sizes) - -@subsection Parts of a block cipher -@itemize @bullet - @item encryption algorithm - @item decryption algorithm - @item mostly a set of subkeys - @item mostly a keyschedule which generates the subkeys from the supplied key. -@end itemize - As we can see here a block cipher normally has an algorithm besides the - encryption and decryption algorithm, which we call keyschedule. - Mostly the encryption and decryption algorithm consist of multiple rounds, - where each round (and sometimes between rounds) subkeys are needed to modify - the data. This subkeys are generated by the keyschedule and stored in a state - or context variable. - Note that not all algorithms need a pregenerated context, sometimes it is easy - to generate the subkeys "on the fly" so there is not always the need of a - context variable. In this case instead of a context the actual key is passed - to the encryption and decryption function. - -@subsection API of block ciphers - 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: -@itemize @bullet - @item *_init function, which implements the keyschedule - @item *_enc function, which implements the encryption algorithm - @item *_dec function, which implements the decryption algorithm - @item *_free function, which frees memory allocated for the keyschedule - @item *_ctx_t context type, which can contain a keyschedule and other information -@end itemize -@subsubsection *_init function - The *_init function generally takes a pointer to the key as first parameter. - For ciphers where the keysize is not fixed the second parameter gives the - keysize (in bits regularly) and the last parameter points to the context - variable to fill. - For some ciphers there are additional parameters like the number of rounds, - these parameters generally occur before the context pointer. - -@subsubsection *_enc and *_dec functions - The encryption and decryption function of a specific algorithm normally do not - differ in their parameters. Generally these functions take a pointer to the - block to operate on. Some ciphers allow to specify two blocks, where the first - one will be written to and the second will contain the source block. The two - blocks may overlap or be the same. Most ciphers have only one block pointer. - The block specified by the pointer is encrypted (if the *_enc function is - called) or decrypted (if the *_dec function is called). - The last parameter specifies either the key direct (with a pointer to it) or - is a pointer to a context created with the *_init function. - It is guaranteed that the context is in the same state as before the *_enc or - *_dec function call. Most *_enc and *_dec functions do not modify the context - at all, but some do for reducing dynamic memory requirements. So here are some - limitations to the reentrant property. - -@subsubsection *_free function - A *_free function is only provided where needed (so most ciphers do not have - it). It is used to free memory dynamically allocated by the *_init function. - -@subsubsection *_ctx_t type - A variable of the *_ctx_t type may hold information needed by the *_enc or - *_dec function. It is initialized by the *_init function. If dynamic memory is - allocated by the *_init function also a *_free function is provided which frees - the allocated memory. An initialized *_ctx_t variable may not be copied as it - may contains pointers to itself. - -@section Block cipher abstraction layer (BCAL) -The BlockCipeherAbstractionLayer (BCAL) is an abstraction layer which allows -usage of all implemented block ciphers in a simple way. It abstracts specific -function details and is suitable for implementations which want to be flexible -in the choosing of specific block ciphers. Another important aspect is that this -abstraction layer enables the implementation of block cipher operating modes -independently from concrete ciphers. It is very simple to use and reassembles -the API used to implement individual ciphers. - -The main component is a block cipher descriptor which contains the details of -the individual ciphers. - -Care should be taken when choosing a specific keysize. It may be the case that -the chosen keysize is not compatible with the chosen block cipher. - - -@subsection Parts of BCAL -The BCAL is split up in different parts: -@itemize @bullet - @item BCAL declaration for BCAL decriptors - @item algorithm specific definitions of BCAL decriptors - @item BCAL basic context type - @item BCAL basic functions -@end itemize - -@subsubsection BCAL declaration for BCAL decriptors -The BCAL 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 block cipher. - -@verbatim -typedef struct { - uint8_t type; /* 1==block cipher */ - uint8_t flags; - PGM_P name; - uint16_t ctxsize_B; - uint16_t blocksize_b; - bc_init_fpt init; - bc_enc_fpt enc; - bc_dec_fpt dec; - bc_free_fpt free; - PGM_VOID_P valid_keysize_desc; -} bcdesc_t; /* block cipher descriptor type */ -@end verbatim - -@table @var - @item type - should be set to @samp{1} to indicate that this descriptor is for a - block cipher. - - @item flags - defines what kind of init function is provided and what kind of decrypt - and encrypt functions are provided. - - @table @asis - @item bit 0 - if clear (@samp{0}) designates an init function with fixed key length, so - the length parameter is omitted (@code{init(void* ctx, void* key)}). - - if set (@samp{1}) designates an init function which requires an explicit - keysize argument (@code{init(void*ctx, uint16_t length_b, void* key)}). - - @item bit 1 - if clear (@samp{0}) designates that the encryption function transforms the - plaintext block in place to the ciphertext (@code{enc(void* block, void* ctx)}). - - if set (@samp{1}) designates that the encryption function offers a dedicated - pointers for input and output. The two regions may be the same - (@code{enc(void* out, void* in, void*ctx)}). - - @item bit 2 - if clear (@samp{0}) designates that the decryption function transforms the - ciphertext block in place to the plaintext (@code{dec(void* block, void* ctx)}). - - if set (@samp{1}) designates that the decryption function offers a dedicated - pointers for input and output. The two regions may be the same - (@code{dec(void* out, void* in, void*ctx)}). - @end table - - @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 the encrypt and decrypt function work on. - - @item init - is a pointer to the init function (see @samp{flags} how the init function - should be called). If there is no init function this field is NULL. - - @item enc - is a pointer to the encryption function (see @samp{flags} how the encryption - function should be called). - - @item dec - is a pointer to the decryption function (see @samp{flags} how the decryption - function should be called). - - @item free - is a pointer to the free function or NULL if there is no free function. - - @item valid_keysize_desc - is a pointer to a keysize descriptor structure which is used to validate - that the chosen keysize is valid -@end table - -@subsubsection BCAL-Basic context -Besides the context types for individual ciphers there is a generic context -type for BCAL. This is the context to use when using BCAL based functions. -The BCAL context has the following structure: -@verbatim -typedef struct{ - bcdesc_t* desc_ptr; - uint16_t keysize; - void* ctx; -} bcgen_ctx_t; -@end verbatim -@table @code -@item desc_ptr -a pointer to the BCAL descriptor -@item keysize -the chosen keysize -@item ctx -pointer to the cipher specific context -@end table - - - -@subsubsection BCAL-Basic -BCAL-Basic provides the basic features of an block cipher on top of the -BCAL. To use it you simply have to include the algorithms you want to use, -the BCAL descriptor file and of course the BCAL-Basic implementation. - -The following functions are provided: -@table @code -@item bcal_cipher_init -@code{uint8_t bcal_cipher_init(const bcdesc_t* cipher_descriptor, const void* key, uint16_t keysize_b, bcgen_ctx_t* ctx)} - this function initializes a BCAL context based on the given BCAL descriptor - pointer (first parameter) with a given key (second parameter) of a given length - (third parameter). The context to initialize is designated by the pointer - passed as fourth parameter. - - If everything works fine @samp{0} is returned. In the case something fails - the following codes are returned: -@table @samp - @item 1 - The specified keysize is not available with this cipher - @item 2 - It was not possible to allocate enough memory to hold the key. - (This is returned when there is no actual init function and you ran out - of memory) - @item 3 - It was not possible to allocate enough memory to hold the context variable - for the selected cipher. -@end table - -@item bcal_cipher_free -@code{void bcal_cipher_free(bcgen_ctx_t* ctx)} this function frees the memory -allocated by the init function and should be called whenever you are finished -with BCAL context. It automatically also calls the @code{free} function if -necessary. - -@item bcal_cipher_enc -@code{void bcal_cipher_enc(void* block, const bcgen_ctx_t* ctx)} -this function encrypts a block in-place using a given BCAL contex. - -@item bcal_cipher_dec -@code{void bcal_cipher_dec(void* block, const bcgen_ctx_t* ctx)} -this function decrypts a block in-place using a given BCAL contex. - -@item bcal_cipher_getBlocksize_b -@code{uint16_t bcal_cipher_getBlocksize_b(const bcdesc_t* desc)} -this function returns the block size of a given cipher by using the BCAL -descriptor (to which a pointer must be passed). - -@item bcal_cipher_getKeysizeDesc -@code{PGM_VOID_P bcal_cipher_getKeysizeDesc(const bcdesc_t* desc)} -this function returns a pointer to the keysize descriptor of a given cipher by -using the BCAL descriptor (to which a pointer must be passed). - -@end table @section Modes of operation -@section Stream ciphers -@subsection List of available stream ciphers -@subsection API of stream ciphers -@subsection Stream cipher abstraction layer (SCAL) +@include acl_streamciphers.texi -@section Hash functions -@subsection List of available hash functions -@subsection API of hash functions -@subsection Hash function abstraction layer (HFAL) +@include acl_hashes.texi @section MAC functions @section Pseudo random number generators (PRNGs) diff --git a/doc/acl_blockciphers.texi b/doc/acl_blockciphers.texi new file mode 100644 index 0000000..93b6a8d --- /dev/null +++ b/doc/acl_blockciphers.texi @@ -0,0 +1,379 @@ +@c acl_blockcipher.texi + +@section Block ciphers +@subsection What a block cipher does + A block cipher is a algorithm which turn an input of fixed length into an + output of the same length (enciphering or encrypting). The transformation is + specified by a key which has to be of a fixed length, or a length of a given + set or range. + Generally there is also an algorithm which turns the output back to the + previous input (deciphering or decrypting) when supplied with the same key. + +@subsection List of available block ciphers +This is a list of the currently supported block ciphers: +@itemize @bullet + @item AES (Advanced Encryption Standard) + @item Camellia + @item CAST5 + @item CAST6 + @item CS-Cipher + @item DES (Data Encryption Standard) + @item Khazad + @item Noekeon + @item Present + @item RC5 + @item RC6 + @item Seed + @item Serpent (AES finalist) + @item Shacal1 + @item Shacal2 + @item Skipjack + @item TDES (Tripple DES) + @item Threefish + @item XTEA +@end itemize + +@subsection high frequent parameters: +@table @asis + @item block size + 64 bits, 128 bits + @item key size + 64 bits, 80 bits, 128 bits, 192 bits, 256 bits + (note that some block ciphers use different sizes) +@end table + +@subsection Parts of a block cipher +@itemize @bullet + @item encryption algorithm + @item decryption algorithm + @item mostly a set of subkeys + @item mostly a keyschedule which generates the subkeys from the supplied key. +@end itemize + As we can see here a block cipher normally has an algorithm besides the + encryption and decryption algorithm, which we call keyschedule. + Mostly the encryption and decryption algorithm consist of multiple rounds, + where each round (and sometimes between rounds) subkeys are needed to modify + the data. This subkeys are generated by the keyschedule and stored in a state + or context variable. + Note that not all algorithms need a pregenerated context, sometimes it is easy + to generate the subkeys "on the fly" so there is not always the need of a + context variable. In this case instead of a context the actual key is passed + to the encryption and decryption function. + +@subsection API of block ciphers + 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 keyschedule + @item *_enc + function, which implements the encryption algorithm + @item *_dec + function, which implements the decryption algorithm + @item *_free + function, which frees memory allocated for the keyschedule + @item *_ctx_t + context type, which can contain a keyschedule and other information +@end table +@subsubsection @code{*_init} function + The @code{*_init} function generally takes a pointer to the key as first parameter. + For ciphers where the keysize is not fixed the second parameter gives the + keysize (in bits regularly) and the last parameter points to the context + variable to fill. + For some ciphers there are additional parameters like the number of rounds, + these parameters generally occur before the context pointer. + +@subsubsection @code{*_enc} and @code{*_dec} functions + The encryption and decryption function of a specific algorithm normally do not + differ in their parameters. Generally these functions take a pointer to the + block to operate on. Some ciphers allow to specify two blocks, where the first + one will be written to and the second will contain the source block. The two + blocks may overlap or be the same. Most ciphers have only one block pointer. + The block specified by the pointer is encrypted (if the @code{*_enc} function is + called) or decrypted (if the @code{*_dec} function is called). + The last parameter specifies either the key direct (with a pointer to it) or + is a pointer to a context created with the @code{*_init} function. + It is guaranteed that the context is in the same state as before the *_enc or + @code{*_dec} function call. Most @code{*_enc} and @code{*_dec} functions do not modify the context + at all, but some do for reducing dynamic memory requirements. So here are some + limitations to the reentrant property. + +@subsubsection @code{*_free} function + A @code{*_free} function is only provided where needed (so most ciphers do not have + it). It is used to free memory dynamically allocated by the @code{*_init} function. + +@subsubsection *_ctx_t type + A variable of the @code{*_ctx_t} type may hold information needed by the @code{*_enc} or + @code{*_dec} function. It is initialized by the @code{*_init} function. If dynamic memory is + allocated by the @code{*_init} function also a @code{*_free} function is provided which frees + the allocated memory. An initialized @code{*_ctx_t} variable may not be copied as it + may contains pointers to itself. + +@section Block cipher abstraction layer (BCAL) +The BlockCipeherAbstractionLayer (BCAL) is an abstraction layer which allows +usage of all implemented block ciphers in a simple way. It abstracts specific +function details and is suitable for implementations which want to be flexible +in the choosing of specific block ciphers. Another important aspect is that this +abstraction layer enables the implementation of block cipher operating modes +independently from concrete ciphers. It is very simple to use and reassembles +the API used to implement individual ciphers. + +The main component is a block cipher descriptor which contains the details of +the individual ciphers. + +Care should be taken when choosing a specific keysize. It may be the case that +the chosen keysize is not compatible with the chosen block cipher. + + +@subsection Parts of BCAL +The BCAL is split up in different parts: +@itemize @bullet + @item BCAL declaration for BCAL decriptors + @item algorithm specific definitions of BCAL decriptors + @item BCAL basic context type + @item BCAL basic functions +@end itemize + +@subsubsection BCAL declaration for BCAL decriptors +The BCAL 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 block cipher. + +@verbatim +typedef struct { + uint8_t type; /* 1==block cipher */ + uint8_t flags; + PGM_P name; + uint16_t ctxsize_B; + uint16_t blocksize_b; + bc_init_fpt init; + bc_enc_fpt enc; + bc_dec_fpt dec; + bc_free_fpt free; + PGM_VOID_P valid_keysize_desc; +} bcdesc_t; /* block cipher descriptor type */ +@end verbatim + +@table @var + @item type + should be set to @samp{1} to indicate that this descriptor is for a + block cipher. + + @item flags + defines what kind of init function is provided and what kind of decrypt + and encrypt functions are provided. + + @table @asis + @item bit 0 + if clear (@samp{0}) designates an init function with fixed key length, so + the length parameter is omitted (@code{init(void* ctx, void* key)}). + + if set (@samp{1}) designates an init function which requires an explicit + keysize argument (@code{init(void*ctx, uint16_t length_b, void* key)}). + + @item bit 1 + if clear (@samp{0}) designates that the encryption function transforms the + plaintext block in place to the ciphertext (@code{enc(void* block, void* ctx)}). + + if set (@samp{1}) designates that the encryption function offers a dedicated + pointers for input and output. The two regions may be the same + (@code{enc(void* out, void* in, void*ctx)}). + + @item bit 2 + if clear (@samp{0}) designates that the decryption function transforms the + ciphertext block in place to the plaintext (@code{dec(void* block, void* ctx)}). + + if set (@samp{1}) designates that the decryption function offers a dedicated + pointers for input and output. The two regions may be the same + (@code{dec(void* out, void* in, void*ctx)}). + @end table + + @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 the encrypt and decrypt function work on. + + @item init + is a pointer to the init function (see @samp{flags} how the init function + should be called). If there is no init function this field is NULL. + + @item enc + is a pointer to the encryption function (see @samp{flags} how the encryption + function should be called). + + @item dec + is a pointer to the decryption function (see @samp{flags} how the decryption + function should be called). + + @item free + is a pointer to the free function or NULL if there is no free function. + + @item valid_keysize_desc + is a pointer to a keysize descriptor structure which is used to validate + that the chosen keysize is valid +@end table + +@subsubsection BCAL-Basic context +Besides the context types for individual ciphers there is a generic context +type for BCAL. This is the context to use when using BCAL based functions. +The BCAL context has the following structure: +@verbatim +typedef struct{ + bcdesc_t* desc_ptr; + uint16_t keysize; + void* ctx; +} bcgen_ctx_t; +@end verbatim +@table @code +@item desc_ptr +a pointer to the BCAL descriptor +@item keysize +the chosen keysize +@item ctx +pointer to the cipher specific context +@end table + + + +@subsubsection BCAL-Basic +BCAL-Basic provides the basic features of an block cipher on top of the +BCAL. To use it you simply have to include the algorithms you want to use, +the BCAL descriptor file and of course the BCAL-Basic implementation. + +The following functions are provided: +@table @code +@item bcal_cipher_init +@code{uint8_t bcal_cipher_init(const bcdesc_t* cipher_descriptor, const void* key, uint16_t keysize_b, bcgen_ctx_t* ctx)} + this function initializes a BCAL context based on the given BCAL descriptor + pointer (first parameter) with a given key (second parameter) of a given length + (third parameter). The context to initialize is designated by the pointer + passed as fourth parameter. + + If everything works fine @samp{0} is returned. In the case something fails + the following codes are returned: +@table @samp + @item 1 + The specified keysize is not available with this cipher + @item 2 + It was not possible to allocate enough memory to hold the key. + (This is returned when there is no actual init function and you ran out + of memory) + @item 3 + It was not possible to allocate enough memory to hold the context variable + for the selected cipher. +@end table + +@item bcal_cipher_free +@code{void bcal_cipher_free(bcgen_ctx_t* ctx)} this function frees the memory +allocated by the init function and should be called whenever you are finished +with BCAL context. It automatically also calls the @code{free} function if +necessary. + +@item bcal_cipher_enc +@code{void bcal_cipher_enc(void* block, const bcgen_ctx_t* ctx)} +this function encrypts a block in-place using a given BCAL contex. + +@item bcal_cipher_dec +@code{void bcal_cipher_dec(void* block, const bcgen_ctx_t* ctx)} +this function decrypts a block in-place using a given BCAL contex. + +@item bcal_cipher_getBlocksize_b +@code{uint16_t bcal_cipher_getBlocksize_b(const bcdesc_t* desc)} +this function returns the block size of a given cipher by using the BCAL +descriptor (to which a pointer must be passed). + +@item bcal_cipher_getKeysizeDesc +@code{PGM_VOID_P bcal_cipher_getKeysizeDesc(const bcdesc_t* desc)} +this function returns a pointer to the keysize descriptor of a given cipher by +using the BCAL descriptor (to which a pointer must be passed). + +@end table + +@subsection Keysize descriptors +There are a lot of different block ciphers or cryptographic algorithms in +general which put several constrains to the number of bits which can be used +as key. + +Our approach is to find a simple and compact way do specify which lengths are +valid and which are not. The system is quite simple, we use a list of patterns +(with parameters) and if any matches the keysize is valid, if none matches the +keysize is unsupported. + +The patterns are: +@itemize @bullet +@item simple list of valid keysizes +@item range of keysizes +@item augmented range of keysizes +@end itemize + +@subsubsection simple list of valid keysizes +The simple keysize list has the following structure: +@verbatim +typedef struct{ /* keysize is valid if listed in items */ + uint8_t n_items; /* number of items (value 0 is reserved) */ + uint16_t items[]; /* list of valid lengths */ +}keysize_desc_list_t; +@end verbatim +First we specify how many keysizes we want to declare valid (this is limited to +255 keysizes but that should not impose any real world constrains). And follow +it by the keysizes as 16bit unsigned values. + +If you want to declare a lot of keys please check first the other methods since +they may give a more compact definition. + +@subsubsection range of keysizes +This method specifies an entire range of keys a valid using the following +structure: +@verbatim +typedef struct{ /* keysize is valid if min<=keysize<=max */ + uint16_t min; + uint16_t max; +}keysize_desc_range_t; +@end verbatim +So all keysizes between @code{min} and @code{max} (including @code{min} and +@code{max}) are valid. Please note that in most cases also keysizes which +are not a multiple of 8 (so are not full bytes) are also matched. +If you want to avoid this see the augmented range of keysizes. + +@subsubsection augmented range of keysizes +The augmented range of keysizes uses the following structure: +@verbatim +typedef struct{ /* keysize is valid if min<=keysize<=max and if keysize mod distance == offset */ + uint16_t min; + uint16_t max; + uint16_t distance; + uint16_t offset; +}keysize_desc_arg_range_t; +@end verbatim +The restriction to a range is the same as with the simpler range of keysizes, +but also another restriction is imposed. A valid keysize must have a reminder +of @code{offset} when divided by @code{distance}. So you can limit a keysize +to full bytes by simply setting @code{distance} to @samp{8} and @code{offset} +to @samp{0}. + +@subsubsection the actual descriptor +The keysize descriptor is a list of the former patterns. Each pattern is +preceded by byte designating the type of pattern and the list is terminated +by a @code{NULL} byte. + +The designator byte can have one of the following values: +@table @samp +@item 0x00 +Terminator byte, signals the end of the list +@item 0x01 +simple list of keysizes +@item 0x02 +simple range of keysizes +@item 0x03 +augmented range of keysizes +@end table + + diff --git a/doc/acl_hashes.texi b/doc/acl_hashes.texi new file mode 100644 index 0000000..29a0ca0 --- /dev/null +++ b/doc/acl_hashes.texi @@ -0,0 +1,87 @@ +@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) + + diff --git a/doc/acl_streamciphers.texi b/doc/acl_streamciphers.texi new file mode 100644 index 0000000..c567a6f --- /dev/null +++ b/doc/acl_streamciphers.texi @@ -0,0 +1,76 @@ +@c acl_streamciphers.texi +@section Stream ciphers + A stream cipher normally generates a deterministic, random looking stream of + bits, known as key stream. For encryption purpose this key stream is XORed with + the data stream. So decryption is exactly the same as encryption. The + data-stream is XORed with the key stream giving the plaintext. So both sides + need exactly the same stream cipher in the same state. + +@subsection List of available stream ciphers + The following stream ciphers are currently implemented: +@itemize @bullet + @item ARCFOUR (RC4 compatibel) + @item Trivium + @item Grain + @item MUGI + @item Mickey-128 (v2) +@end itemize + +@subsection High frequent parameters +@table @asis + @item output-size + 8 bit, 1 bit + @item keysize + 64 bit, 80 bit, 128 bit + @item IVsize + 64 bit +@end table + +@subsection Parts of a stream cipher +@itemize @bullet + @item generation algorithm + @item initialization algorithm + @item state +@end itemize + + As we can see all stream ciphers seem to utilize an internal state which + determines the output. This state is initialized by the initialization + algorithm with a key and an IV (initialization vector). It is very important + for security that _never_ the same key with the same IV is used again. The + IV is not required to be kept secret. + +@subsection API of stream ciphers + 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 stream ciphers consists of: + @table @code + @item *_init + function, which implements the initialization + + @item *_gen + function, which implements the streamcipher algorithm and generates a + keystream output + + @item *_ctx_t + context type, which contains internal state information + + @end table + +@subsubsection @code{*_init} function + The *_init function generally takes a pointer to the key as first parameter. + For ciphers where the keysize is not fixed the second parameter gives the + keysize (in bits regularly) followed by a pointer to the IV and a length + parameter for not fixed IV sizes (both are omitted if the algorithm does not + specify IV handling, in this case a part of the key should be used as IV). + The last parameter points to the context variable to fill. + +@subsubsection @code{*_gen} function + The *_gen function updates the internal state to which a pointer is given as + parameter and returns a fixed length part of the keystream as return value. + + + +@subsection Stream cipher abstraction layer (SCAL) + -- 2.39.5