2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25 #ifndef BR_BEARSSL_BLOCK_H__
26 #define BR_BEARSSL_BLOCK_H__
35 * For a block cipher implementation, up to three separate sets of
36 * functions are provided, for CBC encryption, CBC decryption, and CTR
37 * encryption/decryption. Each set has its own context structure,
38 * initialized with the encryption key. Each set of functions is
39 * provided both as named functions, and through an OOP interface.
41 * For CBC encryption and decryption, the data to encrypt or decrypt is
42 * referenced as a sequence of blocks. The implementations assume that
43 * there is no partial block; no padding is applied or removed. The
44 * caller is responsible for handling any kind of padding.
46 * Function for CTR encryption are defined only for block ciphers with
47 * blocks of 16 bytes or more (i.e. AES, but not DES/3DES).
49 * Each implemented block cipher is identified by an "internal name"
50 * from which are derived the names of structures and functions that
51 * implement the cipher. For the block cipher of internal name "xxx",
52 * the following are defined:
55 * A macro that evaluates to the block size (in bytes) of the
56 * cipher. For all implemented block ciphers, this value is a
60 * Context structure that contains the subkeys resulting from the key
61 * expansion. These subkeys are appropriate for CBC encryption. The
62 * structure first field is called 'vtable' and points to the
63 * appropriate OOP structure.
65 * br_xxx_cbcenc_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)
66 * Perform key expansion: subkeys for CBC encryption are computed and
67 * written in the provided context structure. The key length MUST be
68 * adequate for the implemented block cipher. This function also sets
71 * br_xxx_cbcenc_run(const br_xxx_cbcenc_keys *ctx,
72 * void *iv, void *data, size_t len)
73 * Perform CBC encryption of 'len' bytes, in place. The encrypted data
74 * replaces the cleartext. 'len' MUST be a multiple of the block length
75 * (if it is not, the function may loop forever or overflow a buffer).
76 * The IV is provided with the 'iv' pointer; it is also updated with
77 * a copy of the last encrypted block.
80 * Context structure that contains the subkeys resulting from the key
81 * expansion. These subkeys are appropriate for CBC decryption. The
82 * structure first field is called 'vtable' and points to the
83 * appropriate OOP structure.
85 * br_xxx_cbcdec_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)
86 * Perform key expansion: subkeys for CBC decryption are computed and
87 * written in the provided context structure. The key length MUST be
88 * adequate for the implemented block cipher. This function also sets
91 * br_xxx_cbcdec_run(const br_xxx_cbcdec_keys *ctx,
92 * void *iv, void *data, size_t num_blocks)
93 * Perform CBC decryption of 'len' bytes, in place. The decrypted data
94 * replaces the ciphertext. 'len' MUST be a multiple of the block length
95 * (if it is not, the function may loop forever or overflow a buffer).
96 * The IV is provided with the 'iv' pointer; it is also updated with
97 * a copy of the last encrypted block.
100 * Context structure that contains the subkeys resulting from the key
101 * expansion. These subkeys are appropriate for CTR encryption and
102 * decryption. The structure first field is called 'vtable' and
103 * points to the appropriate OOP structure.
105 * br_xxx_ctr_init(br_xxx_ctr_keys *ctx, const void *key, size_t len)
106 * Perform key expansion: subkeys for CTR encryption and decryption
107 * are computed and written in the provided context structure. The
108 * key length MUST be adequate for the implemented block cipher. This
109 * function also sets the 'vtable' field.
111 * br_xxx_ctr_run(const br_xxx_ctr_keys *ctx, const void *iv,
112 * uint32_t cc, void *data, size_t len) [returns uint32_t]
113 * Perform CTR encryption/decryption of some data. Processing is done
114 * "in place" (the output data replaces the input data). This function
115 * implements the "standard incrementing function" from NIST SP800-38A,
116 * annex B: the IV length shall be 4 bytes less than the block size
117 * (i.e. 12 bytes for AES) and the counter is the 32-bit value starting
118 * with 'cc'. The data length ('len') is not necessarily a multiple of
119 * the block size. The new counter value is returned, which supports
120 * chunked processing, provided that each chunk length (except possibly
121 * the last one) is a multiple of the block size.
124 * It shall be noted that the key expansion functions return 'void'. If
125 * the provided key length is not allowed, then there will be no error
126 * reporting; implementations need not validate the key length, thus an
127 * invalid key length may result in undefined behaviour (e.g. buffer
130 * Subkey structures contain no interior pointer, and no external
131 * resources are allocated upon key expansion. They can thus be
132 * discarded without any explicit deallocation.
135 * Object-oriented API: each context structure begins with a field
136 * (called 'vtable') that points to an instance of a structure that
137 * references the relevant functions through pointers. Each such
138 * structure contains the following:
140 * context_size size (in bytes) of the context structure for subkeys
141 * block_size cipher block size (in bytes)
142 * log_block_size base-2 logarithm of cipher block size
143 * init pointer to the key expansion function
144 * run pointer to the encryption/decryption function
146 * Static, constant instances of these structures are defined, under
149 * br_xxx_cbcenc_vtable
150 * br_xxx_cbcdec_vtable
154 * Implemented Block Ciphers
155 * -------------------------
157 * Function Name Allowed key lengths (bytes)
159 * AES aes_ct 16, 24 and 32
160 * AES aes_ct64 16, 24 and 32
161 * AES aes_big 16, 24 and 32
162 * AES aes_small 16, 24 and 32
163 * DES des_ct 8, 16 and 24
164 * DES des_tab 8, 16 and 24
166 * 'aes_big' is a "classical" AES implementation, using tables. It
167 * is fast but not constant-time, since it makes data-dependent array
170 * 'aes_small' is an AES implementation optimized for code size. It
171 * is substantially slower than 'aes_big'; it is not constant-time
174 * 'aes_ct' is a constant-time implementation of AES; its code is about
175 * as big as that of 'aes_big', while its performance is comparable to
176 * that of 'aes_small'. However, it is constant-time. This
177 * implementation should thus be considered to be the "default" AES in
178 * BearSSL, to be used unless the operational context guarantees that a
179 * non-constant-time implementation is safe, or an architecture-specific
180 * constant-time implementation can be used (e.g. using dedicated
183 * 'aes_ct64' is another constant-time implementation of AES. It is
184 * similar to 'aes_ct' but uses 64-bit values, for faster processing
185 * on 64-bit machines.
187 * 'des_tab' is a classic, table-based implementation of DES/3DES. It
188 * is not constant-time.
190 * 'des_ct' is an constant-time implementation of DES/3DES. It is
191 * substantially slower than 'des_tab'.
194 typedef struct br_block_cbcenc_class_ br_block_cbcenc_class
;
195 struct br_block_cbcenc_class_
{
198 unsigned log_block_size
;
199 void (*init
)(const br_block_cbcenc_class
**ctx
,
200 const void *key
, size_t key_len
);
201 void (*run
)(const br_block_cbcenc_class
*const *ctx
,
202 void *iv
, void *data
, size_t len
);
205 typedef struct br_block_cbcdec_class_ br_block_cbcdec_class
;
206 struct br_block_cbcdec_class_
{
209 unsigned log_block_size
;
210 void (*init
)(const br_block_cbcdec_class
**ctx
,
211 const void *key
, size_t key_len
);
212 void (*run
)(const br_block_cbcdec_class
*const *ctx
,
213 void *iv
, void *data
, size_t len
);
216 typedef struct br_block_ctr_class_ br_block_ctr_class
;
217 struct br_block_ctr_class_
{
220 unsigned log_block_size
;
221 void (*init
)(const br_block_ctr_class
**ctx
,
222 const void *key
, size_t key_len
);
223 uint32_t (*run
)(const br_block_ctr_class
*const *ctx
,
224 const void *iv
, uint32_t cc
, void *data
, size_t len
);
228 * Traditional, table-based AES implementation. It is fast, but uses
229 * internal tables (in particular a 1 kB table for encryption, another
230 * 1 kB table for decryption, and a 256-byte table for key schedule),
231 * and it is not constant-time. In contexts where cache-timing attacks
232 * apply, this implementation may leak the secret key.
234 #define br_aes_big_BLOCK_SIZE 16
236 const br_block_cbcenc_class
*vtable
;
239 } br_aes_big_cbcenc_keys
;
241 const br_block_cbcdec_class
*vtable
;
244 } br_aes_big_cbcdec_keys
;
246 const br_block_ctr_class
*vtable
;
249 } br_aes_big_ctr_keys
;
250 extern const br_block_cbcenc_class br_aes_big_cbcenc_vtable
;
251 extern const br_block_cbcdec_class br_aes_big_cbcdec_vtable
;
252 extern const br_block_ctr_class br_aes_big_ctr_vtable
;
253 void br_aes_big_cbcenc_init(br_aes_big_cbcenc_keys
*ctx
,
254 const void *key
, size_t len
);
255 void br_aes_big_cbcdec_init(br_aes_big_cbcdec_keys
*ctx
,
256 const void *key
, size_t len
);
257 void br_aes_big_ctr_init(br_aes_big_ctr_keys
*ctx
,
258 const void *key
, size_t len
);
259 void br_aes_big_cbcenc_run(const br_aes_big_cbcenc_keys
*ctx
, void *iv
,
260 void *data
, size_t len
);
261 void br_aes_big_cbcdec_run(const br_aes_big_cbcdec_keys
*ctx
, void *iv
,
262 void *data
, size_t len
);
263 uint32_t br_aes_big_ctr_run(const br_aes_big_ctr_keys
*ctx
,
264 const void *iv
, uint32_t cc
, void *data
, size_t len
);
267 * AES implementation optimized for size. It is slower than the
268 * traditional table-based AES implementation, but requires much less
269 * code. It still uses data-dependent table accesses (albeit within a
270 * much smaller 256-byte table), which makes it conceptually vulnerable
271 * to cache-timing attacks.
273 #define br_aes_small_BLOCK_SIZE 16
275 const br_block_cbcenc_class
*vtable
;
278 } br_aes_small_cbcenc_keys
;
280 const br_block_cbcdec_class
*vtable
;
283 } br_aes_small_cbcdec_keys
;
285 const br_block_ctr_class
*vtable
;
288 } br_aes_small_ctr_keys
;
289 extern const br_block_cbcenc_class br_aes_small_cbcenc_vtable
;
290 extern const br_block_cbcdec_class br_aes_small_cbcdec_vtable
;
291 extern const br_block_ctr_class br_aes_small_ctr_vtable
;
292 void br_aes_small_cbcenc_init(br_aes_small_cbcenc_keys
*ctx
,
293 const void *key
, size_t len
);
294 void br_aes_small_cbcdec_init(br_aes_small_cbcdec_keys
*ctx
,
295 const void *key
, size_t len
);
296 void br_aes_small_ctr_init(br_aes_small_ctr_keys
*ctx
,
297 const void *key
, size_t len
);
298 void br_aes_small_cbcenc_run(const br_aes_small_cbcenc_keys
*ctx
, void *iv
,
299 void *data
, size_t len
);
300 void br_aes_small_cbcdec_run(const br_aes_small_cbcdec_keys
*ctx
, void *iv
,
301 void *data
, size_t len
);
302 uint32_t br_aes_small_ctr_run(const br_aes_small_ctr_keys
*ctx
,
303 const void *iv
, uint32_t cc
, void *data
, size_t len
);
306 * Constant-time AES implementation. Its size is similar to that of
307 * 'aes_big', and its performance is similar to that of 'aes_small' (faster
308 * decryption, slower encryption). However, it is constant-time, i.e.
309 * immune to cache-timing and similar attacks.
311 #define br_aes_ct_BLOCK_SIZE 16
313 const br_block_cbcenc_class
*vtable
;
316 } br_aes_ct_cbcenc_keys
;
318 const br_block_cbcdec_class
*vtable
;
321 } br_aes_ct_cbcdec_keys
;
323 const br_block_ctr_class
*vtable
;
326 } br_aes_ct_ctr_keys
;
327 extern const br_block_cbcenc_class br_aes_ct_cbcenc_vtable
;
328 extern const br_block_cbcdec_class br_aes_ct_cbcdec_vtable
;
329 extern const br_block_ctr_class br_aes_ct_ctr_vtable
;
330 void br_aes_ct_cbcenc_init(br_aes_ct_cbcenc_keys
*ctx
,
331 const void *key
, size_t len
);
332 void br_aes_ct_cbcdec_init(br_aes_ct_cbcdec_keys
*ctx
,
333 const void *key
, size_t len
);
334 void br_aes_ct_ctr_init(br_aes_ct_ctr_keys
*ctx
,
335 const void *key
, size_t len
);
336 void br_aes_ct_cbcenc_run(const br_aes_ct_cbcenc_keys
*ctx
, void *iv
,
337 void *data
, size_t len
);
338 void br_aes_ct_cbcdec_run(const br_aes_ct_cbcdec_keys
*ctx
, void *iv
,
339 void *data
, size_t len
);
340 uint32_t br_aes_ct_ctr_run(const br_aes_ct_ctr_keys
*ctx
,
341 const void *iv
, uint32_t cc
, void *data
, size_t len
);
344 * 64-bit constant-time AES implementation. It is similar to 'aes_ct'
345 * but uses 64-bit registers, making it about twice faster than 'aes_ct'
346 * on 64-bit platforms, while remaining constant-time and with a similar
347 * code size. (The doubling in performance is only for CBC decryption
348 * and CTR mode; CBC encryption is non-parallel and cannot benefit from
349 * the larger registers.)
351 #define br_aes_ct64_BLOCK_SIZE 16
353 const br_block_cbcenc_class
*vtable
;
356 } br_aes_ct64_cbcenc_keys
;
358 const br_block_cbcdec_class
*vtable
;
361 } br_aes_ct64_cbcdec_keys
;
363 const br_block_ctr_class
*vtable
;
366 } br_aes_ct64_ctr_keys
;
367 extern const br_block_cbcenc_class br_aes_ct64_cbcenc_vtable
;
368 extern const br_block_cbcdec_class br_aes_ct64_cbcdec_vtable
;
369 extern const br_block_ctr_class br_aes_ct64_ctr_vtable
;
370 void br_aes_ct64_cbcenc_init(br_aes_ct64_cbcenc_keys
*ctx
,
371 const void *key
, size_t len
);
372 void br_aes_ct64_cbcdec_init(br_aes_ct64_cbcdec_keys
*ctx
,
373 const void *key
, size_t len
);
374 void br_aes_ct64_ctr_init(br_aes_ct64_ctr_keys
*ctx
,
375 const void *key
, size_t len
);
376 void br_aes_ct64_cbcenc_run(const br_aes_ct64_cbcenc_keys
*ctx
, void *iv
,
377 void *data
, size_t len
);
378 void br_aes_ct64_cbcdec_run(const br_aes_ct64_cbcdec_keys
*ctx
, void *iv
,
379 void *data
, size_t len
);
380 uint32_t br_aes_ct64_ctr_run(const br_aes_ct64_ctr_keys
*ctx
,
381 const void *iv
, uint32_t cc
, void *data
, size_t len
);
384 * These structures are large enough to accommodate subkeys for all
385 * AES implementations.
388 const br_block_cbcenc_class
*vtable
;
389 br_aes_big_cbcenc_keys big
;
390 br_aes_small_cbcenc_keys small
;
391 br_aes_ct_cbcenc_keys ct
;
392 br_aes_ct64_cbcenc_keys ct64
;
393 } br_aes_gen_cbcenc_keys
;
395 const br_block_cbcdec_class
*vtable
;
396 br_aes_big_cbcdec_keys big
;
397 br_aes_small_cbcdec_keys small
;
398 br_aes_ct_cbcdec_keys ct
;
399 br_aes_ct64_cbcdec_keys ct64
;
400 } br_aes_gen_cbcdec_keys
;
402 const br_block_ctr_class
*vtable
;
403 br_aes_big_ctr_keys big
;
404 br_aes_small_ctr_keys small
;
405 br_aes_ct_ctr_keys ct
;
406 br_aes_ct64_ctr_keys ct64
;
407 } br_aes_gen_ctr_keys
;
410 * Traditional, table-based implementation for DES/3DES. Since tables are
411 * used, cache-timing attacks are conceptually possible.
413 #define br_des_tab_BLOCK_SIZE 8
415 const br_block_cbcenc_class
*vtable
;
418 } br_des_tab_cbcenc_keys
;
420 const br_block_cbcdec_class
*vtable
;
423 } br_des_tab_cbcdec_keys
;
424 extern const br_block_cbcenc_class br_des_tab_cbcenc_vtable
;
425 extern const br_block_cbcdec_class br_des_tab_cbcdec_vtable
;
426 void br_des_tab_cbcenc_init(br_des_tab_cbcenc_keys
*ctx
,
427 const void *key
, size_t len
);
428 void br_des_tab_cbcdec_init(br_des_tab_cbcdec_keys
*ctx
,
429 const void *key
, size_t len
);
430 void br_des_tab_cbcenc_run(const br_des_tab_cbcenc_keys
*ctx
, void *iv
,
431 void *data
, size_t len
);
432 void br_des_tab_cbcdec_run(const br_des_tab_cbcdec_keys
*ctx
, void *iv
,
433 void *data
, size_t len
);
436 * Constant-time implementation for DES/3DES. It is substantially slower
437 * (by a factor of about 4x), but also immune to cache-timing attacks.
439 #define br_des_ct_BLOCK_SIZE 8
441 const br_block_cbcenc_class
*vtable
;
444 } br_des_ct_cbcenc_keys
;
446 const br_block_cbcdec_class
*vtable
;
449 } br_des_ct_cbcdec_keys
;
450 extern const br_block_cbcenc_class br_des_ct_cbcenc_vtable
;
451 extern const br_block_cbcdec_class br_des_ct_cbcdec_vtable
;
452 void br_des_ct_cbcenc_init(br_des_ct_cbcenc_keys
*ctx
,
453 const void *key
, size_t len
);
454 void br_des_ct_cbcdec_init(br_des_ct_cbcdec_keys
*ctx
,
455 const void *key
, size_t len
);
456 void br_des_ct_cbcenc_run(const br_des_ct_cbcenc_keys
*ctx
, void *iv
,
457 void *data
, size_t len
);
458 void br_des_ct_cbcdec_run(const br_des_ct_cbcdec_keys
*ctx
, void *iv
,
459 void *data
, size_t len
);
462 * These structures are large enough to accommodate subkeys for all
463 * DES/3DES implementations.
466 const br_block_cbcenc_class
*vtable
;
467 br_des_tab_cbcenc_keys tab
;
468 br_des_ct_cbcenc_keys ct
;
469 } br_des_gen_cbcenc_keys
;
471 const br_block_cbcdec_class
*vtable
;
472 br_des_tab_cbcdec_keys tab
;
473 br_des_ct_cbcdec_keys ct
;
474 } br_des_gen_cbcdec_keys
;