====================================
=      Usage of streamciphers      =  
====================================

Author: Daniel Otte
email:  daniel.otte@rub.de
 
 
0. Foreword
 This file will describe how to use the streamcipher implementations provided
 by this library. It will not only show how to call the cryptographic functions
 but also discuss a little how to build security mechanisms from that.

1. What a streamcipher does
 A streamcipher normally generates a deterministic, random looking stream of 
 bits, known as keystream. For encryption purpose this keystream is XORed with
 the data stream. So decryption is exactly the same as encryption. The 
 data-stream is XORed with the keystream giving the plaintext. So both sides 
 need exactly the same streamcipher in the same state.
  
1.1. high frequent parameters:
	output-size: 8 bit, 1 bit
	keysize: 64 bit, 80 bit, 128 bit
	IVsize: 64 bit

2. Parts of a streamcipher
  * generation algorithm
  * initialization algorithm
  * state
 As we can see all streamciphers 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.
 
3. streamcipher 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 streamciphers consists of:
 
 *_init function, which implements the initialization
 *_gen  function, which implements the streamcipher algorithm and generates a 
        keystream output
 *_ctx_t context type, which contains internal state information
 
3.1 look at the prototypes
 Generally the prototypes (defined in the *.h files) will tell you what 
 parameter means what. 
  
3.1.2 sizes in bits and bytes
 Working with cryptographical functions involves working with different lengths.
 Some times you want to know it in bits and sometimes in bytes. To reduce
 frustration and to avoid bugs we suffix a length parameter with either _b or
 _B depending on the meaning. _b means in bits and _B means in bytes 
 (big b big word).  
 
3.2. *_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.
 
3.3. *_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.