adding preleminary documentation

diff --git a/doc/acl-guide.texi b/doc/acl-guide.texi
new file mode 100644 (file)
index 0000000..6855f88
--- /dev/null
+++ b/doc/acl-guide.texi
@@ -0,0 +1,288 @@
+\input texinfo  @c -*-texinfo-*-
+@c %**start of header
+@setfilename acl-manual.info
+@settitle AVR/ARM-Crypto-Lib Manual 1.0
+@c %**end of header
+
+@copying
+This is a short example of a complete Texinfo file.
+Copyright © 2011 Daniel Otte
+@end copying
+
+@titlepage
+@title AVR/ARM-Crypto-Lib Manual 1.0
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+@c Output the table of the contents at the beginning.
+@contents
+@ifnottex
+@node Top
+@top GNU Sample
+@insertcopying
+@end ifnottex
+
+@chapter About
+This documentation is a guide to the AVR-Crypto-Lib and ARM-Crypto-Lib.
+Instead of documenting the full API and each function we choose the approach
+of documenting the structure of the API so you know what to do when you want
+to use the library.
+
+@chapter Generic stuff
+@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, ...).
+
+ @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
+
+
+
+@section Modes of operation
+
+@section Stream ciphers
+@subsection List of available stream ciphers
+@subsection API of stream ciphers
+@subsection Stream cipher abstraction layer (SCAL)
+
+@section Hash functions
+@subsection List of available hash functions
+@subsection API of hash functions
+@subsection Hash function abstraction layer (HFAL)
+
+@section MAC functions
+@section Pseudo random number generators (PRNGs)
+
+@chapter Encodings
+@section Base64
+@section ASN.1
+
+@chapter Big integer functions
+
+@chapter Asymmetric Primitives
+@section DSA
+@section RSA
+@section El-Gamal
+@section MQQ
+
+@bye
+