changed arcfour api

[avr-crypto-lib.git] / USAGE.streamciphers

diff --git a/USAGE.streamciphers b/USAGE.streamciphers
new file mode 100644 (file)
index 0000000..68fb197
--- /dev/null
+++ b/USAGE.streamciphers
@@ -0,0 +1,71 @@
+====================================
+=      Usage of streamciphers      =  
+====================================
+
+Author: Daniel Otte
+email:  daniel.otte@rub.de
+ 
+ 
+0. Foreword
+ This file will describe how to use the streramcipher 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 normaly 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 
+ datastream 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:
+       outputsize: 8 bit, 1 bit
+       keysize: 64 bit, 80 bit, 128 bit
+       IVsize: 64 bit
+
+2. Parts of a streamcipher
+  * generation algorithm
+  * initialisation algorithm
+  * state
+ As we can see all streamciphers seem to utilize an internal state which
+ determines the output. This state is initialized by the initialisation 
+ algorithm with a key and an IV (initialisation 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 initialisation
+ *_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.
+ 
+
+ 
\ No newline at end of file