GNU Sample
**********

This is a short example of a complete Texinfo file. Copyright © 2011 Daniel Otte (daniel.otte@rub.de)

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.

Generic stuff
*************

File organisation
=================

Build process
=============

Testing system
==============

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.

Symmetric primitives
********************

Block ciphers
=============

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.

List of available block ciphers
-------------------------------

This is a list of the currently supported block ciphers:

  * AES (Advanced Encryption Standard)

  * Camellia

  * CAST5

  * CAST6

  * CS-Cipher

  * DES (Data Encryption Standard)

  * Khazad

  * Noekeon

  * Present

  * RC5

  * RC6

  * Seed

  * Serpent (AES finalist)

  * Shacal1

  * Shacal2

  * Skipjack

  * TDES (Tripple DES)

  * Threefish

  * XTEA

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)

Parts of a block cipher
-----------------------

  * encryption algorithm

  * decryption algorithm

  * mostly a set of subkeys

  * mostly a keyschedule which generates the subkeys from the supplied key.

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.

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:

  * *_init function, which implements the keyschedule

  * *_enc  function, which implements the encryption algorithm

  * *_dec  function, which implements the decryption algorithm

  * *_free function, which frees memory allocated for the keyschedule

  * *_ctx_t context type, which can contain a keyschedule and other information

*_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.

*_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.

*_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.

*_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.

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.

Parts of BCAL
-------------

The BCAL is split up in different parts:

  * BCAL declaration for BCAL decriptors

  * algorithm specific definitions of BCAL decriptors

  * BCAL basic context type

  * BCAL basic functions

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.

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 */

type
     should be set to 1 to indicate that this descriptor is for a block cipher.

flags
     defines what kind of init function is provided and what kind of decrypt and encrypt functions are provided.

     bit 0
          if clear (0) designates an init function with fixed key length, so the length parameter is omitted (init(void* ctx, void* key)).

          if set (1) designates an init function which requires an explicit keysize argument (init(void*ctx, uint16_t length_b, void* key)).

     bit 1
          if clear (0) designates that the encryption function transforms the plaintext block in place to the ciphertext (enc(void* block, void* ctx)).

          if set (1) designates that the encryption function offers a dedicated pointers for input and output. The two regions may be the same (enc(void* out, void* in, void*ctx)).

     bit 2
          if clear (0) designates that the decryption function transforms the ciphertext block in place to the plaintext (dec(void* block, void* ctx)).

          if set (1) designates that the decryption function offers a dedicated pointers for input and output. The two regions may be the same (dec(void* out, void* in, void*ctx)).

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, ...).

ctxsize_B
     is the number of bytes which should be allocated for the context variable.

blocksize_b
     is the number of bits on which the encrypt and decrypt function work on.

init
     is a pointer to the init function (see flags how the init function should be called). If there is no init function this field is NULL.

enc
     is a pointer to the encryption function (see flags how the encryption function should be called).

dec
     is a pointer to the decryption function (see flags how the decryption function should be called).

free
     is a pointer to the free function or NULL if there is no free function.

valid_keysize_desc
     is a pointer to a keysize descriptor structure which is used to validate that the chosen keysize is valid

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:
typedef struct{
	bcdesc_t* desc_ptr;
	uint16_t  keysize;
	void*     ctx;
} bcgen_ctx_t;

desc_ptr
     a pointer to the BCAL descriptor

keysize
     the chosen keysize

ctx
     pointer to the cipher specific context

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:

bcal_cipher_init
     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 0 is returned. In the case something fails the following codes are returned:

     1
          The specified keysize is not available with this cipher

     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)

     3
          It was not possible to allocate enough memory to hold the context variable for the selected cipher.

bcal_cipher_free
     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 free function if necessary.

bcal_cipher_enc
     void bcal_cipher_enc(void* block, const bcgen_ctx_t* ctx) this function encrypts a block in-place using a given BCAL contex.

bcal_cipher_dec
     void bcal_cipher_dec(void* block, const bcgen_ctx_t* ctx) this function decrypts a block in-place using a given BCAL contex.

bcal_cipher_getBlocksize_b
     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).

bcal_cipher_getKeysizeDesc
     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).

Modes of operation
==================

Stream ciphers
==============

List of available stream ciphers
--------------------------------

API of stream ciphers
---------------------

Stream cipher abstraction layer (SCAL)
--------------------------------------

Hash functions
==============

List of available hash functions
--------------------------------

API of hash functions
---------------------

Hash function abstraction layer (HFAL)
--------------------------------------

MAC functions
=============

Pseudo random number generators (PRNGs)
=======================================

Encodings
*********

Base64
======

ASN.1
=====

Big integer functions
*********************

Asymmetric Primitives
*********************

DSA
===

RSA
===

El-Gamal
========

MQQ
===