doc/blockciphers.rst

   1
   2 Block ciphers
   3 =============
   4 A block cipher is a algorithm which turns an input of fixed length into an
   5 output of the same length (enciphering or encrypting). The transformation is
   6 specified by a key which has to be of a fixed length, or a length of a given
   7 set or range.
   8
   9 Generally there is also an algorithm which turns the output back to the
  10 previous input (deciphering or decrypting) when supplied with the same key.
  11
  12 List of available block ciphers
  13 -------------------------------
  14 This is a list of the currently supported block ciphers:
  15
  16 * AES (Advanced Encryption Standard)
  17 * Camellia
  18 * CAST5
  19 * CAST6
  20 * CS-Cipher
  21 * DES (Data Encryption Standard)
  22 * Khazad
  23 * Noekeon
  24 * Present
  25 * RC5
  26 * RC6
  27 * Seed
  28 * Serpent (AES finalist)
  29 * Shacal1
  30 * Shacal2
  31 * Skipjack
  32 * TDES (Tripple DES)
  33 * Threefish
  34 * XTEA
  35
  36 high frequent parameters
  37 ------------------------
  38 * block size
  39   - 64 bits, 128 bits
  40 * key size
  41   - 64 bits, 80 bits, 128 bits, 192 bits, 256 bits
  42
  43 (note that some block ciphers use different sizes)
  44
  45 Parts of a block cipher
  46 -----------------------
  47 * encryption algorithm
  48 * decryption algorithm
  49 * mostly a set of subkeys
  50 * mostly a keyschedule which generates the subkeys from the supplied key.
  51
  52 As we can see here a block cipher normally has an algorithm besides the
  53 encryption and decryption algorithm, which we call keyschedule.
  54 Mostly the encryption and decryption algorithm consist of multiple rounds,
  55 where each round (and sometimes between rounds) subkeys are needed to modify
  56 the data. This subkeys are generated by the keyschedule and stored in a state
  57 or context variable.
  58
  59 Note that not all algorithms need a pregenerated context, sometimes it is easy
  60 to generate the subkeys "on the fly" so there is not always the need of a
  61 context variable. In this case instead of a context the actual key is passed
  62 to the encryption and decryption function.
  63
  64 API of block ciphers
  65 --------------------
  66 The API is not always consistent due to the fact that we tried to optimize the
  67 code for size (flash, heap and stack) and speed (runtime of the different
  68 components).
  69 Generally the API of the implemented block ciphers consists of:
  70
  71 +----------+------------------------------------------------------------+
  72 | Suffix   | Description                                                |
  73 +==========+============================================================+
  74 | \*_init  | function, which implements the keyschedule                 |
  75 +----------+------------------------------------------------------------+
  76 | \*_enc   | function, which implements the encryption algorithm        |
  77 +----------+------------------------------------------------------------+
  78 | \*_dec   | function, which implements the decryption algorithm        |
  79 +----------+------------------------------------------------------------+
  80 | \*_free  | function, which frees memory allocated for the keyschedule |
  81 +----------+------------------------------------------------------------+
  82 | \*_ctx_t | context type, which can contain a keyschedule and other    |
  83 |          | information                                                |
  84 +----------+------------------------------------------------------------+
  85
  86 \*_init function
  87 ~~~~~~~~~~~~~~~~
  88 The \*_init function generally takes a pointer to the key as first parameter.
  89 For ciphers where the keysize is not fixed the second parameter gives the
  90 keysize (in bits regularly) and the last parameter points to the context
  91 variable to fill.
  92 For some ciphers there are additional parameters like the number of rounds,
  93 these parameters generally occur before the context pointer.
  94
  95 \*_enc and \*_dec functions
  96 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  97 The encryption and decryption function of a specific algorithm normally do not
  98 differ in their parameters. Generally these functions take a pointer to the
  99 block to operate on. Some ciphers allow to specify two blocks, where the first
 100 one will be written to and the second will contain the source block. The two
 101 blocks may overlap or be the same. Most ciphers have only one block pointer.
 102 The block specified by the pointer is encrypted (if the \*_enc function is
 103 called) or decrypted (if the \*_dec function is called).
 104 The last parameter specifies either the key direct (with a pointer to it) or
 105 is a pointer to a context created with the \*_init function.
 106 It is guaranteed that the context is in the same state as before the \*_enc or
 107 \*_dec function call. Most \*_enc and \*_dec functions do not modify the context
 108 at all, but some do for reducing dynamic memory requirements. So here are some
 109 limitations to the reentrant property.
 110
 111 \*_free function
 112 ~~~~~~~~~~~~~~~~
 113 A \*_free function is only provided where needed (so most ciphers do not have
 114 it). It is used to free memory dynamically allocated by the \*_init function.
 115
 116 \*_ctx_t type
 117 ~~~~~~~~~~~~~
 118 A variable of the \*_ctx_t type may hold information needed by the \*_enc or
 119 \*_dec function. It is initialized by the \*_init function. If dynamic memory
 120 is allocated by the \*_init function also a \*_free function is provided which
 121 frees the allocated memory. An initialized \*_ctx_t variable may not be copied
 122 as it may contains pointers to itself.
 123
 124
 125 Block cipher abstraction layer (BCAL)
 126 =====================================
 127 The BlockCipeherAbstractionLayer (BCAL) is an abstraction layer which allows
 128 usage of all implemented block ciphers in a simple way. It abstracts specific
 129 function details and is suitable for implementations which want to be flexible
 130 in the choosing of specific block ciphers. Another important aspect is that this
 131 abstraction layer enables the implementation of block cipher operating modes
 132 independently from concrete ciphers. It is very simple to use and reassembles
 133 the API used to implement individual ciphers.
 134
 135 The main component is a block cipher descriptor which contains the details of
 136 the individual ciphers.
 137
 138 Care should be taken when choosing a specific keysize. It may be the case that
 139 the chosen keysize is not compatible with the chosen block cipher.
 140
 141 Parts of BCAL
 142 -------------
 143 The BCAL is split up in different parts:
 144 * BCAL declaration for BCAL descriptors
 145 * algorithm specific definitions of BCAL descriptors
 146 * BCAL basic context type
 147 * BCAL basic functions
 148
 149 BCAL declaration for BCAL descriptors
 150 -------------------------------------
 151 The BCAL descriptor is a structure which is usually placed in FLASH or ROM since
 152 modification is unnecessary. It contains all information required to use the
 153 according block cipher.
 154
 155 ::
 156
 157    typedef struct {
 158         uint8_t  type; /* 1==block cipher */
 159         uint8_t  flags;
 160         PGM_P    name;
 161         uint16_t ctxsize_B;
 162         uint16_t blocksize_b;
 163         bc_init_fpt init;
 164         bc_enc_fpt  enc;
 165         bc_dec_fpt  dec;
 166         bc_free_fpt free;
 167         PGM_VOID_P valid_keysize_desc;
 168    } bcdesc_t; /* block cipher descriptor type */
 169
 170
 171 +--------------------+---------------------------------------------------------+
 172 | Element            | Description                                             |
 173 +====================+=========================================================+
 174 | type               | should be set to ``1`` to indicate that this descriptor |
 175 |                    | is for a block cipher.                                  |
 176 +--------------------+---------------------------------------------------------+
 177 | flags              | defines what kind of init function is provided and what |
 178 |                    | kind of decrypt and encrypt functions are provided.     |
 179 +--------------------+---------------------------------------------------------+
 180 | flags - bit 0      | if clear (``0``) designates an init function with fixed |
 181 |                    | key length, so the length parameter is omitted          |
 182 |                    | (``init(void* ctx, void* key)``).                       |
 183 |                    |                                                         |
 184 |                    | if set (``1``) designates an init function which        |
 185 |                    | requires an explicit keysize argument                   |
 186 |                    | (``init(void*ctx, uint16_t length_b, void* key)``).     |
 187 +--------------------+---------------------------------------------------------+
 188 | flags - bit 1      | if clear (``0``) designates that the encryption         |
 189 |                    | function transforms the plaintext block in place to the |
 190 |                    | ciphertext (``enc(void* block, void* ctx)``).           |
 191 |                    |                                                         |
 192 |                    | if set (``1``) designates that the encryption function  |
 193 |                    | offers a dedicated pointers for input and output. The   |
 194 |                    | two regions may be the same                             |
 195 |                    | (``enc(void* out, void* in, void*ctx)``).               |
 196 +--------------------+---------------------------------------------------------+
 197 | flags - bit 2      | if clear (``0``) designates that the decryption         |
 198 |                    | function transforms the ciphertext block in place to    |
 199 |                    | the plaintext (``dec(void* block, void* ctx)``).        |
 200 |                    |                                                         |
 201 |                    | if set (``1``) designates that the decryption function  |
 202 |                    | offers a dedicated pointers for input and output. The   |
 203 |                    | two regions may be the same                             |
 204 |                    | (``dec(void* out, void* in, void*ctx)``).               |
 205 +--------------------+---------------------------------------------------------+
 206 | name               | is a pointer to a zero terminated ASCII string giving   |
 207 |                    | the name of the implemented primitive. On targets with  |
 208 |                    | Harvard-architecture the string resides in code memory  |
 209 |                    | (FLASH, ROM, ...).                                      |
 210 +--------------------+---------------------------------------------------------+
 211 | ctxsize_B          | is the number of bytes which should be allocated for    |
 212 |                    | the context variable.                                   |
 213 +--------------------+---------------------------------------------------------+
 214 | blocksize_b        | is the number of bits on which the encrypt and decrypt  |
 215 |                    | function work on.                                       |
 216 +--------------------+---------------------------------------------------------+
 217 | init               | is a pointer to the init function (see ``flags`` how    |
 218 |                    | the init function should be called). If there is no     |
 219 |                    | init function this field is NULL.                       |
 220 +--------------------+---------------------------------------------------------+
 221 | enc                | is a pointer to the encryption function (see ``flags``  |
 222 |                    | how the encryption function should be called).          |
 223 +--------------------+---------------------------------------------------------+
 224 | dec                | is a pointer to the decryption function (see ``flags``  |
 225 |                    | how the decryption function should be called).          |
 226 +--------------------+---------------------------------------------------------+
 227 | free               | is a pointer to the free function or NULL if there is   |
 228 |                    | no free function.                                       |
 229 +--------------------+---------------------------------------------------------+
 230 | valid_keysize_desc | is a pointer to a keysize descriptor structure which is |
 231 |                    | used to validate that the chosen keysize is valid       |
 232 +--------------------+---------------------------------------------------------+
 233
 234 BCAL-Basic context
 235 ------------------
 236 Besides the context types for individual ciphers there is a generic context
 237 type for BCAL. This is the context to use when using BCAL based functions.
 238 The BCAL context has the following structure:
 239
 240 ::
 241
 242    typedef struct {
 243       bcdesc_t* desc_ptr;
 244       uint16_t  keysize;
 245       void*     ctx;
 246    } bcgen_ctx_t;
 247
 248 +----------+----------------------------------------+
 249 | desc_ptr | a pointer to the BCAL descriptor       |
 250 +----------+----------------------------------------+
 251 | keysize  | the chosen keysize                     |
 252 +----------+----------------------------------------+
 253 | ctx      | pointer to the cipher specific context |
 254 +----------+----------------------------------------+
 255
 256
 257
 258 BCAL-Basic
 259 ----------
 260 BCAL-Basic provides the basic features of an block cipher on top of the
 261 BCAL. To use it you simply have to include the algorithms you want to use,
 262 the BCAL descriptor file and of course the BCAL-Basic implementation.
 263
 264 The following functions are provided:
 265
 266 bcal_cipher_init
 267 ~~~~~~~~~~~~~~~~
 268 ::
 269
 270    uint8_t bcal_cipher_init(
 271       const bcdesc_t* cipher_descriptor,
 272       const void* key,
 273       uint16_t keysize_b,
 274       bcgen_ctx_t* ctx)
 275
 276 this function initializes a BCAL context based on the given BCAL descriptor
 277 pointer (first parameter) with a given key (second parameter) of a given length
 278 (third parameter). The context to initialize is designated by the pointer
 279 passed as fourth parameter.
 280
 281 If everything works fine ``0`` is returned. In the case something fails
 282 the following codes are returned:
 283
 284 +---+-------------------------------------------------------------------------+
 285 | 1 | The specified keysize is not available with this cipher                 |
 286 +---+-------------------------------------------------------------------------+
 287 | 2 | It was not possible to allocate enough memory to hold the key.          |
 288 |   | (This is returned when there is no actual init function and you ran out |
 289 |   | of memory)                                                              |
 290 +---+-------------------------------------------------------------------------+
 291 | 3 | It was not possible to allocate enough memory to hold the context       |
 292 |   | variable for the selected cipher.                                       |
 293 +---+-------------------------------------------------------------------------+
 294
 295 bcal_cipher_free
 296 ~~~~~~~~~~~~~~~~
 297 ::
 298
 299    void bcal_cipher_free(bcgen_ctx_t* ctx)
 300
 301 this function frees the memory allocated by the init function and should be
 302 called whenever you are finished with BCAL context. It automatically also calls
 303 the free function if necessary.
 304
 305 bcal_cipher_enc
 306 ~~~~~~~~~~~~~~~
 307 ::
 308
 309    void bcal_cipher_enc(void* block, const bcgen_ctx_t* ctx)
 310
 311 this function encrypts a block in-place using a given BCAL contex.
 312
 313 bcal_cipher_dec
 314 ~~~~~~~~~~~~~~~
 315 ::
 316
 317    void bcal_cipher_dec(void* block, const bcgen_ctx_t* ctx)
 318
 319 this function decrypts a block in-place using a given BCAL contex.
 320
 321 bcal_cipher_getBlocksize_b
 322 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 323 ::
 324
 325    uint16_t bcal_cipher_getBlocksize_b(const bcdesc_t* desc)
 326
 327 this function returns the block size of a given cipher by using the BCAL
 328 descriptor (to which a pointer must be passed).
 329
 330 bcal_cipher_getKeysizeDesc
 331 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 332 ::
 333
 334    PGM_VOID_P bcal_cipher_getKeysizeDesc(const bcdesc_t* desc)
 335
 336 this function returns a pointer to the keysize descriptor of a given cipher by
 337 using the BCAL descriptor (to which a pointer must be passed).
 338