X-Git-Url: https://git.cryptolib.org/?p=avr-crypto-lib.git;a=blobdiff_plain;f=doc%2Facl-guide.texi;h=39a2b915f950f824e98c2f9acc90dc6d1d2f1336;hp=474c78c4d2d8f6e18248925cc53d705eedc0b969;hb=4e5b55fb1342fdef1603b68ea240b0778e665c1d;hpb=bcad01af2c86830bd59bd2fc719e81a7eaf2f13b diff --git a/doc/acl-guide.texi b/doc/acl-guide.texi index 474c78c..39a2b91 100644 --- a/doc/acl-guide.texi +++ b/doc/acl-guide.texi @@ -6,7 +6,7 @@ @copying This is a short example of a complete Texinfo file. -Copyright © 2011 Daniel Otte (@email{daniel.otte@@rub.de}) +Copyright © 2006-2015 Daniel Otte (@email{daniel.otte@@rub.de}) @end copying @titlepage @@ -30,317 +30,135 @@ 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, ...). +@section Requirements +You should have the following software tools to build the library, the version +mentioned is the version used on the test system, older or newer versions may +or may not work): +@table @asis + @item a recent toolchain + for AVR targets: + @table @asis + @item gcc for AVR (avr-gcc) + 4.3.5 + @item GNU binutils for AVR + 2.21 + @item avr-libc + 1.6.8-2 + @end table + for ARM targets: + @table @asis + @item gcc for ARM (arm-elf-gcc) + @item GNU binutils for ARM + @item newlib with enabled malloc() + @end table + @item a flash tool to program your device + for AVR targets: + @table @asis + @item avrdude + 5.10 + @end table + for ARM targets: + @table @asis + @item openocd + 0.4.0 + @end table + + @item GNU make + 3.81 + @item ruby (for the testing system) + 1.8.7.302-2 + @table @asis + @item rubygems + 1.3.7 + @item serialport + 1.0.4 + @item getopt + 1.4.0 + @end table +@end table - @item ctxsize_B - is the number of bytes which should be allocated for the context variable. +@section File organisation - @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. +@section Build process +The build process is managed by a large relative complex @file{Makefile} and +a bunch of more specific Makefile-stubs (@file{*.mk} in the @file{mkfiles} +directory). - @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. +@subsection make-stubs +All stubs are included by the main Makefile automatically, so the addition of +algorithms should not require modifications to the Makefile. - @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 +Because all stubs are included by the main Makefile you can use all features +of your make system when writing them. Currently we use GNU make and we +recommend using GNU make when building the crypto library. -@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: +Each algorithm implementation has its own stub. A stub looks like the following: @verbatim -typedef struct{ - bcdesc_t* desc_ptr; - uint16_t keysize; - void* ctx; -} bcgen_ctx_t; +# Makefile for AES +ALGO_NAME := AES128_C + +# comment out the following line for removement of AES from the build process +BLOCK_CIPHERS += $(ALGO_NAME) + +$(ALGO_NAME)_DIR := aes/ +$(ALGO_NAME)_INCDIR := gf256mul/ bcal/ +$(ALGO_NAME)_OBJ := aes_enc.o aes_dec.o aes_sbox.o aes_invsbox.o \ + aes_keyschedule.o gf256mul.o aes128_enc.o aes128_dec.o +$(ALGO_NAME)_TEST_BIN := main-aes128-test.o $(CLI_STD) $(BCAL_STD) \ + bcal_aes128.o +$(ALGO_NAME)_NESSIE_TEST := test nessie +$(ALGO_NAME)_PERFORMANCE_TEST := performance @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 - +The most important thing is defining an unambiguous name for the implementation, +in this case it is AES128_C. +The next step is chaining the implementation into a category. Uncategorized +implementations will be ignored. So if you want to exclude an implementation +from the build process you can simply comment out the line which chains it into +a category. -@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. +The following lines declare ''Attributes'' of the implementation. +@table @var +@item _DIR + defines the directory where the implementation resides +@item _INCDIR + defines directorys to search for additional files +@item _OBJ + defines the names of the objects which shoud be considered the implementations + core +@item _TESTBIN + defines the names of the objects required to build the test suit +@item _NESSIE_TEST + (currently unused) defines the string which should be send to the test system + to perform nessie standard tests +@item _NESSIE_TEST + (currently unused) defines the string which should be send to the test system + to perform a performance tests +@item _DEF + defines macros to use while compiling @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). +@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. -@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). +@chapter Symmetric primitives +@include acl_keysizes.texi +@include acl_blockciphers.texi -@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) +@include acl_streamciphers.texi -@section Hash functions -@subsection List of available hash functions -@subsection API of hash functions -@subsection Hash function abstraction layer (HFAL) +@include acl_hashes.texi @section MAC functions @section Pseudo random number generators (PRNGs)