@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
+@include acl_blockciphers.texi
-@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
-
-@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:
-@verbatim
-typedef struct{
- bcdesc_t* desc_ptr;
- uint16_t keysize;
- void* ctx;
-} bcgen_ctx_t;
-@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
-
-
-
-@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.
-@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).
-
-@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).
-
-@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)
projects / avr-crypto-lib.git / blobdiff