91 lines
3.1 KiB
ReStructuredText
91 lines
3.1 KiB
ReStructuredText
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:
|
|
|
|
* simple list of valid keysizes
|
|
* range of keysizes
|
|
* augmented range of keysizes
|
|
* itemize
|
|
|
|
simple list of valid keysizes
|
|
-----------------------------
|
|
The simple keysize list has the following structure:
|
|
|
|
::
|
|
|
|
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;
|
|
|
|
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.
|
|
|
|
range of keysizes
|
|
-----------------
|
|
This method specifies an entire range of keys a valid using the following
|
|
structure:
|
|
|
|
::
|
|
|
|
typedef struct { /* keysize is valid if min<=keysize<=max */
|
|
uint16_t min;
|
|
uint16_t max;
|
|
} keysize_desc_range_t;
|
|
|
|
So all keysizes between @code{min} and @code{max} (including ``min`` and
|
|
``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.
|
|
|
|
augmented range of keysizes
|
|
---------------------------
|
|
The augmented range of keysizes uses the following structure:
|
|
|
|
::
|
|
|
|
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;
|
|
|
|
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 ``offset`` when divided by ``distance``. So you can limit a keysize
|
|
to full bytes by simply setting ``distance`` to ``8`` and ``offset`` to ``0``.
|
|
|
|
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 ``NULL`` byte.
|
|
|
|
The designator byte can have one of the following values:
|
|
|
|
|
|
+------+----------------------------------------------+
|
|
| 0x00 | Terminator byte, signals the end of the list |
|
|
+------+----------------------------------------------+
|
|
| 0x01 | simple list of keysizes |
|
|
+------+----------------------------------------------+
|
|
| 0x02 | simple range of keysizes |
|
|
+------+----------------------------------------------+
|
|
| 0x03 | augmented range of keysizes |
|
|
+------+----------------------------------------------+
|
|
|