nettle: CBC

1 
1 6.3.1 Cipher Block Chaining
1 ---------------------------
1 
1 When using CBC mode, plaintext blocks are not encrypted independently of
1 each other, like in Electronic Cook Book mode.  Instead, when encrypting
1 a block in CBC mode, the previous ciphertext block is XORed with the
1 plaintext before it is fed to the block cipher.  When encrypting the
1 first block, a random block called an “IV”, or Initialization Vector, is
1 used as the “previous ciphertext block”.  The IV should be chosen
1 randomly, but it need not be kept secret, and can even be transmitted in
1 the clear together with the encrypted data.
1 
1    In symbols, if ‘E_k’ is the encryption function of a block cipher,
1 and ‘IV’ is the initialization vector, then ‘n’ plaintext blocks
1 ‘M_1’,... ‘M_n’ are transformed into ‘n’ ciphertext blocks ‘C_1’,...
1 ‘C_n’ as follows:
1 
1      C_1 = E_k(IV  XOR M_1)
1      C_2 = E_k(C_1 XOR M_2)
1 
1      ...
1 
1      C_n = E_k(C_(n-1) XOR M_n)
1 
1    Nettle’s includes two functions for applying a block cipher in Cipher
1 Block Chaining (CBC) mode, one for encryption and one for decryption.
1 These functions uses ‘void *’ to pass cipher contexts around.
1 
1  -- Function: void cbc_encrypt (const void *CTX, nettle_cipher_func *F,
1           size_t BLOCK_SIZE, uint8_t *IV, size_t LENGTH, uint8_t *DST,
1           const uint8_t *SRC)
1  -- Function: void cbc_decrypt (const void *CTX, nettle_cipher_func *F,
1           size_t BLOCK_SIZE, uint8_t *IV, size_t LENGTH, uint8_t *DST,
1           const uint8_t *SRC)
1 
1      Applies the encryption or decryption function F in CBC mode.  The
1      final ciphertext block processed is copied into IV before
1      returning, so that a large message can be processed by a sequence
1      of calls to ‘cbc_encrypt’.  The function F is of type
1 
1      ‘void f (void *CTX, size_t LENGTH, uint8_t DST, const uint8_t
1      *SRC)’,
1 
1      and the ‘cbc_encrypt’ and ‘cbc_decrypt’ functions pass their
1      argument CTX on to F.
1 
1    There are also some macros to help use these functions correctly.
1 
1  -- Macro: CBC_CTX (CONTEXT_TYPE, BLOCK_SIZE)
1      Expands to
1           {
1              context_type ctx;
1              uint8_t iv[block_size];
1           }
1 
1    It can be used to define a CBC context struct, either directly,
1 
1      struct CBC_CTX(struct aes_ctx, AES_BLOCK_SIZE) ctx;
1 
1    or to give it a struct tag,
1 
1      struct aes_cbc_ctx CBC_CTX (struct aes_ctx, AES_BLOCK_SIZE);
1 
1  -- Macro: CBC_SET_IV (CTX, IV)
1      First argument is a pointer to a context struct as defined by
1      ‘CBC_CTX’, and the second is a pointer to an Initialization Vector
1      (IV) that is copied into that context.
1 
1  -- Macro: CBC_ENCRYPT (CTX, F, LENGTH, DST, SRC)
1  -- Macro: CBC_DECRYPT (CTX, F, LENGTH, DST, SRC)
1      A simpler way to invoke ‘cbc_encrypt’ and ‘cbc_decrypt’.  The first
1      argument is a pointer to a context struct as defined by ‘CBC_CTX’,
1      and the second argument is an encryption or decryption function
1      following Nettle’s conventions.  The last three arguments define
1      the source and destination area for the operation.
1 
1    These macros use some tricks to make the compiler display a warning
1 if the types of F and CTX don’t match, e.g.  if you try to use an
1 ‘struct aes_ctx’ context with the ‘des_encrypt’ function.
1