adding preleminary documentation
This commit is contained in:
bg
parent
69d6349f8a
commit
2ea8cb1426
|
|
@ -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
|
||||
|
||||
Loading…
Reference in New Issue