more docu
This commit is contained in:
parent
bcad01af2c
commit
ca330e4062
|
@ -43,304 +43,13 @@ to use the library.
|
||||||
|
|
||||||
@chapter Symmetric primitives
|
@chapter Symmetric primitives
|
||||||
|
|
||||||
@section Block ciphers
|
@include acl_blockciphers.texi
|
||||||
@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
|
|
||||||
|
|
||||||
@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 Modes of operation
|
||||||
|
|
||||||
@section Stream ciphers
|
@include acl_streamciphers.texi
|
||||||
@subsection List of available stream ciphers
|
|
||||||
@subsection API of stream ciphers
|
|
||||||
@subsection Stream cipher abstraction layer (SCAL)
|
|
||||||
|
|
||||||
@section Hash functions
|
@include acl_hashes.texi
|
||||||
@subsection List of available hash functions
|
|
||||||
@subsection API of hash functions
|
|
||||||
@subsection Hash function abstraction layer (HFAL)
|
|
||||||
|
|
||||||
@section MAC functions
|
@section MAC functions
|
||||||
@section Pseudo random number generators (PRNGs)
|
@section Pseudo random number generators (PRNGs)
|
||||||
|
|
|
@ -0,0 +1,379 @@
|
||||||
|
@c acl_blockcipher.texi
|
||||||
|
|
||||||
|
@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:
|
||||||
|
@table @asis
|
||||||
|
@item block size
|
||||||
|
64 bits, 128 bits
|
||||||
|
@item key size
|
||||||
|
64 bits, 80 bits, 128 bits, 192 bits, 256 bits
|
||||||
|
(note that some block ciphers use different sizes)
|
||||||
|
@end table
|
||||||
|
|
||||||
|
@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:
|
||||||
|
@table @code
|
||||||
|
@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 table
|
||||||
|
@subsubsection @code{*_init} function
|
||||||
|
The @code{*_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 @code{*_enc} and @code{*_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 @code{*_enc} function is
|
||||||
|
called) or decrypted (if the @code{*_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 @code{*_init} function.
|
||||||
|
It is guaranteed that the context is in the same state as before the *_enc or
|
||||||
|
@code{*_dec} function call. Most @code{*_enc} and @code{*_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 @code{*_free} function
|
||||||
|
A @code{*_free} function is only provided where needed (so most ciphers do not have
|
||||||
|
it). It is used to free memory dynamically allocated by the @code{*_init} function.
|
||||||
|
|
||||||
|
@subsubsection *_ctx_t type
|
||||||
|
A variable of the @code{*_ctx_t} type may hold information needed by the @code{*_enc} or
|
||||||
|
@code{*_dec} function. It is initialized by the @code{*_init} function. If dynamic memory is
|
||||||
|
allocated by the @code{*_init} function also a @code{*_free} function is provided which frees
|
||||||
|
the allocated memory. An initialized @code{*_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
|
||||||
|
|
||||||
|
@subsection Keysize descriptors
|
||||||
|
There are a lot of different block ciphers or cryptographic algorithms in
|
||||||
|
general which put several constrains to the number of bits which can be used
|
||||||
|
as key.
|
||||||
|
|
||||||
|
Our approach is to find a simple and compact way do specify which lengths are
|
||||||
|
valid and which are not. The system is quite simple, we use a list of patterns
|
||||||
|
(with parameters) and if any matches the keysize is valid, if none matches the
|
||||||
|
keysize is unsupported.
|
||||||
|
|
||||||
|
The patterns are:
|
||||||
|
@itemize @bullet
|
||||||
|
@item simple list of valid keysizes
|
||||||
|
@item range of keysizes
|
||||||
|
@item augmented range of keysizes
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
@subsubsection simple list of valid keysizes
|
||||||
|
The simple keysize list has the following structure:
|
||||||
|
@verbatim
|
||||||
|
typedef struct{ /* keysize is valid if listed in items */
|
||||||
|
uint8_t n_items; /* number of items (value 0 is reserved) */
|
||||||
|
uint16_t items[]; /* list of valid lengths */
|
||||||
|
}keysize_desc_list_t;
|
||||||
|
@end verbatim
|
||||||
|
First we specify how many keysizes we want to declare valid (this is limited to
|
||||||
|
255 keysizes but that should not impose any real world constrains). And follow
|
||||||
|
it by the keysizes as 16bit unsigned values.
|
||||||
|
|
||||||
|
If you want to declare a lot of keys please check first the other methods since
|
||||||
|
they may give a more compact definition.
|
||||||
|
|
||||||
|
@subsubsection range of keysizes
|
||||||
|
This method specifies an entire range of keys a valid using the following
|
||||||
|
structure:
|
||||||
|
@verbatim
|
||||||
|
typedef struct{ /* keysize is valid if min<=keysize<=max */
|
||||||
|
uint16_t min;
|
||||||
|
uint16_t max;
|
||||||
|
}keysize_desc_range_t;
|
||||||
|
@end verbatim
|
||||||
|
So all keysizes between @code{min} and @code{max} (including @code{min} and
|
||||||
|
@code{max}) are valid. Please note that in most cases also keysizes which
|
||||||
|
are not a multiple of 8 (so are not full bytes) are also matched.
|
||||||
|
If you want to avoid this see the augmented range of keysizes.
|
||||||
|
|
||||||
|
@subsubsection augmented range of keysizes
|
||||||
|
The augmented range of keysizes uses the following structure:
|
||||||
|
@verbatim
|
||||||
|
typedef struct{ /* keysize is valid if min<=keysize<=max and if keysize mod distance == offset */
|
||||||
|
uint16_t min;
|
||||||
|
uint16_t max;
|
||||||
|
uint16_t distance;
|
||||||
|
uint16_t offset;
|
||||||
|
}keysize_desc_arg_range_t;
|
||||||
|
@end verbatim
|
||||||
|
The restriction to a range is the same as with the simpler range of keysizes,
|
||||||
|
but also another restriction is imposed. A valid keysize must have a reminder
|
||||||
|
of @code{offset} when divided by @code{distance}. So you can limit a keysize
|
||||||
|
to full bytes by simply setting @code{distance} to @samp{8} and @code{offset}
|
||||||
|
to @samp{0}.
|
||||||
|
|
||||||
|
@subsubsection the actual descriptor
|
||||||
|
The keysize descriptor is a list of the former patterns. Each pattern is
|
||||||
|
preceded by byte designating the type of pattern and the list is terminated
|
||||||
|
by a @code{NULL} byte.
|
||||||
|
|
||||||
|
The designator byte can have one of the following values:
|
||||||
|
@table @samp
|
||||||
|
@item 0x00
|
||||||
|
Terminator byte, signals the end of the list
|
||||||
|
@item 0x01
|
||||||
|
simple list of keysizes
|
||||||
|
@item 0x02
|
||||||
|
simple range of keysizes
|
||||||
|
@item 0x03
|
||||||
|
augmented range of keysizes
|
||||||
|
@end table
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,87 @@
|
||||||
|
@c acl_hashes.texi
|
||||||
|
|
||||||
|
@section Hash functions
|
||||||
|
A hash function is an algorithm to map an arbitrary long message (in the form
|
||||||
|
of a bit string) to a fixed length message digest or hash value.
|
||||||
|
The hash function aims to be collision free, which means that it is not
|
||||||
|
practicable to find two messages with the same hash value (although this
|
||||||
|
collision must exist). Also it should not be practicable to construct a
|
||||||
|
message which maps to a given hash value.
|
||||||
|
|
||||||
|
@subsection List of available hash functions
|
||||||
|
The following hash functions are currently implemented:
|
||||||
|
@itemize @bullet
|
||||||
|
@item Blake
|
||||||
|
@item BlueMidnightWish
|
||||||
|
@item CubeHash
|
||||||
|
@item Echo
|
||||||
|
@item Grøstl
|
||||||
|
@item Keccak
|
||||||
|
@item MD5
|
||||||
|
@item SHA-256
|
||||||
|
@item SHA-1
|
||||||
|
@item Shabal
|
||||||
|
@item Skein
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
@subsection High frequent parameters:
|
||||||
|
@table @asis
|
||||||
|
@item block size
|
||||||
|
512 bits
|
||||||
|
@item hash value size
|
||||||
|
128 bits, 160 bits, 224 bits, 256 bits, 384 bits, 512 bits
|
||||||
|
@end table
|
||||||
|
|
||||||
|
|
||||||
|
@subsection Parts of a hash function
|
||||||
|
@itemize @bullet
|
||||||
|
@item initialization function
|
||||||
|
@item compression algorithm
|
||||||
|
@item finalization function
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
@subsection hash function API
|
||||||
|
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:
|
||||||
|
@table @code
|
||||||
|
@item *_init
|
||||||
|
function, which implements the initialisation of the context
|
||||||
|
@item *_nextBlock
|
||||||
|
function, which implements the compression algorithm
|
||||||
|
@item *_lastBlock
|
||||||
|
function, which implements the the padding algorithm
|
||||||
|
@item *_ctx2hash
|
||||||
|
function, which turns a context into an actual hash value
|
||||||
|
@item *_ctx_t
|
||||||
|
context type, which can contains the state of a hashing process
|
||||||
|
@end table
|
||||||
|
|
||||||
|
@subsubsection @code{*_init} function
|
||||||
|
The @code{*_init} function generally takes a pointer to the context as parameter.
|
||||||
|
This function initializes the context with algorithm specific values.
|
||||||
|
|
||||||
|
@subsubsection @code{*_nextBlock} function
|
||||||
|
The @code{*_nextBlock} function is the core of each hash function. It updates the hash
|
||||||
|
state with a given message block. So this function uses a context pointer and
|
||||||
|
a message pointer as parameters. The size of a message block is fixed for each
|
||||||
|
hash function (mostly 512 bit). For the last block of a messages which may be
|
||||||
|
smaller than the blocksize you have to use the @code{*_lastBlock} function described
|
||||||
|
below.
|
||||||
|
|
||||||
|
@subsubsection @code{*_lastBlock} function
|
||||||
|
The @code{*_lastBlock} function finalizes the context with the last bits of a
|
||||||
|
message. Since the last block is not required to have the blocksize you have
|
||||||
|
to specify the length of the last block (normally in bits). This function
|
||||||
|
performs the padding and final processing.
|
||||||
|
|
||||||
|
@subsubsection @code{*_ctx2hash} function
|
||||||
|
The @code{*_ctx2hash} function turns a given hash context into an actual hash value.
|
||||||
|
If multiple sized hash value may be created from a context it is necessary to
|
||||||
|
give the the size of the hash value as parameter.
|
||||||
|
|
||||||
|
|
||||||
|
@subsection Hash function abstraction layer (HFAL)
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,76 @@
|
||||||
|
@c acl_streamciphers.texi
|
||||||
|
@section Stream ciphers
|
||||||
|
A stream cipher normally generates a deterministic, random looking stream of
|
||||||
|
bits, known as key stream. For encryption purpose this key stream is XORed with
|
||||||
|
the data stream. So decryption is exactly the same as encryption. The
|
||||||
|
data-stream is XORed with the key stream giving the plaintext. So both sides
|
||||||
|
need exactly the same stream cipher in the same state.
|
||||||
|
|
||||||
|
@subsection List of available stream ciphers
|
||||||
|
The following stream ciphers are currently implemented:
|
||||||
|
@itemize @bullet
|
||||||
|
@item ARCFOUR (RC4 compatibel)
|
||||||
|
@item Trivium
|
||||||
|
@item Grain
|
||||||
|
@item MUGI
|
||||||
|
@item Mickey-128 (v2)
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
@subsection High frequent parameters
|
||||||
|
@table @asis
|
||||||
|
@item output-size
|
||||||
|
8 bit, 1 bit
|
||||||
|
@item keysize
|
||||||
|
64 bit, 80 bit, 128 bit
|
||||||
|
@item IVsize
|
||||||
|
64 bit
|
||||||
|
@end table
|
||||||
|
|
||||||
|
@subsection Parts of a stream cipher
|
||||||
|
@itemize @bullet
|
||||||
|
@item generation algorithm
|
||||||
|
@item initialization algorithm
|
||||||
|
@item state
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
As we can see all stream ciphers seem to utilize an internal state which
|
||||||
|
determines the output. This state is initialized by the initialization
|
||||||
|
algorithm with a key and an IV (initialization vector). It is very important
|
||||||
|
for security that _never_ the same key with the same IV is used again. The
|
||||||
|
IV is not required to be kept secret.
|
||||||
|
|
||||||
|
@subsection API of stream 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 stream ciphers consists of:
|
||||||
|
@table @code
|
||||||
|
@item *_init
|
||||||
|
function, which implements the initialization
|
||||||
|
|
||||||
|
@item *_gen
|
||||||
|
function, which implements the streamcipher algorithm and generates a
|
||||||
|
keystream output
|
||||||
|
|
||||||
|
@item *_ctx_t
|
||||||
|
context type, which contains internal state information
|
||||||
|
|
||||||
|
@end table
|
||||||
|
|
||||||
|
@subsubsection @code{*_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) followed by a pointer to the IV and a length
|
||||||
|
parameter for not fixed IV sizes (both are omitted if the algorithm does not
|
||||||
|
specify IV handling, in this case a part of the key should be used as IV).
|
||||||
|
The last parameter points to the context variable to fill.
|
||||||
|
|
||||||
|
@subsubsection @code{*_gen} function
|
||||||
|
The *_gen function updates the internal state to which a pointer is given as
|
||||||
|
parameter and returns a fixed length part of the keystream as return value.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
@subsection Stream cipher abstraction layer (SCAL)
|
||||||
|
|
Loading…
Reference in New Issue