Add CFB8 - Cipher Feedback 8-bit block cipher mode

Add CFB variant with 8-bit segment size.

Signed-off-by: Dmitry Eremin-Solenikov <dbaryshkov@gmail.com>

1 files changed, 87 insertions, 19 deletions

diff --git a/nettle.texinfo b/nettle.texinfo
index aa374449..f501cfbe 100644
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -93,7 +93,7 @@ Cipher modes
 
 * CBC::                         
 * CTR::                         
-* CFB::
+* CFB and CFB8::
 * GCM::                         
 * CCM::                         
 
@@ -1904,21 +1904,21 @@ Book mode, @acronym{ECB}), leaks information.
 
 Besides @acronym{ECB}, Nettle provides several other modes of operation:
 Cipher Block Chaining (@acronym{CBC}), Counter mode (@acronym{CTR}), Cipher
-Feedback (@acronym{CFB}) and a couple of @acronym{AEAD} modes
-(@pxref{Authenticated encryption}).  @acronym{CBC} is widely used, but
+Feedback (@acronym{CFB} and @acronym{CFB8}) and a couple of @acronym{AEAD}
+modes (@pxref{Authenticated encryption}).  @acronym{CBC} is widely used, but
 there are a few subtle issues of information leakage, see, e.g.,
 @uref{http://www.kb.cert.org/vuls/id/958563, @acronym{SSH} @acronym{CBC}
 vulnerability}. Today, @acronym{CTR} is usually preferred over @acronym{CBC}.
 
-Modes like @acronym{CBC}, @acronym{CTR} and @acronym{CFB} provide @emph{no}
-message authentication, and should always be used together with a
-@acronym{MAC} (@pxref{Keyed hash functions}) or signature to authenticate
-the message.
+Modes like @acronym{CBC}, @acronym{CTR}, @acronym{CFB} and @acronym{CFB8}
+provide @emph{no} message authentication, and should always be used together
+with a @acronym{MAC} (@pxref{Keyed hash functions}) or signature to
+authenticate the message.
 
 @menu
 * CBC::                         
 * CTR::                         
-* CFB::
+* CFB and CFB8::
 @end menu
 
 @node CBC, CTR, Cipher modes, Cipher modes
@@ -2014,7 +2014,7 @@ These macros use some tricks to make the compiler display a warning if
 the types of @var{f} and @var{ctx} don't match, e.g. if you try to use
 an @code{struct aes_ctx} context with the @code{des_encrypt} function.
 
-@node CTR, CFB, CBC, Cipher modes
+@node CTR, CFB and CFB8, CBC, Cipher modes
 @comment  node-name,  next,  previous,  up
 @subsection Counter mode
 
@@ -2090,18 +2090,21 @@ last three arguments define the source and destination area for the
 operation.
 @end deffn
 
-@node CFB, , CTR, Cipher modes
+@node CFB and CFB8, , CTR, Cipher modes
 @comment  node-name,  next,  previous,  up
 @subsection Cipher Feedback mode
 
 @cindex Cipher Feedback Mode
-@cindex CFB Mode
+@cindex Cipher Feedback 8-bit Mode
+@cindex CFB Modes
+@cindex CFB8 Mode
 
-Cipher Feedback mode (@acronym{CFB}) being a close relative to both
-@acronym{CBC} mode and @acronym{CTR} mode borrows some characteristics
-from stream ciphers.
 
-The message is divided into @code{n} blocks @code{M_1},@dots{}
+Cipher Feedback mode (@acronym{CFB}) and Cipher Feedback 8-bit mode
+(@acronym{CFB8}) being close relatives to both @acronym{CBC} mode and
+@acronym{CTR} mode borrow some characteristics from stream ciphers.
+
+For CFB the message is divided into @code{n} blocks @code{M_1},@dots{}
 @code{M_n}, where @code{M_n} is of size @code{m} which may be smaller
 than the block size. Except for the last block, all the message blocks
 must be of size equal to the cipher's block size.
