new keysize documentation in reStructuredText-format
This commit is contained in:
parent
6cc7eaef52
commit
a49bff0095
|
@ -0,0 +1,90 @@
|
|||
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 |
|
||||
+------+----------------------------------------------+
|
||||
|
Loading…
Reference in New Issue