doc/acl_keysizes.texi

   1 @c acl_keysizes.texi
   2
   3 @section Keysize descriptors
   4 There are a lot of different block ciphers or cryptographic algorithms in
   5 general which put several constrains to the number of bits which can be used
   6 as key.
   7
   8 Our approach is to find a simple and compact way do specify which lengths are
   9 valid and which are not. The system is quite simple, we use a list of patterns
  10 (with parameters) and if any matches the keysize is valid, if none matches the
  11 keysize is unsupported.
  12
  13 The patterns are:
  14 @itemize @bullet
  15 @item simple list of valid keysizes
  16 @item range of keysizes
  17 @item augmented range of keysizes
  18 @end itemize
  19
  20 @subsection simple list of valid keysizes
  21 The simple keysize list has the following structure:
  22 @verbatim
  23 typedef struct{ /* keysize is valid if listed in items */
  24         uint8_t  n_items;  /* number of items (value 0 is reserved) */
  25         uint16_t items[]; /* list of valid lengths */
  26 }keysize_desc_list_t;
  27 @end verbatim
  28 First we specify how many keysizes we want to declare valid (this is limited to
  29 255 keysizes but that should not impose any real world constrains). And follow
  30 it by the keysizes as 16bit unsigned values.
  31
  32 If you want to declare a lot of keys please check first the other methods since
  33 they may give a more compact definition.
  34
  35 @subsection range of keysizes
  36 This method specifies an entire range of keys a valid using the following
  37 structure:
  38 @verbatim
  39 typedef struct{ /* keysize is valid if min<=keysize<=max */
  40         uint16_t min;
  41         uint16_t max;
  42 }keysize_desc_range_t;
  43 @end verbatim
  44 So all keysizes between @code{min} and @code{max} (including @code{min} and
  45 @code{max}) are valid. Please note that in most cases also keysizes which
  46 are not a multiple of 8 (so are not full bytes) are also matched.
  47 If you want to avoid this see the augmented range of keysizes.
  48
  49 @subsection augmented range of keysizes
  50 The augmented range of keysizes uses the following structure:
  51 @verbatim
  52 typedef struct{ /* keysize is valid if min<=keysize<=max and if keysize mod distance == offset */
  53         uint16_t min;
  54         uint16_t max;
  55         uint16_t distance;
  56         uint16_t offset;
  57 }keysize_desc_arg_range_t;
  58 @end verbatim
  59 The restriction to a range is the same as with the simpler range of keysizes,
  60 but also another restriction is imposed. A valid keysize must have a reminder
  61 of @code{offset} when divided by @code{distance}. So you can limit a keysize
  62 to full bytes by simply setting @code{distance} to @samp{8} and @code{offset}
  63 to @samp{0}.
  64
  65 @subsection the actual descriptor
  66 The keysize descriptor is a list of the former patterns. Each pattern is
  67 preceded by byte designating the type of pattern and the list is terminated
  68 by a @code{NULL} byte.
  69
  70 The designator byte can have one of the following values:
  71 @table @samp
  72 @item 0x00
  73 Terminator byte, signals the end of the list
  74 @item 0x01
  75 simple list of keysizes
  76 @item 0x02
  77 simple range of keysizes
  78 @item 0x03
  79 augmented range of keysizes
  80 @end table
  81
  82