@item BCAL basic functions
@end itemize
-@subsubsection BCAL declaration for BCAL decriptors
+@subsection 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.
that the chosen keysize is valid
@end table
-@subsubsection BCAL-Basic context
+@subsection 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:
-@subsubsection BCAL-Basic
+@subsection 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
+@subsubsection @code{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
for the selected cipher.
@end table
-@item bcal_cipher_free
+@subsubsection @code{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
+@subsubsection @code{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
+@subsubsection @code{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
+@subsubsection @code{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
+@subsubsection @code{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
projects / avr-crypto-lib.git / blobdiff