nettle.info: CBC

Cipher modes

CTR

Cipher modes

Back to Software Index

7.3.1 Cipher Block Chaining
---------------------------

When using CBC mode, plaintext blocks are not encrypted independently of
each other, like in Electronic Cook Book mode.  Instead, when encrypting
a block in CBC mode, the previous ciphertext block is XORed with the
plaintext before it is fed to the block cipher.  When encrypting the
first block, a random block called an “IV”, or Initialization Vector, is
used as the “previous ciphertext block”.  The IV should be chosen
randomly, but it need not be kept secret, and can even be transmitted in
the clear together with the encrypted data.

   In symbols, if ‘E_k’ is the encryption function of a block cipher,
and ‘IV’ is the initialization vector, then ‘n’ plaintext blocks
‘M_1’,... ‘M_n’ are transformed into ‘n’ ciphertext blocks ‘C_1’,...
‘C_n’ as follows:

     C_1 = E_k(IV  XOR M_1)
     C_2 = E_k(C_1 XOR M_2)

     ...

     C_n = E_k(C_(n-1) XOR M_n)

   Nettle’s includes two functions for applying a block cipher in Cipher
Block Chaining (CBC) mode, one for encryption and one for decryption.
These functions uses ‘void *’ to pass cipher contexts around.

 -- Function: void cbc_encrypt (const void *CTX, nettle_cipher_func *F,
          size_t BLOCK_SIZE, uint8_t *IV, size_t LENGTH, uint8_t *DST,
          const uint8_t *SRC)
 -- Function: void cbc_decrypt (const void *CTX, nettle_cipher_func *F,
          size_t BLOCK_SIZE, uint8_t *IV, size_t LENGTH, uint8_t *DST,
          const uint8_t *SRC)

     Applies the encryption or decryption function F in CBC mode.  The
     final ciphertext block processed is copied into IV before
     returning, so that a large message can be processed by a sequence
     of calls to ‘cbc_encrypt’.  The function F is of type

     ‘void f (void *CTX, size_t LENGTH, uint8_t DST, const uint8_t
     *SRC)’,

     and the ‘cbc_encrypt’ and ‘cbc_decrypt’ functions pass their
     argument CTX on to F.

   There are also some macros to help use these functions correctly.

 -- Macro: CBC_CTX (CONTEXT_TYPE, BLOCK_SIZE)
     Expands to
          {
             context_type ctx;
             uint8_t iv[block_size];
          }

   It can be used to define a CBC context struct, either directly,

     struct CBC_CTX(struct aes_ctx, AES_BLOCK_SIZE) ctx;

   or to give it a struct tag,

     struct aes_cbc_ctx CBC_CTX (struct aes_ctx, AES_BLOCK_SIZE);

 -- Macro: CBC_SET_IV (CTX, IV)
     First argument is a pointer to a context struct as defined by
     ‘CBC_CTX’, and the second is a pointer to an Initialization Vector
     (IV) that is copied into that context.

 -- Macro: CBC_ENCRYPT (CTX, F, LENGTH, DST, SRC)
 -- Macro: CBC_DECRYPT (CTX, F, LENGTH, DST, SRC)
     A simpler way to invoke ‘cbc_encrypt’ and ‘cbc_decrypt’.  The first
     argument is a pointer to a context struct as defined by ‘CBC_CTX’,
     and the second argument is an encryption or decryption function
     following Nettle’s conventions.  The last three arguments define
     the source and destination area for the operation.

   These macros use some tricks to make the compiler display a warning
if the types of F and CTX don’t match, e.g.  if you try to use an
‘struct aes_ctx’ context with the ‘des_encrypt’ function.