Move AEAD documentation to its own section.

diff --git a/ChangeLog b/ChangeLog
index b55ce5a2a93259249bf82497a8bba85717dd76b8..b84464b32201aeab539f06f2c87822860d26ff60 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,8 @@
 2014-05-05  Niels Möller  <nisse@lysator.liu.se>
 
        * nettle.texinfo (POLY1305): Document poly1305-aes.
+       (Authenticated encryption): Make Authenticated encryption a
+       separate section.
 
 2014-05-04  Niels Möller  <nisse@lysator.liu.se>
 

diff --git a/nettle.texinfo b/nettle.texinfo
index 0dc9a9e3b1862204864416039916da299619846e..79bd98fd07ba65198bb3ed2276bda736228932b5 100644 (file)
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -365,6 +365,7 @@ This chapter describes all the Nettle functions, grouped by family.
 * Hash functions::              
 * Cipher functions::            
 * Cipher modes::                
+* Authenticated encryption::
 * Keyed hash functions::        
 * Key derivation functions::    
 * Public-key algorithms::       
@@ -1847,7 +1848,7 @@ This list can be used to dynamically enumerate or search the supported
 algorithms. NULL-terminated.
 @end deftypevr
 
-@node Cipher modes, Keyed hash functions, Cipher functions, Reference
+@node Cipher modes, Authenticated encryption, Cipher functions, Reference
 @comment  node-name,  next,  previous,  up
 @section Cipher modes
 
@@ -1868,84 +1869,9 @@ Modes like @acronym{CBC} and @acronym{CTR} 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.
 
-@subsection Authenticated encryption with associated data
-@cindex AEAD
-@cindex Authenticated encryption
-
-Since there are some subtle design choices to be made when combining a
-block cipher mode with out authentication with a @acronym{MAC}. In
-recent years, several constructions that combine encryption and
-authentication have been defined. These constructions typically also
-have an additional input, the ``associated data'', which is
-authenticated but not included with the message. A simple example is an
-implicit message number which is available at both sender and receiver,
-and which needs authentication in order to detect deletions or replay of
-messages. This family of building blocks are therefore called
-@acronym{AEAD}, Authenticated encryption with associated data.
-
-The aim is to provide building blocks that it is easier for designers of
-protocols and applications to use correctly. There is also some
-potential for improved performance, if encryption and authentication can
-be done in a single step, although that potential is not realized for
-the constructions currently supported by Nettle.
-
-For encryption, the inputs are:
-
-@itemize
-@item
-The key, which can be used for many messages.
-@item 
-A nonce, which must be unique for each message using the same key.
-@item
-Additional associated data to be authenticated, but not included in the
-message.
-@item
-The cleartext message to be encrypted.
-@end itemize
-
-The outputs are:
-
-@itemize
-@item
-The ciphertext, of the same size as the cleartext.
-@item
-A digest or ``authentication tag''.
-@end itemize
-
-Decryption works the same, but with cleartext and ciphertext
-interchanged. All currently supported @acronym{AEAD} algorithms always
-use the encryption function of the underlying block cipher, for both
-encryption and decryption.
-
-Usually, the authentication tag should be appended at the end of the
-ciphertext, producing an encrypted message which is slightly longer than
-the cleartext. However, Nettle's low level @acronym{AEAD} functions
-produce the authentication tag as a separate output for both encryption
-and decryption.
-
-Both associated data and the message data (cleartext or ciphertext) can
-be processed incrementally. In general, all associated data must be
-processed before the message data, and all calls but the last one must
-use a length that is a multiple of he block size, although some
-@acronym{AEAD} may implement more liberal conventions. The @acronym{CCM}
-mode is a bit special in that it requires the message lengths up front,
-other @acronym{AEAD} constructions don't have this restriction.
-
-The supported @acronym{AEAD} constructions are Galois/Counter mode
-(@acronym{GCM}), @acronym{EAX}, and Counter with
-@acronym{CBC}-@acronym{MAC} (@acronym{CCM}). There are some weaknesses
-in @acronym{GCM} authentication, see
-@uref{http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments/CWC-GCM/Ferguson2.pdf}.
-@acronym{CCM} and @acronym{EAX} use the same building blocks, but the
-@acronym{EAX} design is cleaner and avoids a couple of inconveniences of
-@acronym{CCM}. Therefore, @acronym{EAX} seems like a good choice.
-
 @menu
 * CBC::                         
 * CTR::                         
-* EAX::                         
-* GCM::                         
-* CCM::                         
 @end menu
 @c FIXME: chacha-poly1305
 
@@ -2042,7 +1968,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, EAX, CBC, Cipher modes
+@node CTR, , CBC, Cipher modes
 @comment  node-name,  next,  previous,  up
 @subsection Counter mode
 
@@ -2118,7 +2044,89 @@ last three arguments define the source and destination area for the
 operation.
 @end deffn
 
-@node EAX, GCM, CTR, Cipher modes
+@node Authenticated encryption, Keyed hash functions, Cipher modes, Reference
+@comment  node-name,  next,  previous,  up
+
+@section Authenticated encryption with associated data
+@cindex AEAD
+@cindex Authenticated encryption
+
+Since there are some subtle design choices to be made when combining a
+block cipher mode with out authentication with a @acronym{MAC}. In
+recent years, several constructions that combine encryption and
+authentication have been defined. These constructions typically also
+have an additional input, the ``associated data'', which is
+authenticated but not included with the message. A simple example is an
+implicit message number which is available at both sender and receiver,
+and which needs authentication in order to detect deletions or replay of
+messages. This family of building blocks are therefore called
+@acronym{AEAD}, Authenticated encryption with associated data.
+
+The aim is to provide building blocks that it is easier for designers of
+protocols and applications to use correctly. There is also some
+potential for improved performance, if encryption and authentication can
+be done in a single step, although that potential is not realized for
+the constructions currently supported by Nettle.
+
+For encryption, the inputs are:
+
+@itemize
+@item
+The key, which can be used for many messages.
+@item 
+A nonce, which must be unique for each message using the same key.
+@item
+Additional associated data to be authenticated, but not included in the
+message.
+@item
+The cleartext message to be encrypted.
+@end itemize
+
+The outputs are:
+
+@itemize
+@item
+The ciphertext, of the same size as the cleartext.
+@item
+A digest or ``authentication tag''.
+@end itemize
+
+Decryption works the same, but with cleartext and ciphertext
+interchanged. All currently supported @acronym{AEAD} algorithms always
+use the encryption function of the underlying block cipher, for both
+encryption and decryption.
+
+Usually, the authentication tag should be appended at the end of the
+ciphertext, producing an encrypted message which is slightly longer than
+the cleartext. However, Nettle's low level @acronym{AEAD} functions
+produce the authentication tag as a separate output for both encryption
+and decryption.
+
+Both associated data and the message data (cleartext or ciphertext) can
+be processed incrementally. In general, all associated data must be
+processed before the message data, and all calls but the last one must
+use a length that is a multiple of he block size, although some
+@acronym{AEAD} may implement more liberal conventions. The @acronym{CCM}
+mode is a bit special in that it requires the message lengths up front,
+other @acronym{AEAD} constructions don't have this restriction.
+
+The supported @acronym{AEAD} constructions are Galois/Counter mode
+(@acronym{GCM}), @acronym{EAX}, and Counter with
+@acronym{CBC}-@acronym{MAC} (@acronym{CCM}). There are some weaknesses
+in @acronym{GCM} authentication, see
+@uref{http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments/CWC-GCM/Ferguson2.pdf}.
+@acronym{CCM} and @acronym{EAX} use the same building blocks, but the
+@acronym{EAX} design is cleaner and avoids a couple of inconveniences of
+@acronym{CCM}. Therefore, @acronym{EAX} seems like a good conservative
+choice.
+
+@menu
+* EAX::                         
+* GCM::                         
+* CCM::                         
+@end menu
+
+@node EAX, GCM, Authenticated encryption, Authenticated encryption
 @comment  node-name,  next,  previous,  up
 @subsection EAX
 
@@ -2273,7 +2281,7 @@ smaller than @code{EAX_DIGEST_SIZE}, only the first @var{length} octets
 of the digest are written.
 @end deftypefun
 
-@node GCM, CCM, EAX, Cipher modes
+@node GCM, CCM, EAX, Authenticated encryption
 @comment  node-name,  next,  previous,  up
 @subsection Galois counter mode
 
@@ -2535,7 +2543,7 @@ that @var{length} is @code{GCM_DIGEST_SIZE}, but if you provide a smaller
 value, only the first @var{length} octets of the digest are written.
 @end deftypefun
 
-@node CCM,  , GCM, Cipher modes
+@node CCM,  , GCM, Authenticated encryption
 @comment  node-name,  next,  previous,  up
 @subsection Counter with CBC-MAC mode
 
@@ -2764,7 +2772,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 Keyed hash functions, Key derivation functions, Cipher modes, Reference
+@node Keyed hash functions, Key derivation functions, Authenticated encryption, Reference
 @comment  node-name,  next,  previous,  up
 @section Keyed Hash Functions