@@ -2121,10 +2124,31 @@ C_(n-1) = E_k(C_(n - 2)) XOR M_(n-1)
 C_n = E_k(C_(n - 1)) [1..m] XOR M_n
 @end example
 
-Nettle's includes two functions for applying a block cipher in Cipher
-Feedback (@acronym{CFB}) mode, one for encryption and one for
-decryption. These functions uses @code{void *} to pass cipher contexts
-around.
+Cipher Feedback 8-bit mode (@acronym{CFB8}) transforms block cipher into a stream
+cipher. The message is encrypted byte after byte, not requiring any padding.
+
+If @code{E_k} is the encryption function of a block cipher, @code{b} is
+@code{E_k} block size, @code{IV} is the initialization vector, then the
+@code{n} plaintext bytes are transformed into @code{n} ciphertext bytes
+@code{C_1},@dots{} @code{C_n} as follows:
+
+@example
+I_1 = IV
+C_1 = E_k(I_1) [1..8] XOR M_1
+I_2 = I_1 [9..b] << 8 | C_1
+C_2 = E_k(I_2) [1..8] XOR M_2
+
+@dots{}
+
+I_(n-1) = I_(n-2) [9..b] << 8 | C_(n-2)
+C_(n-1) = E_k(I_(n-1)) [1..8] XOR M_(n-1)
+I_n = I_(n-1) [9..b] << 8 | C_(n-1)
+C_n = E_k(I_n) [1..8] XOR M_n
+@end example
+
+Nettle's includes functions for applying a block cipher in Cipher
+Feedback (@acronym{CFB}) and Cipher Feedback 8-bit (@acronym{CFB8})
+modes. These functions uses @code{void *} to pass cipher contexts around.
 
 @deftypefun {void} cfb_encrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
 @deftypefunx {void} cfb_decrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
@@ -2141,6 +2165,18 @@ When a message is encrypted using a sequence of calls to
 is a multiple of the block size.
 @end deftypefun
 
+@deftypefun {void} cfb8_encrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
+@deftypefunx {void} cfb8_decrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src})
+
+Applies the encryption or decryption function @var{f} in @acronym{CFB8}
+mode. The final IV block processed is copied into @var{iv}
+before returning, so that a large message can be processed by a sequence of
+calls to @code{cfb8_encrypt}. Note that for @acronym{CFB8} mode internally
+uses encryption only function and hence @var{f} should always be the
+encryption function for the underlying block cipher.
+
+@end deftypefun
+
 Like for @acronym{CBC}, there are also a couple of helper macros.
 
 @deffn Macro CFB_CTX (@var{context_type}, @var{block_size})
@@ -2175,6 +2211,38 @@ last three arguments define the source and destination area for the
 operation.
 @end deffn
 
+@deffn Macro CFB8_CTX (@var{context_type}, @var{block_size})
+Expands to
+@example
+@{
+   context_type ctx;
+   uint8_t iv[block_size];
+@}
+@end example
+@end deffn
+
+@deffn Macro CFB8_SET_IV(@var{ctx}, @var{iv})
+First argument is a pointer to a context struct as defined by
+@code{CFB8_CTX}, and the second is a pointer to an initialization vector
+that is copied into that context.
+@end deffn
+
+@deffn Macro CFB8_ENCRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src})
+A simpler way to invoke @code{cfb8_encrypt}. The first argument is a
+pointer to a context struct as defined by @code{CFB8_CTX}, and the
+second argument is an encryption function following Nettle's
+conventions. The last three arguments define the source and destination
+area for the operation.
+@end deffn
+
+@deffn Macro CFB8_DECRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src})
+A simpler way to invoke @code{cfb8_decrypt}. The first argument is a
+pointer to a context struct as defined by @code{CFB8_CTX}, and the
+second argument is an encryption function following Nettle's
+conventions. The last three arguments define the source and destination
+area for the operation.
+@end deffn
+
 @node Authenticated encryption, Keyed hash functions, Cipher modes, Reference
 @comment  node-name,  next,  previous,  up