-@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.
-
-@subsubsection *_ctx_t type
- A variable of the *_ctx_t type may hold information needed by the *_enc or
- *_dec function. It is initialized by the *_init function. If dynamic memory is
- allocated by the *_init function also a *_free function is provided which frees
- the allocated memory. An initialized *_ctx_t variable may not be copied as it
- may contains pointers to itself.
-
-@section Block cipher abstraction layer (BCAL)
-The BlockCipeherAbstractionLayer (BCAL) is an abstraction layer which allows
-usage of all implemented block ciphers in a simple way. It abstracts specific
-function details and is suitable for implementations which want to be flexible
-in the choosing of specific block ciphers. Another important aspect is that this
-abstraction layer enables the implementation of block cipher operating modes
-independently from concrete ciphers. It is very simple to use and reassembles
-the API used to implement individual ciphers.
-
-The main component is a block cipher descriptor which contains the details of
-the individual ciphers.
-
-Care should be taken when choosing a specific keysize. It may be the case that
-the chosen keysize is not compatible with the chosen block cipher.
-
-
-@subsection Parts of BCAL
-The BCAL is split up in different parts:
-@itemize @bullet
- @item BCAL declaration for BCAL decriptors
- @item algorithm specific definitions of BCAL decriptors
- @item BCAL basic context type
- @item BCAL basic functions
-@end itemize
-
-@subsubsection BCAL declaration for BCAL decriptors
-The BCAL descriptor is a structure which is usually placed in FLASH or ROM since
-modification is unnecessary. It contains all information required to use the
-according block cipher.
-
-@verbatim
-typedef struct {
- uint8_t type; /* 1==block cipher */
- uint8_t flags;
- PGM_P name;
- uint16_t ctxsize_B;
- uint16_t blocksize_b;
- bc_init_fpt init;
- bc_enc_fpt enc;
- bc_dec_fpt dec;
- bc_free_fpt free;
- PGM_VOID_P valid_keysize_desc;
-} bcdesc_t; /* block cipher descriptor type */
-@end verbatim
-
-@table @var
- @item type
- should be set to @samp{1} to indicate that this descriptor is for a
- block cipher.
-
- @item flags
- defines what kind of init function is provided and what kind of decrypt
- and encrypt functions are provided.
-
- @table @asis
- @item bit 0
- if clear (@samp{0}) designates an init function with fixed key length, so
- the length parameter is omitted (@code{init(void* ctx, void* key)}).
-
- if set (@samp{1}) designates an init function which requires an explicit
- keysize argument (@code{init(void*ctx, uint16_t length_b, void* key)}).
-
- @item bit 1
- if clear (@samp{0}) designates that the encryption function transforms the
- plaintext block in place to the ciphertext (@code{enc(void* block, void* ctx)}).
-
- if set (@samp{1}) designates that the encryption function offers a dedicated
- pointers for input and output. The two regions may be the same
- (@code{enc(void* out, void* in, void*ctx)}).
-
- @item bit 2
- if clear (@samp{0}) designates that the decryption function transforms the
- ciphertext block in place to the plaintext (@code{dec(void* block, void* ctx)}).
-
- if set (@samp{1}) designates that the decryption function offers a dedicated
- pointers for input and output. The two regions may be the same
- (@code{dec(void* out, void* in, void*ctx)}).
- @end table
-
- @item name
- is a pointer to a zero terminated ASCII string giving the name of the
- implemented primitive. On targets with Harvard-architecture the string resides
- in code memory (FLASH, ROM, ...).