fixed typos in documentation
This commit is contained in:
parent
00b7eb605c
commit
5ea7340f82
|
@ -8,15 +8,15 @@ email: daniel.otte@rub.de
|
||||||
|
|
||||||
0. Foreword
|
0. Foreword
|
||||||
This file will describe how to use the blockcipher implementations provided by
|
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
|
this library. It will not only show how to call the cryptographic functions
|
||||||
also discuss a little how to build security mechanisms from that.
|
but also discuss a little how to build security mechanisms from that.
|
||||||
So you will also be introduced to the basic "modes of operation".
|
So you will also be introduced to the basic "modes of operation".
|
||||||
|
|
||||||
1. What a blockcipher does
|
1. What a blockcipher does
|
||||||
A blockcipher is a algorithm which turn an input of fixed length into an output
|
A blockcipher is a algorithm which turn an input of fixed length into an
|
||||||
of the same length (enciphering or encrypting). The transformation is specified
|
output of the same length (enciphering or encrypting). The transformation is
|
||||||
by a key which has to be of a fixed length, or a length of a given set or
|
specified by a key which has to be of a fixed length, or a length of a given
|
||||||
range.
|
set or range.
|
||||||
Generally there is also an algorithm which turns the output back to the
|
Generally there is also an algorithm which turns the output back to the
|
||||||
previous input (deciphering or decrypting) when supplied with te same key.
|
previous input (deciphering or decrypting) when supplied with te same key.
|
||||||
|
|
||||||
|
@ -30,7 +30,7 @@ email: daniel.otte@rub.de
|
||||||
* decryption algorithm
|
* decryption algorithm
|
||||||
* mostly a set of subkeys
|
* mostly a set of subkeys
|
||||||
* mostly a keyschedule which generates the subkeys from the supplied key.
|
* mostly a keyschedule which generates the subkeys from the supplied key.
|
||||||
As we can see here a blockcipher normally has an algortihm besides the
|
As we can see here a blockcipher normally has an algorithm besides the
|
||||||
encryption and decryption algorithm, which we call keyschedule.
|
encryption and decryption algorithm, which we call keyschedule.
|
||||||
Mostly the encryption and decryption algorithm consist of multiple rounds,
|
Mostly the encryption and decryption algorithm consist of multiple rounds,
|
||||||
where each round (and sometimes between rounds) subkeys are needed to modify
|
where each round (and sometimes between rounds) subkeys are needed to modify
|
||||||
|
@ -50,17 +50,17 @@ email: daniel.otte@rub.de
|
||||||
*_enc function, which implements the encryption algorithm
|
*_enc function, which implements the encryption algorithm
|
||||||
*_dec function, which implements the decryption algorithm
|
*_dec function, which implements the decryption algorithm
|
||||||
*_free function, which frees memory allocated for the keyschedule
|
*_free function, which frees memory allocated for the keyschedule
|
||||||
*_ctx_t context type, which can contain a keyschdule and other information
|
*_ctx_t context type, which can contain a keyschedule and other information
|
||||||
|
|
||||||
3.1 look at the prototypes
|
3.1 look at the prototypes
|
||||||
Generally the prototypes (defined in the *.h files) will tell you what
|
Generally the prototypes (defined in the *.h files) will tell you what
|
||||||
parameter means what.
|
parameter means what.
|
||||||
|
|
||||||
3.1.2 sizes in bits and bytes
|
3.1.2 sizes in bits and bytes
|
||||||
Working with cryptographical functions involves working with different lengths.
|
Working with cryptographical functions involves working with different
|
||||||
Some times you want to know it in bits and sometimes in bytes. To reduce
|
lengths. Some times you want to know it in bits and sometimes in bytes. To
|
||||||
frustration and to avoid bugs we suffix a length parameter with either _b or _B
|
reduce frustration and to avoid bugs we suffix a length parameter with either
|
||||||
depending on the meaning. _b means in bits and _B means in bytes
|
_b or _B depending on the meaning. _b means in bits and _B means in bytes
|
||||||
(big b big word).
|
(big b big word).
|
||||||
|
|
||||||
3.2. *_init function
|
3.2. *_init function
|
||||||
|
@ -68,14 +68,14 @@ email: daniel.otte@rub.de
|
||||||
For ciphers where the keysize is not fixed the second parameter gives the
|
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
|
keysize (in bits regularly) and the last parameter points to the context
|
||||||
variable to fill.
|
variable to fill.
|
||||||
For some ciphers there are additonal parameters like the number of rounds,
|
For some ciphers there are additional parameters like the number of rounds,
|
||||||
these parameters generally occur before the context pointer.
|
these parameters generally occur before the context pointer.
|
||||||
|
|
||||||
3.3. *_enc and *_dec functions
|
3.3. *_enc and *_dec functions
|
||||||
The encryption and decryption function of a specific algorithm normally do not
|
The encryption and decryption function of a specific algorithm normally do not
|
||||||
differ in their parameters. Generally these functions take a pointer to the
|
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
|
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
|
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
|
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
|
direct (with a pointer to it) or is a pointer to a context created with the
|
||||||
*_init function.
|
*_init function.
|
||||||
|
@ -86,19 +86,19 @@ email: daniel.otte@rub.de
|
||||||
|
|
||||||
4. modes of operation
|
4. modes of operation
|
||||||
The usage of cryptographic algorithms is usually motivated by the intend to
|
The usage of cryptographic algorithms is usually motivated by the intend to
|
||||||
fight potential threads. Blockciphers are generally good building blocks. There
|
fight potential threads. Blockciphers are generally good building blocks.
|
||||||
are different attacks to the cipher itself, but this is work to be done by
|
There are different attacks to the cipher itself, but this is work to be done
|
||||||
cryptographers, but what stays up to you is using this building blocks in a
|
by cryptographers, but what stays up to you is using this building blocks in a
|
||||||
secure maner.
|
secure manner.
|
||||||
You may read http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation to
|
You may read http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation to
|
||||||
learn more.
|
learn more.
|
||||||
|
|
||||||
4.1. ECB (electronic codebook mode)
|
4.1. ECB (electronic codebook mode)
|
||||||
Electronic codebook mode is the simplest mode of operation and its usages is
|
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
|
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
|
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,
|
with this mode is that, for example same data produces the same ciphertext,
|
||||||
which may also allows an attacke to inject selected data.
|
which may also allows an attack to inject selected data.
|
||||||
|
|
||||||
+----+ +----+ +----+ +----+ +----+ +----+
|
+----+ +----+ +----+ +----+ +----+ +----+
|
||||||
| P1 | | P2 | | P3 | | C1 | | C2 | | C3 |
|
| P1 | | P2 | | P3 | | C1 | | C2 | | C3 |
|
||||||
|
@ -115,17 +115,17 @@ email: daniel.otte@rub.de
|
||||||
+----+ +----+ +----+ +----+ +----+ +----+
|
+----+ +----+ +----+ +----+ +----+ +----+
|
||||||
|
|
||||||
4.2. CBC (chipher-block-chaining mode)
|
4.2. CBC (chipher-block-chaining mode)
|
||||||
CBC-mode is a more advanced mode of opration. It solves most problems of
|
CBC-mode is a more advanced mode of operation. It solves most problems of
|
||||||
ECB-mode. It again works by spliting up the message into blocks and intoducing
|
ECB-mode. It again works by split ing up the message into blocks and
|
||||||
a initialisation vector (IV) at the beginning. The IV should be randomly
|
introducing a initialization vector (IV) at the beginning. The IV should be
|
||||||
generated and is not required to be kept secret. The plaintext of each block
|
randomly generated and is not required to be kept secret. The plaintext of
|
||||||
is XORed with the ciphertext of the previous block (the first block is XORed
|
each block is XORed with the ciphertext of the previous block (the first block
|
||||||
with the IV) and then gets encrypted producing the ciphertext 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
|
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).
|
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.
|
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
|
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
|
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.
|
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_
|
The wikipedia article http://en.wikipedia.org/wiki/Block_cipher_modes_of_
|
||||||
operation#Other_modes_and_other_cryptographic_primitives would make a good
|
operation#Other_modes_and_other_cryptographic_primitives would make a good
|
||||||
|
@ -156,10 +156,10 @@ email: daniel.otte@rub.de
|
||||||
|
|
||||||
4.3.1. CTR (counter mode)
|
4.3.1. CTR (counter mode)
|
||||||
This is quite simple. You use a counter which gets encrypted to produce a
|
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
|
key stream. This key stream may be used to encrypt data by XOR-ing the
|
||||||
with the key stream. Decrypting is exactly the same then encrypting BE WARNED,
|
plaintext with the key stream. Decrypting is exactly the same then encrypting
|
||||||
an attacker might flip a bit in the ciphertext and the corresponding bit in
|
BE WARNED, an attacker might flip a bit in the ciphertext and the
|
||||||
the plaintext gets fliped.
|
corresponding bit in the plaintext gets flipped.
|
||||||
|
|
||||||
+---------+ o--o +---------+ o--o +---------+ o--o +---------+
|
+---------+ o--o +---------+ o--o +---------+ o--o +---------+
|
||||||
| counter |-|+1|->| counter |-|+1|->| counter |-|+1|->| counter |
|
| counter |-|+1|->| counter |-|+1|->| counter |-|+1|->| counter |
|
||||||
|
@ -178,7 +178,7 @@ email: daniel.otte@rub.de
|
||||||
|
|
||||||
4.3.2 OFB (output-feedback mode)
|
4.3.2 OFB (output-feedback mode)
|
||||||
OFB-mode is much like CTR-mode. In fact the only difference is that you do not
|
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
|
increment a counter, but use the output of the encryption operation before as
|
||||||
input.
|
input.
|
||||||
|
|
||||||
+-------+ +-------+ +-------+
|
+-------+ +-------+ +-------+
|
||||||
|
@ -203,11 +203,11 @@ email: daniel.otte@rub.de
|
||||||
|
|
||||||
4.3.2 CFB (cipher-feedback mode)
|
4.3.2 CFB (cipher-feedback mode)
|
||||||
CFB-mode looks much like OFB-mode, but it has a lot of different properties.
|
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
|
Instead of using the previous output block as input the resulting ciphertext
|
||||||
used as input. Due to the fact that not the entire outputblock needs to be
|
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
|
used, the ciphertext does not form the entire input block for the next
|
||||||
operation but it is shifted in the input block.
|
operation but it is shifted in the input block.
|
||||||
The resulting cipher is something known as self synchonising stream cipher.
|
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
|
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
|
in this bit flipped in the corresponding plaintext but the following blocks
|
||||||
will be "destroyed" until the cipher "heald" itself, meaning the manipulated
|
will be "destroyed" until the cipher "heald" itself, meaning the manipulated
|
||||||
|
|
|
@ -0,0 +1,76 @@
|
||||||
|
===================================
|
||||||
|
= Usage of hash functions =
|
||||||
|
===================================
|
||||||
|
|
||||||
|
Author: Daniel Otte
|
||||||
|
email: daniel.otte@rub.de
|
||||||
|
|
||||||
|
|
||||||
|
0. Foreword
|
||||||
|
This file will describe how to use the hash function implementations provided
|
||||||
|
by this library.
|
||||||
|
|
||||||
|
1. What a hash function does
|
||||||
|
A hash function is an algorithm to map an arbitrary long message (in the form
|
||||||
|
of a bit string) to a fixed length message digest or hash value.
|
||||||
|
The hash function aims to be collision free, which means that it is not
|
||||||
|
practicable to find two messages with the same hash value (although this
|
||||||
|
collision must exist). Also it should not be practicable to construct a
|
||||||
|
message which maps to a given hash value.
|
||||||
|
|
||||||
|
|
||||||
|
1.1. high frequent parameters:
|
||||||
|
block size: 512 bits
|
||||||
|
hash value size: 128 bits, 160 bits, 224 bits, 256 bits, 384 bits, 512 bits
|
||||||
|
|
||||||
|
2. Parts of a hash function
|
||||||
|
* initialization function
|
||||||
|
* compression algorithm
|
||||||
|
* finalization function
|
||||||
|
|
||||||
|
3. block cipher 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 block ciphers consists of:
|
||||||
|
|
||||||
|
*_init function, which implements the keyschedule
|
||||||
|
*_nextBlock function, which implements the compression algorithm
|
||||||
|
*_lastBlock function, which implements the the padding algorithm
|
||||||
|
*_ctx2hash function, which turns a context into an actual hash value
|
||||||
|
*_ctx_t context type, which can contains the state of a hashing process
|
||||||
|
|
||||||
|
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 context as parameter.
|
||||||
|
This function initializes the context with algorithm specific values.
|
||||||
|
|
||||||
|
3.3. *_nexBlock function
|
||||||
|
The *nextBlock function is the core of each hash function. It updates the hash
|
||||||
|
state with a given message block. So this function uses a context pointer and
|
||||||
|
a message pointer as parameters. The size of a message block is fixed for each
|
||||||
|
hash function (mostly 512 bit). For the last block of a messages which may be
|
||||||
|
smaller than the blocksize you have to use the *_lastBlock function described
|
||||||
|
below.
|
||||||
|
|
||||||
|
3.4 *_lastBlock function
|
||||||
|
The *_lastBlock function finalizes the context with the last bits of a
|
||||||
|
message. Since the last block is not required to have the blocksize you have
|
||||||
|
to specify the length of the last block (normally in bits). This function
|
||||||
|
performs the padding and final processing.
|
||||||
|
|
||||||
|
3.5. *_ctx2hash function
|
||||||
|
The *_ctx2hash function turns a given hash context into an actual hash value.
|
||||||
|
If multiple sized hash value may be created from a context it is necessary to
|
||||||
|
give the the size of the hash value as parameter.
|
||||||
|
|
|
@ -7,29 +7,29 @@ email: daniel.otte@rub.de
|
||||||
|
|
||||||
|
|
||||||
0. Foreword
|
0. Foreword
|
||||||
This file will describe how to use the streramcipher implementations provided
|
This file will describe how to use the streamcipher implementations provided
|
||||||
by this library. It will not only show how to call the cryptographic functions
|
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.
|
but also discuss a little how to build security mechanisms from that.
|
||||||
|
|
||||||
1. What a streamcipher does
|
1. What a streamcipher does
|
||||||
A streamcipher normaly generates a deterministic, random looking stream of
|
A streamcipher normally generates a deterministic, random looking stream of
|
||||||
bits, known as keystream. For encryption purpose this keystream is XORed with
|
bits, known as keystream. For encryption purpose this keystream is XORed with
|
||||||
the data stream. So decryption is exactly the same as encryption. The
|
the data stream. So decryption is exactly the same as encryption. The
|
||||||
datastream is XORed with the keystream giving the plaintext. So both sides need
|
data-stream is XORed with the keystream giving the plaintext. So both sides
|
||||||
exactly the same streamcipher in the same state.
|
need exactly the same streamcipher in the same state.
|
||||||
|
|
||||||
1.1. high frequent parameters:
|
1.1. high frequent parameters:
|
||||||
outputsize: 8 bit, 1 bit
|
output-size: 8 bit, 1 bit
|
||||||
keysize: 64 bit, 80 bit, 128 bit
|
keysize: 64 bit, 80 bit, 128 bit
|
||||||
IVsize: 64 bit
|
IVsize: 64 bit
|
||||||
|
|
||||||
2. Parts of a streamcipher
|
2. Parts of a streamcipher
|
||||||
* generation algorithm
|
* generation algorithm
|
||||||
* initialisation algorithm
|
* initialization algorithm
|
||||||
* state
|
* state
|
||||||
As we can see all streamciphers seem to utilize an internal state which
|
As we can see all streamciphers seem to utilize an internal state which
|
||||||
determines the output. This state is initialized by the initialisation
|
determines the output. This state is initialized by the initialization
|
||||||
algorithm with a key and an IV (initialisation vector). It is very important
|
algorithm with a key and an IV (initialization vector). It is very important
|
||||||
for security that _never_ the same key with the same IV is used again. The
|
for security that _never_ the same key with the same IV is used again. The
|
||||||
IV is not required to be kept secret.
|
IV is not required to be kept secret.
|
||||||
|
|
||||||
|
@ -39,7 +39,7 @@ email: daniel.otte@rub.de
|
||||||
components).
|
components).
|
||||||
Generally the API of the implemented streamciphers consists of:
|
Generally the API of the implemented streamciphers consists of:
|
||||||
|
|
||||||
*_init function, which implements the initialisation
|
*_init function, which implements the initialization
|
||||||
*_gen function, which implements the streamcipher algorithm and generates a
|
*_gen function, which implements the streamcipher algorithm and generates a
|
||||||
keystream output
|
keystream output
|
||||||
*_ctx_t context type, which contains internal state information
|
*_ctx_t context type, which contains internal state information
|
||||||
|
@ -51,8 +51,8 @@ email: daniel.otte@rub.de
|
||||||
3.1.2 sizes in bits and bytes
|
3.1.2 sizes in bits and bytes
|
||||||
Working with cryptographical functions involves working with different lengths.
|
Working with cryptographical functions involves working with different lengths.
|
||||||
Some times you want to know it in bits and sometimes in bytes. To reduce
|
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
|
frustration and to avoid bugs we suffix a length parameter with either _b or
|
||||||
depending on the meaning. _b means in bits and _B means in bytes
|
_B depending on the meaning. _b means in bits and _B means in bytes
|
||||||
(big b big word).
|
(big b big word).
|
||||||
|
|
||||||
3.2. *_init function
|
3.2. *_init function
|
||||||
|
|
14
twister.c
14
twister.c
|
@ -29,18 +29,14 @@
|
||||||
# include "gf256mul.h"
|
# include "gf256mul.h"
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
static
|
|
||||||
void shiftrow(void* row, uint8_t shift){
|
|
||||||
*((uint64_t*)row) = *((uint64_t*)row)>>(8*shift) | *((uint64_t*)row)<<(64-8*shift);
|
|
||||||
}
|
|
||||||
|
|
||||||
#define MDS(a,b) pgm_read_byte(&(twister_mds[(a)][(b)]))
|
#define MDS(a,b) pgm_read_byte(&(twister_mds[(a)][(b)]))
|
||||||
|
|
||||||
#ifdef TWISTER_MUL_TABLE
|
#ifdef TWISTER_MUL_TABLE
|
||||||
# define MULT(a,b) pgm_read_byte(&(twister_multab[a][b]))
|
# define MULT(a,b) pgm_read_byte(&(twister_multab[(a)][(b)]))
|
||||||
#else
|
#else
|
||||||
# define MULT(a,b) gf256mul((a),(b), 0x4D)
|
# define MULT(a,b) gf256mul((a),(b), 0x4D)
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
void twister_blank_round(twister_state_t* ctx){
|
void twister_blank_round(twister_state_t* ctx){
|
||||||
uint8_t i,j,k=0;
|
uint8_t i,j,k=0;
|
||||||
uint8_t tmp[8][8];
|
uint8_t tmp[8][8];
|
||||||
|
@ -55,11 +51,7 @@ void twister_blank_round(twister_state_t* ctx){
|
||||||
tmp[i][j] = pgm_read_byte(twister_sbox+ctx->s[i][j]);
|
tmp[i][j] = pgm_read_byte(twister_sbox+ctx->s[i][j]);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
/* shift rows */
|
/* mix columns with integrates shift rows */
|
||||||
// for(i=1;i<8; ++i){
|
|
||||||
// shiftrow(&(tmp[i][0]), i);
|
|
||||||
// }
|
|
||||||
/* mix columns */
|
|
||||||
for( i=0; i<8; i++ ){
|
for( i=0; i<8; i++ ){
|
||||||
// multiply with mds matrix
|
// multiply with mds matrix
|
||||||
for( j=0; j<8; j++ ){
|
for( j=0; j<8; j++ ){
|
||||||
|
|
Loading…
Reference in New Issue