X-Git-Url: https://www.bearssl.org/gitweb//home/git/?p=BearSSL;a=blobdiff_plain;f=inc%2Fbearssl_block.h;h=38108b74185065441873c3af5acfdb8548c34f35;hp=6dc0e5bfb40d7f009a9f0152d76a73daef0ad950;hb=e61ad42191511226309bad2cbde8cd9e8cc743cb;hpb=3210f38e0491b39aec1ef419cb4114e9483089fb diff --git a/inc/bearssl_block.h b/inc/bearssl_block.h index 6dc0e5b..38108b7 100644 --- a/inc/bearssl_block.h +++ b/inc/bearssl_block.h @@ -28,15 +28,19 @@ #include #include -/* - * Block Ciphers - * ------------- +/** \file bearssl_block.h + * + * # Block Ciphers + * + * This file documents the API for block ciphers. + * + * + * ## Procedural API * * For a block cipher implementation, up to three separate sets of * functions are provided, for CBC encryption, CBC decryption, and CTR * encryption/decryption. Each set has its own context structure, - * initialized with the encryption key. Each set of functions is - * provided both as named functions, and through an OOP interface. + * initialised with the encryption key. * * For CBC encryption and decryption, the data to encrypt or decrypt is * referenced as a sequence of blocks. The implementations assume that @@ -48,80 +52,87 @@ * * Each implemented block cipher is identified by an "internal name" * from which are derived the names of structures and functions that - * implement the cipher. For the block cipher of internal name "xxx", + * implement the cipher. For the block cipher of internal name "`xxx`", * the following are defined: * - * br_xxx_BLOCK_SIZE - * A macro that evaluates to the block size (in bytes) of the - * cipher. For all implemented block ciphers, this value is a - * power of two. - * - * br_xxx_cbcenc_keys - * Context structure that contains the subkeys resulting from the key - * expansion. These subkeys are appropriate for CBC encryption. The - * structure first field is called 'vtable' and points to the - * appropriate OOP structure. - * - * br_xxx_cbcenc_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len) - * Perform key expansion: subkeys for CBC encryption are computed and - * written in the provided context structure. The key length MUST be - * adequate for the implemented block cipher. This function also sets - * the 'vtable' field. - * - * br_xxx_cbcenc_run(const br_xxx_cbcenc_keys *ctx, - * void *iv, void *data, size_t len) - * Perform CBC encryption of 'len' bytes, in place. The encrypted data - * replaces the cleartext. 'len' MUST be a multiple of the block length - * (if it is not, the function may loop forever or overflow a buffer). - * The IV is provided with the 'iv' pointer; it is also updated with - * a copy of the last encrypted block. - * - * br_xxx_cbcdec_keys - * Context structure that contains the subkeys resulting from the key - * expansion. These subkeys are appropriate for CBC decryption. The - * structure first field is called 'vtable' and points to the - * appropriate OOP structure. - * - * br_xxx_cbcdec_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len) - * Perform key expansion: subkeys for CBC decryption are computed and - * written in the provided context structure. The key length MUST be - * adequate for the implemented block cipher. This function also sets - * the 'vtable' field. - * - * br_xxx_cbcdec_run(const br_xxx_cbcdec_keys *ctx, - * void *iv, void *data, size_t num_blocks) - * Perform CBC decryption of 'len' bytes, in place. The decrypted data - * replaces the ciphertext. 'len' MUST be a multiple of the block length - * (if it is not, the function may loop forever or overflow a buffer). - * The IV is provided with the 'iv' pointer; it is also updated with - * a copy of the last encrypted block. - * - * br_xxx_ctr_keys - * Context structure that contains the subkeys resulting from the key - * expansion. These subkeys are appropriate for CTR encryption and - * decryption. The structure first field is called 'vtable' and - * points to the appropriate OOP structure. - * - * br_xxx_ctr_init(br_xxx_ctr_keys *ctx, const void *key, size_t len) - * Perform key expansion: subkeys for CTR encryption and decryption - * are computed and written in the provided context structure. The - * key length MUST be adequate for the implemented block cipher. This - * function also sets the 'vtable' field. - * - * br_xxx_ctr_run(const br_xxx_ctr_keys *ctx, const void *iv, - * uint32_t cc, void *data, size_t len) [returns uint32_t] - * Perform CTR encryption/decryption of some data. Processing is done - * "in place" (the output data replaces the input data). This function - * implements the "standard incrementing function" from NIST SP800-38A, - * annex B: the IV length shall be 4 bytes less than the block size - * (i.e. 12 bytes for AES) and the counter is the 32-bit value starting - * with 'cc'. The data length ('len') is not necessarily a multiple of - * the block size. The new counter value is returned, which supports - * chunked processing, provided that each chunk length (except possibly - * the last one) is a multiple of the block size. - * - * - * It shall be noted that the key expansion functions return 'void'. If + * - `br_xxx_BLOCK_SIZE` + * + * A macro that evaluates to the block size (in bytes) of the + * cipher. For all implemented block ciphers, this value is a + * power of two. + * + * - `br_xxx_cbcenc_keys` + * + * Context structure that contains the subkeys resulting from the key + * expansion. These subkeys are appropriate for CBC encryption. The + * structure first field is called `vtable` and points to the + * appropriate OOP structure. + * + * - `br_xxx_cbcenc_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)` + * + * Perform key expansion: subkeys for CBC encryption are computed and + * written in the provided context structure. The key length MUST be + * adequate for the implemented block cipher. This function also sets + * the `vtable` field. + * + * - `br_xxx_cbcenc_run(const br_xxx_cbcenc_keys *ctx, void *iv, void *data, size_t len)` + * + * Perform CBC encryption of `len` bytes, in place. The encrypted data + * replaces the cleartext. `len` MUST be a multiple of the block length + * (if it is not, the function may loop forever or overflow a buffer). + * The IV is provided with the `iv` pointer; it is also updated with + * a copy of the last encrypted block. + * + * - `br_xxx_cbcdec_keys` + * + * Context structure that contains the subkeys resulting from the key + * expansion. These subkeys are appropriate for CBC decryption. The + * structure first field is called `vtable` and points to the + * appropriate OOP structure. + * + * - `br_xxx_cbcdec_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)` + * + * Perform key expansion: subkeys for CBC decryption are computed and + * written in the provided context structure. The key length MUST be + * adequate for the implemented block cipher. This function also sets + * the `vtable` field. + * + * - `br_xxx_cbcdec_run(const br_xxx_cbcdec_keys *ctx, void *iv, void *data, size_t num_blocks)` + * + * Perform CBC decryption of `len` bytes, in place. The decrypted data + * replaces the ciphertext. `len` MUST be a multiple of the block length + * (if it is not, the function may loop forever or overflow a buffer). + * The IV is provided with the `iv` pointer; it is also updated with + * a copy of the last _encrypted_ block. + * + * - `br_xxx_ctr_keys` + * + * Context structure that contains the subkeys resulting from the key + * expansion. These subkeys are appropriate for CTR encryption and + * decryption. The structure first field is called `vtable` and + * points to the appropriate OOP structure. + * + * - `br_xxx_ctr_init(br_xxx_ctr_keys *ctx, const void *key, size_t len)` + * + * Perform key expansion: subkeys for CTR encryption and decryption + * are computed and written in the provided context structure. The + * key length MUST be adequate for the implemented block cipher. This + * function also sets the `vtable` field. + * + * - `br_xxx_ctr_run(const br_xxx_ctr_keys *ctx, const void *iv, uint32_t cc, void *data, size_t len)` (returns `uint32_t`) + * + * Perform CTR encryption/decryption of some data. Processing is done + * "in place" (the output data replaces the input data). This function + * implements the "standard incrementing function" from NIST SP800-38A, + * annex B: the IV length shall be 4 bytes less than the block size + * (i.e. 12 bytes for AES) and the counter is the 32-bit value starting + * with `cc`. The data length (`len`) is not necessarily a multiple of + * the block size. The new counter value is returned, which supports + * chunked processing, provided that each chunk length (except possibly + * the last one) is a multiple of the block size. + * + * + * It shall be noted that the key expansion functions return `void`. If * the provided key length is not allowed, then there will be no error * reporting; implementations need not validate the key length, thus an * invalid key length may result in undefined behaviour (e.g. buffer @@ -132,94 +143,267 @@ * discarded without any explicit deallocation. * * - * Object-oriented API: each context structure begins with a field - * (called 'vtable') that points to an instance of a structure that - * references the relevant functions through pointers. Each such - * structure contains the following: + * ## Object-Oriented API + * + * Each context structure begins with a field (called `vtable`) that + * points to an instance of a structure that references the relevant + * functions through pointers. Each such structure contains the + * following: + * + * - `context_size` + * + * The size (in bytes) of the context structure for subkeys. + * + * - `block_size` + * + * The cipher block size (in bytes). + * + * - `log_block_size` + * + * The base-2 logarithm of cipher block size (e.g. 4 for blocks + * of 16 bytes). * - * context_size size (in bytes) of the context structure for subkeys - * block_size cipher block size (in bytes) - * log_block_size base-2 logarithm of cipher block size - * init pointer to the key expansion function - * run pointer to the encryption/decryption function + * - `init` * - * Static, constant instances of these structures are defined, under - * the names: + * Pointer to the key expansion function. * - * br_xxx_cbcenc_vtable - * br_xxx_cbcdec_vtable - * br_xxx_ctr_vtable + * - `run` * + * Pointer to the encryption/decryption function. * - * Implemented Block Ciphers - * ------------------------- + * + * For block cipher "`xxx`", static, constant instances of these + * structures are defined, under the names: + * + * - `br_xxx_cbcenc_vtable` + * - `br_xxx_cbcdec_vtable` + * - `br_xxx_ctr_vtable` + * + * + * ## Implemented Block Ciphers * - * Function Name Allowed key lengths (bytes) + * Provided implementations are: + * + * | Name | Function | Block Size (bytes) | Key lengths (bytes) | + * | :-------- | :------- | :----------------: | :-----------------: | + * | aes_big | AES | 16 | 16, 24 and 32 | + * | aes_small | AES | 16 | 16, 24 and 32 | + * | aes_ct | AES | 16 | 16, 24 and 32 | + * | aes_ct64 | AES | 16 | 16, 24 and 32 | + * | des_ct | DES/3DES | 8 | 8, 16 and 24 | + * | des_tab | DES/3DES | 8 | 8, 16 and 24 | * - * AES aes_ct 16, 24 and 32 - * AES aes_ct64 16, 24 and 32 - * AES aes_big 16, 24 and 32 - * AES aes_small 16, 24 and 32 - * DES des_ct 8, 16 and 24 - * DES des_tab 8, 16 and 24 + * **Note:** DES/3DES nominally uses keys of 64, 128 and 192 bits (i.e. 8, + * 16 and 24 bytes), but some of the bits are ignored by the algorithm, so + * the _effective_ key lengths, from a security point of view, are 56, + * 112 and 168 bits, respectively. * - * 'aes_big' is a "classical" AES implementation, using tables. It + * `aes_big` is a "classical" AES implementation, using tables. It * is fast but not constant-time, since it makes data-dependent array * accesses. * - * 'aes_small' is an AES implementation optimized for code size. It - * is substantially slower than 'aes_big'; it is not constant-time + * `aes_small` is an AES implementation optimized for code size. It + * is substantially slower than `aes_big`; it is not constant-time * either. * - * 'aes_ct' is a constant-time implementation of AES; its code is about - * as big as that of 'aes_big', while its performance is comparable to - * that of 'aes_small'. However, it is constant-time. This + * `aes_ct` is a constant-time implementation of AES; its code is about + * as big as that of `aes_big`, while its performance is comparable to + * that of `aes_small`. However, it is constant-time. This * implementation should thus be considered to be the "default" AES in * BearSSL, to be used unless the operational context guarantees that a * non-constant-time implementation is safe, or an architecture-specific * constant-time implementation can be used (e.g. using dedicated * hardware opcodes). * - * 'aes_ct64' is another constant-time implementation of AES. It is - * similar to 'aes_ct' but uses 64-bit values, for faster processing - * on 64-bit machines. + * `aes_ct64` is another constant-time implementation of AES. It is + * similar to `aes_ct` but uses 64-bit values. On 32-bit machines, + * `aes_ct64` is not faster than `aes_ct`, often a bit slower, and has + * a larger footprint; however, on 64-bit architectures, `aes_ct64` + * is typically twice faster than `aes_ct` for modes that allow parallel + * operations (i.e. CTR, and CBC decryption, but not CBC encryption). * - * 'des_tab' is a classic, table-based implementation of DES/3DES. It + * `des_tab` is a classic, table-based implementation of DES/3DES. It * is not constant-time. * - * 'des_ct' is an constant-time implementation of DES/3DES. It is - * substantially slower than 'des_tab'. + * `des_ct` is an constant-time implementation of DES/3DES. It is + * substantially slower than `des_tab`. */ +/** + * \brief Class type for CBC encryption implementations. + * + * A `br_block_cbcenc_class` instance points to the functions implementing + * a specific block cipher, when used in CBC mode for encrypting data. + */ typedef struct br_block_cbcenc_class_ br_block_cbcenc_class; struct br_block_cbcenc_class_ { + /** + * \brief Size (in bytes) of the context structure appropriate + * for containing subkeys. + */ size_t context_size; + + /** + * \brief Size of individual blocks (in bytes). + */ unsigned block_size; + + /** + * \brief Base-2 logarithm of the size of individual blocks, + * expressed in bytes. + */ unsigned log_block_size; + + /** + * \brief Initialisation function. + * + * This function sets the `vtable` field in the context structure. + * The key length MUST be one of the key lengths supported by + * the implementation. + * + * \param ctx context structure to initialise. + * \param key secret key. + * \param key_len key length (in bytes). + */ void (*init)(const br_block_cbcenc_class **ctx, const void *key, size_t key_len); + + /** + * \brief Run the CBC encryption. + * + * The `iv` parameter points to the IV for this run; it is + * updated with a copy of the last encrypted block. The data + * is encrypted "in place"; its length (`len`) MUST be a + * multiple of the block size. + * + * \param ctx context structure (already initialised). + * \param iv IV for CBC encryption (updated). + * \param data data to encrypt. + * \param len data length (in bytes, multiple of block size). + */ void (*run)(const br_block_cbcenc_class *const *ctx, void *iv, void *data, size_t len); }; +/** + * \brief Class type for CBC decryption implementations. + * + * A `br_block_cbcdec_class` instance points to the functions implementing + * a specific block cipher, when used in CBC mode for decrypting data. + */ typedef struct br_block_cbcdec_class_ br_block_cbcdec_class; struct br_block_cbcdec_class_ { + /** + * \brief Size (in bytes) of the context structure appropriate + * for containing subkeys. + */ size_t context_size; + + /** + * \brief Size of individual blocks (in bytes). + */ unsigned block_size; + + /** + * \brief Base-2 logarithm of the size of individual blocks, + * expressed in bytes. + */ unsigned log_block_size; + + /** + * \brief Initialisation function. + * + * This function sets the `vtable` field in the context structure. + * The key length MUST be one of the key lengths supported by + * the implementation. + * + * \param ctx context structure to initialise. + * \param key secret key. + * \param key_len key length (in bytes). + */ void (*init)(const br_block_cbcdec_class **ctx, const void *key, size_t key_len); + + /** + * \brief Run the CBC decryption. + * + * The `iv` parameter points to the IV for this run; it is + * updated with a copy of the last encrypted block. The data + * is decrypted "in place"; its length (`len`) MUST be a + * multiple of the block size. + * + * \param ctx context structure (already initialised). + * \param iv IV for CBC decryption (updated). + * \param data data to decrypt. + * \param len data length (in bytes, multiple of block size). + */ void (*run)(const br_block_cbcdec_class *const *ctx, void *iv, void *data, size_t len); }; +/** + * \brief Class type for CTR encryption/decryption implementations. + * + * A `br_block_ctr_class` instance points to the functions implementing + * a specific block cipher, when used in CTR mode for encrypting or + * decrypting data. + */ typedef struct br_block_ctr_class_ br_block_ctr_class; struct br_block_ctr_class_ { + /** + * \brief Size (in bytes) of the context structure appropriate + * for containing subkeys. + */ size_t context_size; + + /** + * \brief Size of individual blocks (in bytes). + */ unsigned block_size; + + /** + * \brief Base-2 logarithm of the size of individual blocks, + * expressed in bytes. + */ unsigned log_block_size; + + /** + * \brief Initialisation function. + * + * This function sets the `vtable` field in the context structure. + * The key length MUST be one of the key lengths supported by + * the implementation. + * + * \param ctx context structure to initialise. + * \param key secret key. + * \param key_len key length (in bytes). + */ void (*init)(const br_block_ctr_class **ctx, const void *key, size_t key_len); + + /** + * \brief Run the CTR encryption or decryption. + * + * The `iv` parameter points to the IV for this run; its + * length is exactly 4 bytes less than the block size (e.g. + * 12 bytes for AES/CTR). The IV is combined with a 32-bit + * block counter to produce the block value which is processed + * with the block cipher. + * + * The data to encrypt or decrypt is updated "in place". Its + * length (`len` bytes) is not required to be a multiple of + * the block size; if the final block is partial, then the + * corresponding key stream bits are dropped. + * + * The resulting counter value is returned. + * + * \param ctx context structure (already initialised). + * \param iv IV for CTR encryption/decryption. + * \param cc initial value for the block counter. + * \param data data to encrypt or decrypt. + * \param len data length (in bytes). + * \return the new block counter value. + */ uint32_t (*run)(const br_block_ctr_class *const *ctx, const void *iv, uint32_t cc, void *data, size_t len); }; @@ -231,35 +415,137 @@ struct br_block_ctr_class_ { * and it is not constant-time. In contexts where cache-timing attacks * apply, this implementation may leak the secret key. */ + +/** \brief AES block size (16 bytes). */ #define br_aes_big_BLOCK_SIZE 16 + +/** + * \brief Context for AES subkeys (`aes_big` implementation, CBC encryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_cbcenc_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[60]; unsigned num_rounds; +#endif } br_aes_big_cbcenc_keys; + +/** + * \brief Context for AES subkeys (`aes_big` implementation, CBC decryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_cbcdec_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[60]; unsigned num_rounds; +#endif } br_aes_big_cbcdec_keys; + +/** + * \brief Context for AES subkeys (`aes_big` implementation, CTR encryption + * and decryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_ctr_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[60]; unsigned num_rounds; +#endif } br_aes_big_ctr_keys; + +/** + * \brief Class instance for AES CBC encryption (`aes_big` implementation). + */ extern const br_block_cbcenc_class br_aes_big_cbcenc_vtable; + +/** + * \brief Class instance for AES CBC decryption (`aes_big` implementation). + */ extern const br_block_cbcdec_class br_aes_big_cbcdec_vtable; + +/** + * \brief Class instance for AES CTR encryption and decryption + * (`aes_big` implementation). + */ extern const br_block_ctr_class br_aes_big_ctr_vtable; + +/** + * \brief Context initialisation (key schedule) for AES CBC encryption + * (`aes_big` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_aes_big_cbcenc_init(br_aes_big_cbcenc_keys *ctx, const void *key, size_t len); + +/** + * \brief Context initialisation (key schedule) for AES CBC decryption + * (`aes_big` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_aes_big_cbcdec_init(br_aes_big_cbcdec_keys *ctx, const void *key, size_t len); + +/** + * \brief Context initialisation (key schedule) for AES CTR encryption + * and decryption (`aes_big` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_aes_big_ctr_init(br_aes_big_ctr_keys *ctx, const void *key, size_t len); + +/** + * \brief CBC encryption with AES (`aes_big` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (updated). + * \param data data to encrypt (updated). + * \param len data length (in bytes, MUST be multiple of 16). + */ void br_aes_big_cbcenc_run(const br_aes_big_cbcenc_keys *ctx, void *iv, void *data, size_t len); + +/** + * \brief CBC decryption with AES (`aes_big` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (updated). + * \param data data to decrypt (updated). + * \param len data length (in bytes, MUST be multiple of 16). + */ void br_aes_big_cbcdec_run(const br_aes_big_cbcdec_keys *ctx, void *iv, void *data, size_t len); + +/** + * \brief CTR encryption and decryption with AES (`aes_big` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (constant, 12 bytes). + * \param cc initial block counter value. + * \param data data to decrypt (updated). + * \param len data length (in bytes). + * \return new block counter value. + */ uint32_t br_aes_big_ctr_run(const br_aes_big_ctr_keys *ctx, const void *iv, uint32_t cc, void *data, size_t len); @@ -270,35 +556,137 @@ uint32_t br_aes_big_ctr_run(const br_aes_big_ctr_keys *ctx, * much smaller 256-byte table), which makes it conceptually vulnerable * to cache-timing attacks. */ + +/** \brief AES block size (16 bytes). */ #define br_aes_small_BLOCK_SIZE 16 + +/** + * \brief Context for AES subkeys (`aes_small` implementation, CBC encryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_cbcenc_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[60]; unsigned num_rounds; +#endif } br_aes_small_cbcenc_keys; + +/** + * \brief Context for AES subkeys (`aes_small` implementation, CBC decryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_cbcdec_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[60]; unsigned num_rounds; +#endif } br_aes_small_cbcdec_keys; + +/** + * \brief Context for AES subkeys (`aes_small` implementation, CTR encryption + * and decryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_ctr_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[60]; unsigned num_rounds; +#endif } br_aes_small_ctr_keys; + +/** + * \brief Class instance for AES CBC encryption (`aes_small` implementation). + */ extern const br_block_cbcenc_class br_aes_small_cbcenc_vtable; + +/** + * \brief Class instance for AES CBC decryption (`aes_small` implementation). + */ extern const br_block_cbcdec_class br_aes_small_cbcdec_vtable; + +/** + * \brief Class instance for AES CTR encryption and decryption + * (`aes_small` implementation). + */ extern const br_block_ctr_class br_aes_small_ctr_vtable; + +/** + * \brief Context initialisation (key schedule) for AES CBC encryption + * (`aes_small` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_aes_small_cbcenc_init(br_aes_small_cbcenc_keys *ctx, const void *key, size_t len); + +/** + * \brief Context initialisation (key schedule) for AES CBC decryption + * (`aes_small` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_aes_small_cbcdec_init(br_aes_small_cbcdec_keys *ctx, const void *key, size_t len); + +/** + * \brief Context initialisation (key schedule) for AES CTR encryption + * and decryption (`aes_small` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_aes_small_ctr_init(br_aes_small_ctr_keys *ctx, const void *key, size_t len); + +/** + * \brief CBC encryption with AES (`aes_small` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (updated). + * \param data data to encrypt (updated). + * \param len data length (in bytes, MUST be multiple of 16). + */ void br_aes_small_cbcenc_run(const br_aes_small_cbcenc_keys *ctx, void *iv, void *data, size_t len); + +/** + * \brief CBC decryption with AES (`aes_small` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (updated). + * \param data data to decrypt (updated). + * \param len data length (in bytes, MUST be multiple of 16). + */ void br_aes_small_cbcdec_run(const br_aes_small_cbcdec_keys *ctx, void *iv, void *data, size_t len); + +/** + * \brief CTR encryption and decryption with AES (`aes_small` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (constant, 12 bytes). + * \param cc initial block counter value. + * \param data data to decrypt (updated). + * \param len data length (in bytes). + * \return new block counter value. + */ uint32_t br_aes_small_ctr_run(const br_aes_small_ctr_keys *ctx, const void *iv, uint32_t cc, void *data, size_t len); @@ -308,35 +696,137 @@ uint32_t br_aes_small_ctr_run(const br_aes_small_ctr_keys *ctx, * decryption, slower encryption). However, it is constant-time, i.e. * immune to cache-timing and similar attacks. */ + +/** \brief AES block size (16 bytes). */ #define br_aes_ct_BLOCK_SIZE 16 + +/** + * \brief Context for AES subkeys (`aes_ct` implementation, CBC encryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_cbcenc_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[60]; unsigned num_rounds; +#endif } br_aes_ct_cbcenc_keys; + +/** + * \brief Context for AES subkeys (`aes_ct` implementation, CBC decryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_cbcdec_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[60]; unsigned num_rounds; +#endif } br_aes_ct_cbcdec_keys; + +/** + * \brief Context for AES subkeys (`aes_ct` implementation, CTR encryption + * and decryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_ctr_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[60]; unsigned num_rounds; +#endif } br_aes_ct_ctr_keys; + +/** + * \brief Class instance for AES CBC encryption (`aes_ct` implementation). + */ extern const br_block_cbcenc_class br_aes_ct_cbcenc_vtable; + +/** + * \brief Class instance for AES CBC decryption (`aes_ct` implementation). + */ extern const br_block_cbcdec_class br_aes_ct_cbcdec_vtable; + +/** + * \brief Class instance for AES CTR encryption and decryption + * (`aes_ct` implementation). + */ extern const br_block_ctr_class br_aes_ct_ctr_vtable; + +/** + * \brief Context initialisation (key schedule) for AES CBC encryption + * (`aes_ct` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_aes_ct_cbcenc_init(br_aes_ct_cbcenc_keys *ctx, const void *key, size_t len); + +/** + * \brief Context initialisation (key schedule) for AES CBC decryption + * (`aes_ct` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_aes_ct_cbcdec_init(br_aes_ct_cbcdec_keys *ctx, const void *key, size_t len); + +/** + * \brief Context initialisation (key schedule) for AES CTR encryption + * and decryption (`aes_ct` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_aes_ct_ctr_init(br_aes_ct_ctr_keys *ctx, const void *key, size_t len); + +/** + * \brief CBC encryption with AES (`aes_ct` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (updated). + * \param data data to encrypt (updated). + * \param len data length (in bytes, MUST be multiple of 16). + */ void br_aes_ct_cbcenc_run(const br_aes_ct_cbcenc_keys *ctx, void *iv, void *data, size_t len); + +/** + * \brief CBC decryption with AES (`aes_ct` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (updated). + * \param data data to decrypt (updated). + * \param len data length (in bytes, MUST be multiple of 16). + */ void br_aes_ct_cbcdec_run(const br_aes_ct_cbcdec_keys *ctx, void *iv, void *data, size_t len); + +/** + * \brief CTR encryption and decryption with AES (`aes_ct` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (constant, 12 bytes). + * \param cc initial block counter value. + * \param data data to decrypt (updated). + * \param len data length (in bytes). + * \return new block counter value. + */ uint32_t br_aes_ct_ctr_run(const br_aes_ct_ctr_keys *ctx, const void *iv, uint32_t cc, void *data, size_t len); @@ -348,41 +838,143 @@ uint32_t br_aes_ct_ctr_run(const br_aes_ct_ctr_keys *ctx, * and CTR mode; CBC encryption is non-parallel and cannot benefit from * the larger registers.) */ + +/** \brief AES block size (16 bytes). */ #define br_aes_ct64_BLOCK_SIZE 16 + +/** + * \brief Context for AES subkeys (`aes_ct64` implementation, CBC encryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_cbcenc_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint64_t skey[30]; unsigned num_rounds; +#endif } br_aes_ct64_cbcenc_keys; + +/** + * \brief Context for AES subkeys (`aes_ct64` implementation, CBC decryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_cbcdec_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint64_t skey[30]; unsigned num_rounds; +#endif } br_aes_ct64_cbcdec_keys; + +/** + * \brief Context for AES subkeys (`aes_ct64` implementation, CTR encryption + * and decryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_ctr_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint64_t skey[30]; unsigned num_rounds; +#endif } br_aes_ct64_ctr_keys; + +/** + * \brief Class instance for AES CBC encryption (`aes_ct64` implementation). + */ extern const br_block_cbcenc_class br_aes_ct64_cbcenc_vtable; + +/** + * \brief Class instance for AES CBC decryption (`aes_ct64` implementation). + */ extern const br_block_cbcdec_class br_aes_ct64_cbcdec_vtable; + +/** + * \brief Class instance for AES CTR encryption and decryption + * (`aes_ct64` implementation). + */ extern const br_block_ctr_class br_aes_ct64_ctr_vtable; + +/** + * \brief Context initialisation (key schedule) for AES CBC encryption + * (`aes_ct64` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_aes_ct64_cbcenc_init(br_aes_ct64_cbcenc_keys *ctx, const void *key, size_t len); + +/** + * \brief Context initialisation (key schedule) for AES CBC decryption + * (`aes_ct64` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_aes_ct64_cbcdec_init(br_aes_ct64_cbcdec_keys *ctx, const void *key, size_t len); + +/** + * \brief Context initialisation (key schedule) for AES CTR encryption + * and decryption (`aes_ct64` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_aes_ct64_ctr_init(br_aes_ct64_ctr_keys *ctx, const void *key, size_t len); + +/** + * \brief CBC encryption with AES (`aes_ct64` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (updated). + * \param data data to encrypt (updated). + * \param len data length (in bytes, MUST be multiple of 16). + */ void br_aes_ct64_cbcenc_run(const br_aes_ct64_cbcenc_keys *ctx, void *iv, void *data, size_t len); + +/** + * \brief CBC decryption with AES (`aes_ct64` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (updated). + * \param data data to decrypt (updated). + * \param len data length (in bytes, MUST be multiple of 16). + */ void br_aes_ct64_cbcdec_run(const br_aes_ct64_cbcdec_keys *ctx, void *iv, void *data, size_t len); + +/** + * \brief CTR encryption and decryption with AES (`aes_ct64` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (constant, 12 bytes). + * \param cc initial block counter value. + * \param data data to decrypt (updated). + * \param len data length (in bytes). + * \return new block counter value. + */ uint32_t br_aes_ct64_ctr_run(const br_aes_ct64_ctr_keys *ctx, const void *iv, uint32_t cc, void *data, size_t len); -/* - * These structures are large enough to accommodate subkeys for all - * AES implementations. +/** + * \brief Aggregate structure large enough to be used as context for + * subkeys (CBC encryption) for all AES implementations. */ typedef union { const br_block_cbcenc_class *vtable; @@ -391,6 +983,11 @@ typedef union { br_aes_ct_cbcenc_keys ct; br_aes_ct64_cbcenc_keys ct64; } br_aes_gen_cbcenc_keys; + +/** + * \brief Aggregate structure large enough to be used as context for + * subkeys (CBC decryption) for all AES implementations. + */ typedef union { const br_block_cbcdec_class *vtable; br_aes_big_cbcdec_keys big; @@ -398,6 +995,11 @@ typedef union { br_aes_ct_cbcdec_keys ct; br_aes_ct64_cbcdec_keys ct64; } br_aes_gen_cbcdec_keys; + +/** + * \brief Aggregate structure large enough to be used as context for + * subkeys (CTR encryption and decryption) for all AES implementations. + */ typedef union { const br_block_ctr_class *vtable; br_aes_big_ctr_keys big; @@ -410,25 +1012,91 @@ typedef union { * Traditional, table-based implementation for DES/3DES. Since tables are * used, cache-timing attacks are conceptually possible. */ + +/** \brief DES/3DES block size (8 bytes). */ #define br_des_tab_BLOCK_SIZE 8 + +/** + * \brief Context for DES subkeys (`des_tab` implementation, CBC encryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_cbcenc_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[96]; unsigned num_rounds; +#endif } br_des_tab_cbcenc_keys; + +/** + * \brief Context for DES subkeys (`des_tab` implementation, CBC decryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_cbcdec_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[96]; unsigned num_rounds; +#endif } br_des_tab_cbcdec_keys; + +/** + * \brief Class instance for DES CBC encryption (`des_tab` implementation). + */ extern const br_block_cbcenc_class br_des_tab_cbcenc_vtable; + +/** + * \brief Class instance for DES CBC decryption (`des_tab` implementation). + */ extern const br_block_cbcdec_class br_des_tab_cbcdec_vtable; + +/** + * \brief Context initialisation (key schedule) for DES CBC encryption + * (`des_tab` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_des_tab_cbcenc_init(br_des_tab_cbcenc_keys *ctx, const void *key, size_t len); + +/** + * \brief Context initialisation (key schedule) for DES CBC decryption + * (`des_tab` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_des_tab_cbcdec_init(br_des_tab_cbcdec_keys *ctx, const void *key, size_t len); + +/** + * \brief CBC encryption with DES (`des_tab` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (updated). + * \param data data to encrypt (updated). + * \param len data length (in bytes, MUST be multiple of 8). + */ void br_des_tab_cbcenc_run(const br_des_tab_cbcenc_keys *ctx, void *iv, void *data, size_t len); + +/** + * \brief CBC decryption with DES (`des_tab` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (updated). + * \param data data to decrypt (updated). + * \param len data length (in bytes, MUST be multiple of 8). + */ void br_des_tab_cbcdec_run(const br_des_tab_cbcdec_keys *ctx, void *iv, void *data, size_t len); @@ -436,25 +1104,91 @@ void br_des_tab_cbcdec_run(const br_des_tab_cbcdec_keys *ctx, void *iv, * Constant-time implementation for DES/3DES. It is substantially slower * (by a factor of about 4x), but also immune to cache-timing attacks. */ + +/** \brief DES/3DES block size (8 bytes). */ #define br_des_ct_BLOCK_SIZE 8 + +/** + * \brief Context for DES subkeys (`des_ct` implementation, CBC encryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_cbcenc_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[96]; unsigned num_rounds; +#endif } br_des_ct_cbcenc_keys; + +/** + * \brief Context for DES subkeys (`des_ct` implementation, CBC decryption). + * + * First field is a pointer to the vtable; it is set by the initialisation + * function. Other fields are not supposed to be accessed by user code. + */ typedef struct { + /** \brief Pointer to vtable for this context. */ const br_block_cbcdec_class *vtable; +#ifndef BR_DOXYGEN_IGNORE uint32_t skey[96]; unsigned num_rounds; +#endif } br_des_ct_cbcdec_keys; + +/** + * \brief Class instance for DES CBC encryption (`des_ct` implementation). + */ extern const br_block_cbcenc_class br_des_ct_cbcenc_vtable; + +/** + * \brief Class instance for DES CBC decryption (`des_ct` implementation). + */ extern const br_block_cbcdec_class br_des_ct_cbcdec_vtable; + +/** + * \brief Context initialisation (key schedule) for DES CBC encryption + * (`des_ct` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_des_ct_cbcenc_init(br_des_ct_cbcenc_keys *ctx, const void *key, size_t len); + +/** + * \brief Context initialisation (key schedule) for DES CBC decryption + * (`des_ct` implementation). + * + * \param ctx context to initialise. + * \param key secret key. + * \param len secret key length (in bytes). + */ void br_des_ct_cbcdec_init(br_des_ct_cbcdec_keys *ctx, const void *key, size_t len); + +/** + * \brief CBC encryption with DES (`des_ct` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (updated). + * \param data data to encrypt (updated). + * \param len data length (in bytes, MUST be multiple of 8). + */ void br_des_ct_cbcenc_run(const br_des_ct_cbcenc_keys *ctx, void *iv, void *data, size_t len); + +/** + * \brief CBC decryption with DES (`des_ct` implementation). + * + * \param ctx context (already initialised). + * \param iv IV (updated). + * \param data data to decrypt (updated). + * \param len data length (in bytes, MUST be multiple of 8). + */ void br_des_ct_cbcdec_run(const br_des_ct_cbcdec_keys *ctx, void *iv, void *data, size_t len); @@ -462,11 +1196,21 @@ void br_des_ct_cbcdec_run(const br_des_ct_cbcdec_keys *ctx, void *iv, * These structures are large enough to accommodate subkeys for all * DES/3DES implementations. */ + +/** + * \brief Aggregate structure large enough to be used as context for + * subkeys (CBC encryption) for all DES implementations. + */ typedef union { const br_block_cbcenc_class *vtable; br_des_tab_cbcenc_keys tab; br_des_ct_cbcenc_keys ct; } br_des_gen_cbcenc_keys; + +/** + * \brief Aggregate structure large enough to be used as context for + * subkeys (CBC decryption) for all DES implementations. + */ typedef union { const br_block_cbcdec_class *vtable; br_des_tab_cbcdec_keys tab;