Commit c665ecd3 authored by Niels Möller's avatar Niels Möller
Browse files

Started on AEAD documentation.

parent a7861812
2014-04-27 Niels Möller <nisse@lysator.liu.se>
* nettle.texinfo (Cipher modes): Subsection on AEAD constructions.
2014-04-26 Niels Möller <nisse@lysator.liu.se> 2014-04-26 Niels Möller <nisse@lysator.liu.se>
* nettle.texinfo: Update for introduction of nettle_cipher_func. * nettle.texinfo: Update for introduction of nettle_cipher_func.
......
...@@ -1811,17 +1811,48 @@ Cipher modes of operation specifies the procedure to use when encrypting ...@@ -1811,17 +1811,48 @@ Cipher modes of operation specifies the procedure to use when encrypting
a message that is larger than the cipher's block size. As explained in a message that is larger than the cipher's block size. As explained in
@xref{Cipher functions}, splitting the message into blocks and @xref{Cipher functions}, splitting the message into blocks and
processing them independently with the block cipher (Electronic Code processing them independently with the block cipher (Electronic Code
Book mode, @acronym{ECB}) leaks information. Besides @acronym{ECB}, Book mode, @acronym{ECB}), leaks information.
Nettle provides three other modes of operation: Cipher Block Chaining
(@acronym{CBC}), Counter mode (@acronym{CTR}), and Galois/Counter mode Besides @acronym{ECB}, Nettle provides a two other modes of operation:
(@acronym{GCM}). @acronym{CBC} is widely used, but there are a few Cipher Block Chaining (@acronym{CBC}), Counter mode (@acronym{CTR}), and
subtle issues of information leakage, see, e.g., a couple of AEAD modes (see below). @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} @uref{http://www.kb.cert.org/vuls/id/958563, @acronym{SSH} @acronym{CBC}
vulnerability}. @acronym{CTR} and @acronym{GCM} vulnerability}. Today, @acronym{CTR} is usually preferred over @acronym{CBC}.
were standardized more recently, and are believed to be more secure.
@acronym{GCM} includes message authentication; for the other modes, one Modes like @acronym{CBC} and @acronym{CTR} provide @emph{no} message
should always use a @acronym{MAC} (@pxref{Keyed hash functions}) or authentication, and should always be used together with a @acronym{MAC}
signature to authenticate the message. (@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 ptotential is not realized for
the constructions currently supported by Nettle.
The supported @acronym{AEAD} constructions are Galois/Counter mode
(@acronym{GCM}), @acronym{EAX}, and Counter with
@acronym{CBC}-@acronym{MAC} (@acronym{CCM}). Of these, I recommend
@acronym{EAX}. 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 simpler.
@menu @menu
* CBC:: * CBC::
...@@ -2202,6 +2233,10 @@ recommended by NIST in 2007, ...@@ -2202,6 +2233,10 @@ recommended by NIST in 2007,
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.
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}.
In particular, don't use @acronym{GCM} with short authentication tags.
@acronym{GCM} is applied to messages of arbitrary length. The inputs @acronym{GCM} is applied to messages of arbitrary length. The inputs
are: are:
...@@ -2275,9 +2310,9 @@ a multiple of the block size. ...@@ -2275,9 +2310,9 @@ a multiple of the block size.
@deftypefun void gcm_digest (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{digest}) @deftypefun void gcm_digest (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{digest})
Extracts the message digest (also known ``authentication tag''). This is Extracts the message digest (also known ``authentication tag''). This is
the final operation when processing a message. @var{length} is usually the final operation when processing a message. It's strongly recommended
equal to @code{GCM_DIGEST_SIZE}, but if you provide a smaller value, that @var{length} is @code{GCM_DIGEST_SIZE}, but if you provide a smaller
only the first @var{length} octets of the digest are written. value, only the first @var{length} octets of the digest are written.
@end deftypefun @end deftypefun
To encrypt a message using @acronym{GCM}, first initialize a context for To encrypt a message using @acronym{GCM}, first initialize a context for
......
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