1 ===================================
2 = Usage of blockciphers =
3 ===================================
6 email: daniel.otte@rub.de
10 This file will describe how to use the blockcipher implementations provided by
11 this library. It will not only show how to call the cryptographic functions but
12 also discuss a little how to build security mechanisms from that.
13 So you will also be introduced to the basic "modes of operation".
15 1. What a blockcipher does
16 A blockcipher is a algorithm which turn an input of fixed length into an output
17 of the same length (enciphering or encrypting). The transformation is specified
18 by a key which has to be of a fixed length, or a length of a given set or
20 Generally there is also an algorithm which turns the output back to the
21 previous input (deciphering or decrypting) when supplied with te same key.
23 1.1. high frequent parameters:
24 block size: 64 bits, 128 bits
25 key size: 64 bits, 80 bits, 128 bits, 192 bits, 256 bits
26 (note that some blockciphers use different sizes)
28 2. Parts of a blockcipher
29 * encryption algorithm
30 * decryption algorithm
31 * mostly a set of subkeys
32 * mostly a keyschedule which generates the subkeys from the supplied key.
33 As we can see here a blockcipher normally has an algortihm besides the
34 encryption and decryption algorithm, which we call keyschedule.
35 Mostly the encryption and decryption algorithm consist of multiple rounds,
36 where each round (and sometimes between rounds) subkeys are needed to modify
37 the data. This subkeys are generated by the keyschedule and stored in a state
39 Note that not all algorithms need a pregenerated context, sometimes it is easy
40 to generate the subkeys "on the fly" so there is not always the need of a
44 The API is not always consistent due to the fact that we tried to optimize the
45 code for size (flash, heap and stack) and speed (runtime of the different
47 Generally the API of the implemented blockciphers consists of:
49 *_init function, which implements the keyschedule
50 *_enc function, which implements the encryption algorithm
51 *_dec function, which implements the decryption algorithm
52 *_free function, which frees memory allocated for the keyschedule
53 *_ctx_t context type, which can contain a keyschdule and other information
55 3.1 look at the prototypes
56 Generally the prototypes (defined in the *.h files) will tell you what
59 3.1.2 sizes in bits and bytes
60 Working with cryptographical functions involves working with different lengths.
61 Some times you want to know it in bits and sometimes in bytes. To reduce
62 frustration and to avoid bugs we suffix a length parameter with either _b or _B
63 depending on the meaning. _b means in bits and _B means in bytes
67 The *_init function generally takes a pointer to the key as first parameter.
68 For ciphers where the keysize is not fixed the second parameter gives the
69 keysize (in bits regularly) and the last parameter points to the context
71 For some ciphers there are additonal parameters like the number of rounds,
72 these parameters generally occur before the context pointer.
74 3.3. *_enc and *_dec functions
75 The encryption and decryption function of a specific algorithm normally do not
76 differ in their parameters. Generally these functions take a pointer to the
77 block to operate on. Some ciphers allow to specify two blocks, where the first
78 one will be written to and the scound will contain the source block. The two
79 blocks may overlap or be the same. The last parameter specifies either the key
80 direct (with a pointer to it) or is a pointer to a context created with the
84 A *_free function is only provided where needed (so most ciphers do not have
85 it). It is used to free memory dynamically allocated by the *_init function.
88 The usage of cryptographic algorithms is usually motivated by the intend to
89 fight potential threads. Blockciphers are generally good building blocks. There
90 are different attacks to the cipher itself, but this is work to be done by
91 cryptographers, but what stays up to you is using this building blocks in a
93 You may read http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation to
96 4.1. ECB (electronic codebook mode)
97 Electronic codebook mode is the simplest mode of operation and its usages is
98 generally not suggested. In ECB-mode a message which is to encrypt is simply
99 split up in blocks and each block gets indipendently encrypted. The problem
100 with this mode is that, for example same data produces the same ciphertext,
101 which may also allows an attacke to inject selected data.
103 +----+ +----+ +----+ +----+ +----+ +----+
104 | P1 | | P2 | | P3 | | C1 | | C2 | | C3 |
105 +----+ +----+ +----+ +----+ +----+ +----+
108 o---o o---o o---o o---o o---o o---o
109 | E | | E | | E | | D | | D | | D |
110 o---o o---o o---o o---o o---o o---o
113 +----+ +----+ +----+ +----+ +----+ +----+
114 | C1 | | C2 | | C3 | | P1 | | P2 | | P3 |
115 +----+ +----+ +----+ +----+ +----+ +----+
117 4.2. CBC (chipher-block-chaining mode)
118 CBC-mode is a more advanced mode of opration. It solves most problems of
119 ECB-mode. It again works by spliting up the message into blocks and intoducing
120 a initialisation vector (IV) at the beginning. The IV should be randomly
121 generated and is not required to be kept secret. The plaintext of each block
122 is XORed with the ciphertext of the previous block (the first block is XORed
123 with the IV) and then gets encrypted producing the ciphertext block.
124 For decryption of a block simply decrypt the block an XOR it with the previous
125 ciphertext block (or the IV in the case of the first block).
126 CBC-mode has some properties which make it quite useles for some application.
127 For example if you want to store a large amount of data, and you want to make
128 a change in one block you would have to decrypt and reencrypt all follwing
129 blocks. If you have such a case read more about block cipher modes.
130 The wikipedia article http://en.wikipedia.org/wiki/Block_cipher_modes_of_
131 operation#Other_modes_and_other_cryptographic_primitives would make a good
134 +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+
135 | IV | | P1 | | P2 | | P3 | | IV | | C1 | | C2 | | C3 |
136 +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+
138 +------> X +--> X +--> X | +---+ +---+ |
139 | | | | | | | | | | | |
140 | V | V | V | V | V | V
141 | o---o | o---o | o---o | o---o | o---o | o---o
142 | | E | | | E | | | E | | | D | | | D | | | D |
143 | o---o | o---o | o---o | o---o | o---o | o---o
144 | | | | | | | | | | | |
145 | +---+ +---+ + +------> X +--> X +--> X
148 +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+
149 | IV | | C1 | | C2 | | C3 | | IV | | P1 | | P2 | | P3 |
150 +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+
152 4.3. stream cipher modes
153 The following modes of operation turn the blockcipher in something better
154 described as stream cipher. So you may consider reading USAGE.streamciphers
155 or anything else about streamcipher if you wish to use this modes.
157 4.3.1. CTR (counter mode)
158 This is quite simple. You use a counter which gets encrypted to produce a
159 key stream. This key stream may be used to encrypt data by XORing the plaintext
160 with the key stream. Decrypting is exactly the same then encrypting BE WARNED,
161 an attacker might flip a bit in the ciphertext and the corresponding bit in
162 the plaintext gets fliped.
164 +---------+ o--o +---------+ o--o +---------+ o--o +---------+
165 | counter |-|+1|->| counter |-|+1|->| counter |-|+1|->| counter |
166 +---------+ o--o +---------+ o--o +---------+ o--o +---------+
169 o---o o---o o---o o---o
170 | E | | E | | E | | E |
171 o---o o---o o---o o---o
174 +--------+ +--------+ +--------+ +--------+
175 | key | | key | | key | | key |
176 | stream | | stream | | stream | | stream |
177 +--------+ +--------+ +--------+ +--------+
179 4.3.2 OFB (output-feedback mode)
180 OFB-mode is much like CTR-mode. In fact the only difference is that you do not
181 increment a counter, but use the output of the encrytption operation before as
184 +-------+ +-------+ +-------+
185 | IV | +---->| input | +---->| input |
186 +-------+ | +-------+ | +-------+
189 o---o | o---o | o---o
190 | E | | | E | | | E |
191 o---o | o---o | o---o
194 +--------+ | +--------+ | +--------+
195 | output |--+ | output |--+ | output |
196 +--------+ +--------+ +--------+
199 +--------+ +--------+ +--------+
200 | key | | key | | key |
201 | stream | | stream | | stream |
202 +--------+ +--------+ +--------+
204 4.3.2 CFB (cipher-feedback mode)
205 CFB-mode looks much like OFB-mode, but it has a lot of different properties.
206 Instead of using the previous output block as input the resultig ciphertext is
207 used as input. Due to the fact that not the entire outputblock needs to be
208 used, the ciphertext does not form the entire input block for the next
209 operation but it is shifted in the input block.
210 The resulting cipher is something known as self synchonising stream cipher.
211 This means that a manipulation of a single bit in the ciphertext will result
212 in this bit flipped in the corresponding plaintext but the following blocks
213 will be "destroyed" until the cipher "heald" itself, meaning the manipulated
214 ciphertext block gets shift out of the input block.
217 +-------+ +-------+ +-------+
218 | IV | +--------->>| input | +--------->>| input |
219 +-------+ | +-------+ | +-------+
222 o---o | o---o | o---o
223 | E | | | E | | | E |
224 o---o | o---o | o---o
227 +--------+ | +--------+ | +--------+
228 | output | | | output | | | output |
229 +--------+ | +--------+ | +--------+
231 +----+ V +----+ +----+ V +----+ +----+ V +----+
232 | P1 |-->X-->| C1 | | P2 |-->X-->| C2 | | P3 |-->X-->| C3 |
233 +----+ +----+ +----+ +----+ +----+ +----+
236 +-------------+ +-------------+
237 | +-------+ | | +-------+ | +-------+
238 | | IV | +---------|>>| input | +-------->>| input |
239 | +-------+ | +-------+ +-------+
242 | o---o | o---o o---o
243 | | E | | | E | | E |
244 | o---o | o---o o---o
247 | +--------+ | +--------+ +--------+
248 | | output | | | output | | output |
249 | +--------+ | +--------+ +--------+
251 +----+ V +----+ +----+ V +----+ +----+ V +----+
252 | C1 |-->X-->| P1 | | C2 |-->X-->| P2 | | C3 |-->X-->| P3 |
253 +----+ +----+ +----+ +----+ +----+ +----+