@c acl_keysizes.texi

@section 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

@subsection 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.

@subsection 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.

@subsection 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}.

@subsection 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