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