From a49bff0095d7fae6c24ec953a03ef349839eff60 Mon Sep 17 00:00:00 2001
From: bg <bg@nerilex.org>
Date: Mon, 25 Aug 2014 22:00:36 +0200
Subject: [PATCH] new keysize documentation in reStructuredText-format

---
 doc/keysizes.rst | 90 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 doc/keysizes.rst

diff --git a/doc/keysizes.rst b/doc/keysizes.rst
new file mode 100644
index 0000000..ab56876
--- /dev/null
+++ b/doc/keysizes.rst
@@ -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                  |
++------+----------------------------------------------+
+
-- 
2.39.5