Commit 47b66061 authored by Niels Möller's avatar Niels Möller

Move description of general structure to the AEAD subsection.

parent c665ecd3
...@@ -1842,17 +1842,59 @@ messages. This family of building blocks are therefore called ...@@ -1842,17 +1842,59 @@ messages. This family of building blocks are therefore called
The aim is to provide building blocks that it is easier for designers of The aim is to provide building blocks that it is easier for designers of
protocols and applications to use correctly. There is also some protocols and applications to use correctly. There is also some
potential for improved performance, if encryption and authentication can potential for improved performance, if encryption and authentication can
be done in a single step, although that ptotential is not realized for be done in a single step, although that potential is not realized for
the constructions currently supported by Nettle. 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 The supported @acronym{AEAD} constructions are Galois/Counter mode
(@acronym{GCM}), @acronym{EAX}, and Counter with (@acronym{GCM}), @acronym{EAX}, and Counter with
@acronym{CBC}-@acronym{MAC} (@acronym{CCM}). Of these, I recommend @acronym{CBC}-@acronym{MAC} (@acronym{CCM}). There are some weaknesses
@acronym{EAX}. There are some weaknesses in @acronym{GCM} in @acronym{GCM} authentication, see
authentication, see
@uref{http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments/CWC-GCM/Ferguson2.pdf}. @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 @acronym{CCM} and @acronym{EAX} use the same building blocks, but the
the @acronym{EAX} design is simpler. @acronym{EAX} design is cleaner and avoids a couple of inconveniences of
@acronym{CCM}. Therefore, @acronym{EAX} seems like a good choice.
@menu @menu
* CBC:: * CBC::
...@@ -2036,48 +2078,20 @@ operation. ...@@ -2036,48 +2078,20 @@ operation.
@comment node-name, next, previous, up @comment node-name, next, previous, up
@subsection EAX @subsection EAX
The @acronym{EAX} mode combines @acronym{CTR} mode encryption, The @acronym{EAX} mode is an @acronym{AEAD} mode whichcombines
@xref{CTR}, with a message authentication based on @acronym{CBC}, @acronym{CTR} mode encryption, @xref{CTR}, with a message authentication
@xref{CBC}. It is defined on top of a block cipher, and only the based on @acronym{CBC}, @xref{CBC}. The implementation in Nettle is
encryption function of this cipher is used. The implementation in Nettle restricted to ciphers with a block size of 128 bits (16 octets).
is restricted to ciphers with a block size of 128 bits (16 octets).
@acronym{EAX} was defined as a reaction to the @acronym{CCM} mode, @acronym{EAX} was defined as a reaction to the @acronym{CCM} mode,
@xref{CCM}, which uses the same primitives but has some undesirable and @xref{CCM}, which uses the same primitives but has some undesirable and
inelegant properties. inelegant properties.
The @acronym{EAX} mode provides both encryption and authentication. For @acronym{EAX} supports arbitrary nonce size; it's even possible to use
@acronym{EAX} encryption, the inputs are: an empty nonce in case only a single message is encrypted for each key.
@itemize
@item
The key, which can be used for many messages.
@item
A nonce, of arbitrary size, 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
A ciphertext, of the same size as the cleartext.
@item
An authentication tag, or digest, of size up to one block of the
underlying cipher.
@end itemize
Usually, the authentication tag should be appended at the end of the
ciphertext, producing an encrypted message which is slightly longer than
the cleartext.
Nettle's support for @acronym{EAX} consists of a low-level general Nettle's support for @acronym{EAX} consists of a low-level general
interface, some convenience macros, and specific functions for interface, some convenience macros, and specific functions for
@acronym{EAX} using @acronym{AES}128 as the underlying cipher. These @acronym{EAX} using @acronym{AES}-128 as the underlying cipher. These
interfaces are defined in @file{<nettle/eax.h>} interfaces are defined in @file{<nettle/eax.h>}
@subsubsection General @acronym{EAX} interface @subsubsection General @acronym{EAX} interface
...@@ -2222,13 +2236,13 @@ of the digest are written. ...@@ -2222,13 +2236,13 @@ of the digest are written.
@cindex Galois Counter Mode @cindex Galois Counter Mode
@cindex GCM @cindex GCM
Galois counter mode is the combination of counter mode with message Galois counter mode is an @acronym{AEAD} constructions combining counter
authentication based on universal hashing. The main objective of the mode with message authentication based on universal hashing. The main
design is to provide high performance for hardware implementations, objective of the design is to provide high performance for hardware
where other popular @acronym{MAC} algorithms (@pxref{Keyed hash implementations, where other popular @acronym{MAC} algorithms
functions} becomes a bottleneck for high-speed hardware implementations. (@pxref{Keyed hash functions} become a bottleneck for high-speed
It was proposed by David A. McGrew and John Viega in 2005, and hardware implementations. It was proposed by David A. McGrew and John
recommended by NIST in 2007, Viega in 2005, and recommended by NIST in 2007,
@uref{http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf, @uref{http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf,
NIST Special Publication 800-38D}. It is constructed on top of a block NIST Special Publication 800-38D}. It is constructed on top of a block
cipher which must have a block size of 128 bits. cipher which must have a block size of 128 bits.
...@@ -2237,27 +2251,10 @@ The authentication in @acronym{GCM} has some known weaknesses, see ...@@ -2237,27 +2251,10 @@ The authentication in @acronym{GCM} has some known weaknesses, see
@uref{http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments/CWC-GCM/Ferguson2.pdf}. @uref{http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments/CWC-GCM/Ferguson2.pdf}.
In particular, don't use @acronym{GCM} with short authentication tags. In particular, don't use @acronym{GCM} with short authentication tags.
@acronym{GCM} is applied to messages of arbitrary length. The inputs Nettle's support for @acronym{GCM} consists of a low-level general
are: interface, some convenience macros, and specific functions for
@acronym{GCM} using @acronym{AES} as the underlying cipher. These
@itemize interfaces are defined in @file{<nettle/gcm.h>}
@item
A key, which can be used for many messages.
@item
An initialization vector (@acronym{IV}) which @emph{must} be unique for
each message.
@item
Additional authenticated data, which is to be included in the message
authentication, but not encrypted. May be empty.
@item
The plaintext. May be empty.
@end itemize
The outputs are a ciphertext, of the same length as the plaintext, and a
message digest of length 128 bits. Nettle's support for @acronym{GCM}
consists of a low-level general interface, some convenience macros, and
specific functions for @acronym{GCM} using @acronym{AES} as the
underlying cipher. These interfaces are defined in @file{<nettle/gcm.h>}
@subsubsection General @acronym{GCM} interface @subsubsection General @acronym{GCM} interface
...@@ -2278,7 +2275,7 @@ Size of the @acronym{GCM} digest, also 16. ...@@ -2278,7 +2275,7 @@ Size of the @acronym{GCM} digest, also 16.
@end defvr @end defvr
@defvr Constant GCM_IV_SIZE @defvr Constant GCM_IV_SIZE
Recommended size of the @acronym{IV}, 12. Other sizes are allowed. Recommended size of the @acronym{IV}, 12. Arbitrary sizes are allowed.
@end defvr @end defvr
@deftypefun void gcm_set_key (struct gcm_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}) @deftypefun void gcm_set_key (struct gcm_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f})
...@@ -2423,9 +2420,10 @@ only the first @var{length} octets of the digest are written. ...@@ -2423,9 +2420,10 @@ only the first @var{length} octets of the digest are written.
@cindex Counter with CBC-MAC Mode @cindex Counter with CBC-MAC Mode
@cindex CCM Mode @cindex CCM Mode
CCM mode is the combination of counter mode with message authentication @acronym{CCM} mode is a combination of counter mode with message
based on cipher block chaining. It is constructed on top of a block authentication based on cipher block chaining, the same building blocks
cipher which must have a block size of 128 bits. @acronym{CCM} mode is as @acronym{EAX}, @pxref{EAX}. It is constructed on top of a block cipher
which must have a block size of 128 bits. @acronym{CCM} mode is
recommended by NIST in recommended by NIST in
@uref{http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf, @uref{http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf,
NIST Special Publication 800-38C}. Nettle's support for CCM consists of NIST Special Publication 800-38C}. Nettle's support for CCM consists of
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment