From 2ea8cb1426827f659035bc58cb6b743e73a110dd Mon Sep 17 00:00:00 2001 From: bg Date: Sat, 25 Jun 2011 22:32:29 +0000 Subject: [PATCH] adding preleminary documentation --- doc/acl-guide.texi | 288 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 doc/acl-guide.texi diff --git a/doc/acl-guide.texi b/doc/acl-guide.texi new file mode 100644 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 + -- 2.39.5