new document describing blockcipher usage

diff --git a/A5_1.c b/A5_1.c
index a22d185d829a15196feb457d732700527d7a5047..7a59e1414ad193b7e42e7630ca423eb005bace73 100644 (file)
--- a/A5_1.c
+++ b/A5_1.c
@@ -36,7 +36,7 @@ uint8_t a5_1_clock_core(a5_1_ctx_t *c, uint8_t clockoverride);
 
 
 /*
- * length is length of key in bytes!
+ * length is length of key in bits!
  */
 
 void a5_1_init(a5_1_ctx_t *c, void* key, uint8_t keylength_b, void* iv, uint8_t ivlength_b){

diff --git a/USAGE.blockciphers b/USAGE.blockciphers
new file mode 100644 (file)
index 0000000..688de9f
--- /dev/null
+++ b/USAGE.blockciphers
@@ -0,0 +1,254 @@
+===================================
+=      Usage of blockciphers      =  
+===================================
+
+Author: Daniel Otte
+email:  daniel.otte@rub.de
+ 
+ 
+0. Foreword
+ This file will describe how to use the blockcipher 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.
+ So you will also be introduced to the basic "modes of operation".
+
+1. What a blockcipher does
+ A blockcipher 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 te same key.
+ 
+1.1. high frequent parameters:
+  block size: 64 bits, 128 bits
+  key size: 64 bits, 80 bits, 128 bits, 192 bits, 256 bits
+  (note that some blockciphers use different sizes)
+
+2. Parts of a blockcipher 
+  * encryption algorithm
+  * decryption algorithm
+  * mostly a set of subkeys
+  * mostly a keyschedule which generates the subkeys from the supplied key.
+ As we can see here a blockcipher normally has an algortihm 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.
+
+3. blockcipher 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 blockciphers consists of:
+ 
+ *_init function, which implements the keyschedule
+ *_enc  function, which implements the encryption algorithm
+ *_dec  function, which implements the decryption algorithm
+ *_free function, which frees memory allocated for the keyschedule
+ *_ctx_t context type, which can contain a keyschdule and other 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) and the last parameter points to a context variable
+ to fill.
+ For some ciphers there are additonal parameters like the number of rounds, 
+ these parameters generally occur before the context pointer.
+ 
+3.3. *_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 scound will contain the source block. The two 
+ blocks may overlap or be the same. 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.
+ 
+3.4. *_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.
+ 
+4. modes of operation
+ The usage of cryptographic algorithms is usually motivated by the intend to
+ fight potential threads. Blockciphers are generally good building blocks. There
+ are different attacks to the cipher itself, but this is work to be done by
+ cryptographers, but what stays up to you is using this building blocks in a
+ secure maner.
+ You may read http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation to
+ learn more.
+ 
+4.1. ECB (electronic codebook mode)
+ Electronic codebook mode is the simplest mode of operation and its usages is
+ generally not suggested. In ECB-mode a message which is to encrypt is simply
+ split up in blocks and each block gets indipendently encrypted. The problem 
+ with this mode is that, for example same data produces the same ciphertext, 
+ which may also allows an attacke to inject selected data.
+ 
+    +----+   +----+   +----+           +----+   +----+   +----+
+    | P1 |   | P2 |   | P3 |           | C1 |   | C2 |   | C3 |
+    +----+   +----+   +----+           +----+   +----+   +----+
+      |        |        |                |        |        |
+      V        V        V                V        V        V
+    o---o    o---o    o---o            o---o    o---o    o---o
+    | E |    | E |    | E |            | D |    | D |    | D |
+    o---o    o---o    o---o            o---o    o---o    o---o
+      |        |        |                |        |        |
+      V        V        V                V        V        V
+    +----+   +----+   +----+           +----+   +----+   +----+
+    | C1 |   | C2 |   | C3 |           | P1 |   | P2 |   | P3 |
+    +----+   +----+   +----+           +----+   +----+   +----+
+
+4.2. CBC (chipher-block-chaining mode)
+ CBC-mode is a more advanced mode of opration. It solves most problems of 
+ ECB-mode. It again works by spliting up the message into blocks and intoducing
+ a initialisation vector (IV) at the beginning. The IV should be randomly 
+ generated and is not required to be kept secret. The plaintext of each block
+ is XORed with the ciphertext of the previous block (the first block is XORed
+ with the IV) and then gets encrypted producing the ciphertext block.
+ For decryption of a block simply decrypt the block an XOR it with the previous
+ ciphertext block (or the IV in the case of the first block).
+ CBC-mode has some properties which make it quite useles for some application.
+ For example if you want to store a large amount of data, and you want to make
+ a change in one block you would have to decrypt and reencrypt all follwing
+ blocks. If you have such a case read more about block cipher modes.
+ The wikipedia article http://en.wikipedia.org/wiki/Block_cipher_modes_of_
+ operation#Other_modes_and_other_cryptographic_primitives would make a good 
+ start.
+
+ +----+   +----+   +----+   +----+       +----+   +----+   +----+   +----+
+ | IV |   | P1 |   | P2 |   | P3 |       | IV |   | C1 |   | C2 |   | C3 |
+ +----+   +----+   +----+   +----+       +----+   +----+   +----+   +----+
+   |        |        |        |            |        |        |        |
+   +------> X   +--> X   +--> X            |        +---+    +---+    |
+   |        |   |    |   |    |            |        |   |    |   |    |
+   |        V   |    V   |    V            |        V   |    V   |    V
+   |      o---o |  o---o |  o---o          |      o---o |  o---o |  o---o
+   |      | E | |  | E | |  | E |          |      | D | |  | D | |  | D |
+   |      o---o |  o---o |  o---o          |      o---o |  o---o |  o---o
+   |        |   |    |   |    |            |        |   |    |   |    |
+   |        +---+    +---+    +            +------> X   +--> X   +--> X
+   |        |        |        |            |        |        |        |
+   V        V        V        V            V        V        V        V
+ +----+   +----+   +----+   +----+       +----+   +----+   +----+   +----+
+ | IV |   | C1 |   | C2 |   | C3 |       | IV |   | P1 |   | P2 |   | P3 |
+ +----+   +----+   +----+   +----+       +----+   +----+   +----+   +----+
+
+4.3. stream cipher modes
+ The following modes of operation turn the blockcipher in something better
+ described as stream cipher. So you may consider reading USAGE.streamciphers
+ or anything else about streamcipher if you wish to use this modes.
+ 
+4.3.1. CTR (counter mode)
+ This is quite simple. You use a counter which gets encrypted to produce a
+ key stream. This key stream may be used to encrypt data by XORing the plaintext
+ with the key stream. Decrypting is exactly the same then encrypting BE WARNED, 
+ an attacker might flip a bit in the ciphertext and the corresponding bit in 
+ the plaintext gets fliped. 
+
+ +---------+ o--o  +---------+ o--o  +---------+ o--o  +---------+
+ | counter |-|+1|->| counter |-|+1|->| counter |-|+1|->| counter |
+ +---------+ o--o  +---------+ o--o  +---------+ o--o  +---------+
+      |                 |                 |                 |
+      V                 V                 V                 V
+    o---o             o---o             o---o             o---o
+    | E |             | E |             | E |             | E |
+    o---o             o---o             o---o             o---o
+      |                 |                 |                 |
+      V                 V                 V                 V
+  +--------+        +--------+        +--------+        +--------+
+  |  key   |        |  key   |        |  key   |        |  key   |
+  | stream |        | stream |        | stream |        | stream |
+  +--------+        +--------+        +--------+        +--------+
+ 
+4.3.2 OFB (output-feedback mode) 
+ OFB-mode is much like CTR-mode. In fact the only difference is that you do not
+ increment a counter, but use the output of the encrytption operation before as
+ input.
+ 
+ +-------+         +-------+         +-------+
+ |   IV  |   +---->| input |   +---->| input |
+ +-------+   |     +-------+   |     +-------+
+     |       |         |       |         |
+     V       |         V       |         V
+   o---o     |       o---o     |       o---o
+   | E |     |       | E |     |       | E |
+   o---o     |       o---o     |       o---o
+     |       |         |       |         |
+     V       |         V       |         V
+ +--------+  |     +--------+  |     +--------+
+ | output |--+     | output |--+     | output |
+ +--------+        +--------+        +--------+
+     |                 |                 |
+     V                 V                 V
+ +--------+        +--------+        +--------+
+ |  key   |        |  key   |        |  key   |
+ | stream |        | stream |        | stream |
+ +--------+        +--------+        +--------+
+
+4.3.2 CFB (cipher-feedback mode) 
+ CFB-mode looks much like OFB-mode, but it has a lot of different properties.
+ Instead of using the previous output block as input the resultig ciphertext is
+ used as input. Due to the fact that not the entire outputblock needs to be 
+ used, the ciphertext does not form the entire input block for the next 
+ operation but it is shifted in the input block.
+ The resulting cipher is something known as self synchonising stream cipher.
+ This means tha a manipulation of a single bit in the ciphertext, will result
+ in this bit flipped in th corresponding plaintext but the following block will
+ be "destroyed" until the cipher "healths" itself, meaning the manipulated 
+ ciphertext block gets shift out of the input block.
+
+
+      +-------+              +-------+              +-------+
+      |   IV  |  +--------->>| input |  +--------->>| input |
+      +-------+  |           +-------+  |           +-------+
+          |      |               |      |               |
+          V      |               V      |               V
+        o---o    |             o---o    |             o---o
+        | E |    |             | E |    |             | E |
+        o---o    |             o---o    |             o---o
+          |      |               |      |               |
+          V      |               V      |               V
+      +--------+ |           +--------+ |           +--------+
+      | output | |           | output | |           | output |
+      +--------+ |           +--------+ |           +--------+
+          |      |               |      |               |
+ +----+   V   +----+    +----+   V   +----+    +----+   V   +----+
+ | P1 |-->X-->| C1 |    | P2 |-->X-->| C2 |    | P3 |-->X-->| C3 |
+ +----+       +----+    +----+       +----+    +----+       +----+
+
+
+   +-------------+         +-------------+
+   |  +-------+  |         |  +-------+  |          +-------+
+   |  |   IV  |  +---------|>>| input |  +-------->>| input |
+   |  +-------+            |  +-------+             +-------+
+   |      |                |      |                     |
+   |      V                |      V                     V
+   |    o---o              |    o---o                 o---o
+   |    | E |              |    | E |                 | E |
+   |    o---o              |    o---o                 o---o
+   |      |                |      |                     |
+   |      V                |      V                     V
+   |  +--------+           |  +--------+            +--------+
+   |  | output |           |  | output |            | output |
+   |  +--------+           |  +--------+            +--------+
+   |      |                |      |                      |
+ +----+   V   +----+     +----+   V   +----+    +----+   V   +----+
+ | C1 |-->X-->| P1 |     | C2 |-->X-->| P2 |    | C3 |-->X-->| P3 |
+ +----+       +----+     +----+       +----+    +----+       +----+
+

diff --git a/mkfiles/a5_1.mk b/mkfiles/a5_1.mk
new file mode 100644 (file)
index 0000000..6d89b62
--- /dev/null
+++ b/mkfiles/a5_1.mk
@@ -0,0 +1,12 @@
+# Makefile for ARCFOUR (RC4 compatible)
+ALGO_NAME := A51
+
+# comment out the following line for removement of ARCFOUR from the build process
+STREAM_CIPHERS += $(ALGO_NAME)
+
+$(ALGO_NAME)_OBJ      := A5_1.o
+$(ALGO_NAME)_TEST_BIN := main-a5_1-test.o debug.o uart.o serial-tools.o \
+                         nessie_stream_test.o nessie_common.o A5_1.o
+$(ALGO_NAME)_NESSIE_TEST      := "nessie"
+$(ALGO_NAME)_PEROFRMANCE_TEST := "performance"
+