@copying
This is a short example of a complete Texinfo file.
-Copyright © 2011 Daniel Otte
+Copyright © 2006-2015 Daniel Otte (@email{daniel.otte@@rub.de})
@end copying
@titlepage
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.
+@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
-@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 File organisation
-@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.
+@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).
-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 make-stubs
+All stubs are included by the main Makefile automatically, so the addition of
+algorithms should not require modifications to the Makefile.
-@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.
+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.
+Each algorithm implementation has its own stub. A stub looks like the following:
@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 */
+# 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 @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.
+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.
- @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
+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
+@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
+@include acl_keysizes.texi
+@include acl_blockciphers.texi
@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)
projects / avr-crypto-lib.git / blobdiff