@c acl_blockcipher.texi

@section Block ciphers
 A block cipher is a algorithm which turns 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

@subsection 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

@subsection 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



@subsection 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:
@subsubsection @code{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

@subsubsection @code{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.

@subsubsection @code{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.

@subsubsection @code{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.

@subsubsection @code{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).

@subsubsection @code{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).



