Skip to content
GitLab
Menu
Projects
Groups
Snippets
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
Wim Lewis
nettle
Commits
c665ecd3
Commit
c665ecd3
authored
Apr 27, 2014
by
Niels Möller
Browse files
Started on AEAD documentation.
parent
a7861812
Changes
2
Hide whitespace changes
Inline
Side-by-side
ChangeLog
View file @
c665ecd3
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>
* nettle.texinfo: Update for introduction of nettle_cipher_func.
...
...
nettle.texinfo
View file @
c665ecd3
...
...
@@ -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
@xref
{
Cipher functions
}
, splitting the message into blocks and
processing them independently with the block cipher (Electronic Code
Book mode, @acronym
{
ECB
}
) leaks information. Besides @acronym
{
ECB
}
,
Nettle provides three other modes of operation: Cipher Block Chaining
(@acronym
{
CBC
}
), Counter mode (@acronym
{
CTR
}
), and Galois/Counter mode
(@acronym
{
GCM
}
). @acronym
{
CBC
}
is widely used, but there are a few
subtle issues of information leakage, see, e.g.,
Book mode, @acronym
{
ECB
}
), leaks information.
Besides @acronym
{
ECB
}
, Nettle provides a two other modes of operation:
Cipher Block Chaining (@acronym
{
CBC
}
), Counter mode (@acronym
{
CTR
}
), and
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
}
vulnerability
}
. @acronym
{
CTR
}
and @acronym
{
GCM
}
were standardized more recently, and are believed to be more secure.
@acronym
{
GCM
}
includes message authentication; for the other modes, one
should always use a @acronym
{
MAC
}
(@pxref
{
Keyed hash functions
}
) or
signature to authenticate the message.
vulnerability
}
. Today, @acronym
{
CTR
}
is usually preferred over @acronym
{
CBC
}
.
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 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
* CBC::
...
...
@@ -2202,6 +2233,10 @@ recommended by NIST in 2007,
NIST Special Publication 800-38D
}
. It is constructed on top of a block
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
are:
...
...
@@ -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
}
)
Extracts the message digest (also known ``authentication tag''). This is
the final operation when processing a message.
@var
{
length
}
is usually
equal to
@code
{
GCM
_
DIGEST
_
SIZE
}
, but if you provide a smaller
value,
only the first @var
{
length
}
octets of the digest are written.
the final operation when processing a message.
It's strongly recommended
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
To encrypt a message using @acronym
{
GCM
}
, first initialize a context for
...
...
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment