SIV-CMAC mode, based on patch by Nikos Mavrogiannopoulos

This AEAD algorithm provides a way to make nonce-reuse a not critical
issue. That is particular useful to stateless servers that cannot
ensure that the nonce will not repeat. This cipher is used by
draft-ietf-ntp-using-nts-for-ntp-17.

1 files changed, 104 insertions, 1 deletions

diff --git a/nettle.texinfo b/nettle.texinfo
index 596c7098..bda807db 100644
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -97,6 +97,7 @@ Cipher modes
 * CFB and CFB8::
 * GCM::                         
 * CCM::                         
+* SIV-CMAC::
 
 Keyed Hash Functions
 
@@ -2565,6 +2566,7 @@ more adventurous alternative, in particular if performance is important.
 * GCM::                         
 * CCM::                         
 * ChaCha-Poly1305::
+* SIV-CMAC::
 * nettle_aead abstraction::
 @end menu
 
@@ -3212,7 +3214,7 @@ These are identical to @code{ccm_encrypt_message} and @code{ccm_decrypt_message}
 except that @var{cipher} and @var{f} are replaced with a context structure.
 @end deftypefun
 
-@node ChaCha-Poly1305, nettle_aead abstraction, CCM, Authenticated encryption
+@node ChaCha-Poly1305, SIV-CMAC, CCM, Authenticated encryption
 @comment  node-name,  next,  previous,  up
 @subsection ChaCha-Poly1305
 
@@ -3295,6 +3297,107 @@ smaller than @code{CHACHA_POLY1305_DIGEST_SIZE}, only the first
 @var{length} octets of the digest are written.
 @end deftypefun
 
+@node SIV-CMAC, nettle_aead abstraction, ChaCha-Poly1305, Authenticated encryption
+@comment  node-name,  next,  previous,  up
+@subsection Synthetic Initialization Vector AEAD
+
+@cindex SIV mode
+@cindex SIV-CMAC mode
+
+@acronym{SIV-CMAC} mode is a combination of counter mode with message
+authentication based on @acronym{CMAC}. Unlike other counter @acronym{AEAD}
+modes, it provides protection against accidental nonce misuse, making it
+a good choice for stateless-servers that cannot ensure nonce uniqueness.
+It is constructed on top of a block cipher which must have a block size of
+128 bits. Nettle's support for @acronym{SIV-CMAC} consists of
+a message encryption and authentication interface, for
+@acronym{SIV-CMAC} using AES as the underlying block cipher.
+When a nonce is re-used with this mode, message authenticity is retained
+however an attacker can determine whether the same plaintext was protected
+with the two messages sharing the nonce.
+These interfaces are defined in @file{<nettle/siv-cmac.h>}.
+
+Unlike other @acronym{AEAD} mode in @acronym{SIV-CMAC} the initialization
+vector serves as the tag. That means that in the generated ciphertext
+the tag precedes the ciphertext.
+
+Note also, that the @acronym{SIV-CMAC} algorithm, as specified in
+@cite{RFC 5297}, introduces the notion of authenticated data which
+consist of multiple components. For example with @acronym{SIV-CMAC} the
+authentication tag of data @code{X} followed by @code{Y}, is different
+than the concatenated data @code{X || Y}. The interfaces described below
+follow the @acronym{AEAD} paradigm and uses a fix structure with single
+string of authenticated data, a nonce, and the plaintext message itself.
+In the terminology of the RFC, the input to the S2V function is always a
+vector of three elements, where S1 is the authenticated data, S2 is the
+nonce, and S3 is the plaintext.
+
+@emph{Empty nonce should be considered experimental:} The specification
+also discusses nonce-less mode of operation, where the nonce is omitted
+in the S2V input vector; this leads to some confusion on how to do
+SIV-CMAC when the nonce is an empty string: Should S2 be an empty
+string, or should this mean nonce-less mode? Nettle's implementation
+currently uses an empty S2, but this may have interoperability issues.
+If standards emerge, Nettle's implementation may be changed to follow.
+In principle, we have the same ambiguity with empty associated data, but
+at the time of writing, Nettle authors are not aware of any
+interoperability problems with this.
+
+@subsubsection General interface
+
+@defvr Constant SIV_BLOCK_SIZE
+@acronym{SIV-CMAC}'s block size, 16.
+@end defvr
+
+@defvr Constant SIV_DIGEST_SIZE
+Size of the @acronym{SIV-CMAC} digest or initialization vector, 16.
+@end defvr
+
+@subsubsection @acronym{SIV-CMAC}-@acronym{AES} interface
+
+The @acronym{AES} @acronym{SIV-CMAC} functions provide an API for using
+@acronym{SIV-CMAC} mode with the @acronym{AES} block ciphers. The parameters
+all have the same meaning as the general and message interfaces, except
+that the @var{cipher}, @var{f}, and @var{ctx} parameters are replaced
+with an @acronym{AES} context structure, and a set-key function must be
+called before using any of the other functions in this interface.
+
+@deftp {Context struct} {struct siv_cmac_aes128_ctx}
+Holds state corresponding to a particular message encrypted using the
+AES-128 block cipher.
+@end deftp
+
+@deftp {Context struct} {struct siv_cmac_aes256_ctx}
+Holds state corresponding to a particular message encrypted using the
+AES-256 block cipher.
+@end deftp
+
+@deftypefun void siv_cmac_aes128_set_key (struct siv_cmac_aes128_ctx *@var{ctx}, const uint8_t *@var{key})
+@deftypefunx void siv_cmac_aes256_set_key (struct siv_cmac_aes256_ctx *@var{ctx}, const uint8_t *@var{key})
+Initializes the encryption key for the AES block cipher. One of these
+functions must be called before any of the other functions in the
+@acronym{AES} @acronym{SIV-CMAC} interface.
+@end deftypefun
+
+@deftypefun void siv_cmac_aes128_encrypt_message (struct siv_cmac_aes128_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src})
+@deftypefunx void siv_cmac_aes256_encrypt_message (struct siv_cmac_aes256_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src})
+Computes the message digest from the @var{adata} and @var{src}
+parameters, encrypts the plaintext from @var{src}, prepends the
+initialization vector to the ciphertext and outputs it to @var{dst}.
+The @var{clength} variable must be equal to the length of @var{src}
+plus @code{SIV_DIGEST_SIZE}.
+
+@end deftypefun
+
+@deftypefun int siv_cmac_aes128_decrypt_message (struct siv_cmac_aes128_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src})
+@deftypefunx int siv_cmac_aes256_decrypt_message (struct siv_cmac_aes128_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src})
+Decrypts the ciphertext from @var{src}, outputs the plaintext to
+@var{dst}, recalculates the initialization vector from @var{adata} and the
+plaintext. If the values of the received and calculated initialization vector
+are equal, this will return 1 indicating a valid and authenticated
+message. Otherwise, this function will return zero.
+@end deftypefun
+
 @node nettle_aead abstraction, , ChaCha-Poly1305, Authenticated encryption
 @comment  node-name,  next,  previous,  up
 @subsection The @code{struct nettle_aead} abstraction