@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)
--- /dev/null
+@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
+
+
--- /dev/null
+@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)
+
+
--- /dev/null
+@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)
+
projects / avr-crypto-lib.git / commitdiff