From 854dea52b9237692593d8bfc0619c194df5b9c3a Mon Sep 17 00:00:00 2001 From: bg Date: Sun, 20 Jul 2008 16:30:43 +0000 Subject: [PATCH] new document describing blockcipher usage --- A5_1.c | 2 +- USAGE.blockciphers | 254 +++++++++++++++++++++++++++++++++++++++++++++ mkfiles/a5_1.mk | 12 +++ 3 files changed, 267 insertions(+), 1 deletion(-) create mode 100644 USAGE.blockciphers create mode 100644 mkfiles/a5_1.mk diff --git a/A5_1.c b/A5_1.c index a22d185..7a59e14 100644 --- 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 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 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" + -- 2.39.2