You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

#### 254 lines 13 KiB Raw Permalink Blame History

 `===================================` `= Usage of blockciphers = ` `===================================` ``` ``` `Author: Daniel Otte` `email: bg@nerilex.org` ` ` ` ` `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 algorithm 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 keyschedule 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 the context` ` variable to fill.` ` For some ciphers there are additional 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 second 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 manner.` ` 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 independently encrypted. The problem ` ` with this mode is that, for example same data produces the same ciphertext, ` ` which may also allows an attack 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 operation. It solves most problems of ` ` ECB-mode. It again works by split ing up the message into blocks and ` ` introducing a initialization 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 useless 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 re-encrypt all following` ` 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 XOR-ing 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 flipped. ` ``` ``` ` +---------+ 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 encryption 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 resulting ciphertext ` ` is used as input. Due to the fact that not the entire output-block 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 synchronizing stream cipher.` ` This means that a manipulation of a single bit in the ciphertext will result` ` in this bit flipped in the corresponding plaintext but the following blocks ` ` will be "destroyed" until the cipher "heald" 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 |` ` +----+ +----+ +----+ +----+ +----+ +----+` ``` ``` ``` ```