+@c acl_blockcipher.texi
+
+@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:
+@table @asis
+ @item block size
+ 64 bits, 128 bits
+ @item key size
+ 64 bits, 80 bits, 128 bits, 192 bits, 256 bits
+ (note that some block ciphers use different sizes)
+@end table
+
+@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:
+@table @code
+ @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 table
+@subsubsection @code{*_init} function
+ The @code{*_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 @code{*_enc} and @code{*_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 @code{*_enc} function is
+ called) or decrypted (if the @code{*_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 @code{*_init} function.
+ It is guaranteed that the context is in the same state as before the *_enc or
+ @code{*_dec} function call. Most @code{*_enc} and @code{*_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 @code{*_free} function
+ A @code{*_free} function is only provided where needed (so most ciphers do not have
+ it). It is used to free memory dynamically allocated by the @code{*_init} function.
+
+@subsubsection *_ctx_t type
+ A variable of the @code{*_ctx_t} type may hold information needed by the @code{*_enc} or
+ @code{*_dec} function. It is initialized by the @code{*_init} function. If dynamic memory is
+ allocated by the @code{*_init} function also a @code{*_free} function is provided which frees
+ the allocated memory. An initialized @code{*_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, ...).
+
+ @item ctxsize_B
+ is the number of bytes which should be allocated for the context variable.
+
+ @item blocksize_b
+ is the number of bits on which the encrypt and decrypt function work on.
+
+ @item init
+ is a pointer to the init function (see @samp{flags} how the init function
+ should be called). If there is no init function this field is NULL.
+
+ @item enc
+ is a pointer to the encryption function (see @samp{flags} how the encryption
+ function should be called).
+
+ @item dec
+ is a pointer to the decryption function (see @samp{flags} how the decryption
+ function should be called).
+
+ @item free
+ is a pointer to the free function or NULL if there is no free function.
+
+ @item valid_keysize_desc
+ is a pointer to a keysize descriptor structure which is used to validate
+ that the chosen keysize is valid
+@end table
+
+@subsubsection BCAL-Basic context
+Besides the context types for individual ciphers there is a generic context
+type for BCAL. This is the context to use when using BCAL based functions.
+The BCAL context has the following structure:
+@verbatim
+typedef struct{
+ bcdesc_t* desc_ptr;
+ uint16_t keysize;
+ void* ctx;
+} bcgen_ctx_t;
+@end verbatim
+@table @code
+@item desc_ptr
+a pointer to the BCAL descriptor
+@item keysize
+the chosen keysize
+@item ctx
+pointer to the cipher specific context
+@end table
+
+
+
+@subsubsection BCAL-Basic
+BCAL-Basic provides the basic features of an block cipher on top of the
+BCAL. To use it you simply have to include the algorithms you want to use,
+the BCAL descriptor file and of course the BCAL-Basic implementation.
+
+The following functions are provided:
+@table @code
+@item bcal_cipher_init
+@code{uint8_t bcal_cipher_init(const bcdesc_t* cipher_descriptor, const void* key, uint16_t keysize_b, bcgen_ctx_t* ctx)}
+ this function initializes a BCAL context based on the given BCAL descriptor
+ pointer (first parameter) with a given key (second parameter) of a given length
+ (third parameter). The context to initialize is designated by the pointer
+ passed as fourth parameter.
+
+ If everything works fine @samp{0} is returned. In the case something fails
+ the following codes are returned:
+@table @samp
+ @item 1
+ The specified keysize is not available with this cipher
+ @item 2
+ It was not possible to allocate enough memory to hold the key.
+ (This is returned when there is no actual init function and you ran out
+ of memory)
+ @item 3
+ It was not possible to allocate enough memory to hold the context variable
+ for the selected cipher.
+@end table
+
+@item bcal_cipher_free
+@code{void bcal_cipher_free(bcgen_ctx_t* ctx)} this function frees the memory
+allocated by the init function and should be called whenever you are finished
+with BCAL context. It automatically also calls the @code{free} function if
+necessary.
+
+@item bcal_cipher_enc
+@code{void bcal_cipher_enc(void* block, const bcgen_ctx_t* ctx)}
+this function encrypts a block in-place using a given BCAL contex.
+
+@item bcal_cipher_dec
+@code{void bcal_cipher_dec(void* block, const bcgen_ctx_t* ctx)}
+this function decrypts a block in-place using a given BCAL contex.
+
+@item bcal_cipher_getBlocksize_b
+@code{uint16_t bcal_cipher_getBlocksize_b(const bcdesc_t* desc)}
+this function returns the block size of a given cipher by using the BCAL
+descriptor (to which a pointer must be passed).
+
+@item bcal_cipher_getKeysizeDesc
+@code{PGM_VOID_P bcal_cipher_getKeysizeDesc(const bcdesc_t* desc)}
+this function returns a pointer to the keysize descriptor of a given cipher by
+using the BCAL descriptor (to which a pointer must be passed).
+
+@end table
+
+@subsection Keysize descriptors
+There are a lot of different block ciphers or cryptographic algorithms in
+general which put several constrains to the number of bits which can be used
+as key.
+
+Our approach is to find a simple and compact way do specify which lengths are
+valid and which are not. The system is quite simple, we use a list of patterns
+(with parameters) and if any matches the keysize is valid, if none matches the
+keysize is unsupported.
+
+The patterns are:
+@itemize @bullet
+@item simple list of valid keysizes
+@item range of keysizes
+@item augmented range of keysizes
+@end itemize
+
+@subsubsection simple list of valid keysizes
+The simple keysize list has the following structure:
+@verbatim
+typedef struct{ /* keysize is valid if listed in items */
+ uint8_t n_items; /* number of items (value 0 is reserved) */
+ uint16_t items[]; /* list of valid lengths */
+}keysize_desc_list_t;
+@end verbatim
+First we specify how many keysizes we want to declare valid (this is limited to
+255 keysizes but that should not impose any real world constrains). And follow
+it by the keysizes as 16bit unsigned values.
+
+If you want to declare a lot of keys please check first the other methods since
+they may give a more compact definition.
+
+@subsubsection range of keysizes
+This method specifies an entire range of keys a valid using the following
+structure:
+@verbatim
+typedef struct{ /* keysize is valid if min<=keysize<=max */
+ uint16_t min;
+ uint16_t max;
+}keysize_desc_range_t;
+@end verbatim
+So all keysizes between @code{min} and @code{max} (including @code{min} and
+@code{max}) are valid. Please note that in most cases also keysizes which
+are not a multiple of 8 (so are not full bytes) are also matched.
+If you want to avoid this see the augmented range of keysizes.
+
+@subsubsection augmented range of keysizes
+The augmented range of keysizes uses the following structure:
+@verbatim
+typedef struct{ /* keysize is valid if min<=keysize<=max and if keysize mod distance == offset */
+ uint16_t min;
+ uint16_t max;
+ uint16_t distance;
+ uint16_t offset;
+}keysize_desc_arg_range_t;
+@end verbatim
+The restriction to a range is the same as with the simpler range of keysizes,
+but also another restriction is imposed. A valid keysize must have a reminder
+of @code{offset} when divided by @code{distance}. So you can limit a keysize
+to full bytes by simply setting @code{distance} to @samp{8} and @code{offset}
+to @samp{0}.
+
+@subsubsection the actual descriptor
+The keysize descriptor is a list of the former patterns. Each pattern is
+preceded by byte designating the type of pattern and the list is terminated
+by a @code{NULL} byte.
+
+The designator byte can have one of the following values:
+@table @samp
+@item 0x00
+Terminator byte, signals the end of the list
+@item 0x01
+simple list of keysizes
+@item 0x02
+simple range of keysizes
+@item 0x03
+augmented range of keysizes
+@end table
+
+