bg
/
avr-crypto-lib
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

more docu

This commit is contained in:
bg 2011-06-26 23:55:31 +00:00
parent bcad01af2c
commit ca330e4062
4 changed files with 545 additions and 294 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

297
doc/acl-guide.texi
View File

@ -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)

379
doc/acl_blockciphers.texi Normal file
View File

@ -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

87
doc/acl_hashes.texi Normal file
View File

@ -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)

76
doc/acl_streamciphers.texi Normal file
View File

@ -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)