new document describing blockcipher usage
This commit is contained in:
parent
94cad47618
commit
854dea52b9
2
A5_1.c
2
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){
|
||||
|
|
|
@ -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 |
|
||||
+----+ +----+ +----+ +----+ +----+ +----+
|
||||
|
|
@ -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"
|
||||
|
Loading…
Reference in New Issue