-@section File organisation
-@section Build process
-@section Testing system
-@section Sizes in bits and bytes
- Working with cryptographic functions involves working with different
- lengths. Some times you want to know it in bits, sometimes in bytes and another
- time in words (how long a word is must be defined by the context).
- To reduce confusion, frustration and to avoid bugs we suffix a length
- parameter with either _b, _B or _w depending on the meaning.
- _b means in bits and _B means in bytes (big b big word) and _w meaning words.
-
-@chapter Symmetric primitives
-
-@section Block ciphers
-@subsection What a block cipher does
- A block cipher 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 the same key.
-
-@subsection List of available block ciphers
-This is a list of the currently supported block ciphers:
-@itemize @bullet
- @item AES (Advanced Encryption Standard)
- @item Camellia
- @item CAST5
- @item CAST6
- @item CS-Cipher
- @item DES (Data Encryption Standard)
- @item Khazad
- @item Noekeon
- @item Present
- @item RC5
- @item RC6
- @item Seed
- @item Serpent (AES finalist)
- @item Shacal1
- @item Shacal2
- @item Skipjack
- @item TDES (Tripple DES)
- @item Threefish
- @item XTEA
-@end itemize
-
-@subsection high frequent parameters:
- block size: 64 bits, 128 bits
- key size: 64 bits, 80 bits, 128 bits, 192 bits, 256 bits
- (note that some block ciphers use different sizes)
-
-@subsection Parts of a block cipher
-@itemize @bullet
- @item encryption algorithm
- @item decryption algorithm
- @item mostly a set of subkeys
- @item mostly a keyschedule which generates the subkeys from the supplied key.
-@end itemize
- As we can see here a block cipher 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. In this case instead of a context the actual key is passed
- to the encryption and decryption function.
-
-@subsection API of block ciphers
- 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:
-@itemize @bullet
- @item *_init function, which implements the keyschedule
- @item *_enc function, which implements the encryption algorithm
- @item *_dec function, which implements the decryption algorithm
- @item *_free function, which frees memory allocated for the keyschedule
- @item *_ctx_t context type, which can contain a keyschedule and other information
-@end itemize
-@subsubsection *_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.
-
-@subsubsection *_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. Most ciphers have only one block pointer.
- The block specified by the pointer is encrypted (if the *_enc function is
- called) or decrypted (if the *_dec function is called).
- 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.
- It is guaranteed that the context is in the same state as before the *_enc or
- *_dec function call. Most *_enc and *_dec functions do not modify the context
- at all, but some do for reducing dynamic memory requirements. So here are some
- limitations to the reentrant property.
-
-@subsubsection *_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.