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
Nettle
nettle
Commits
7153ad93
Commit
7153ad93
authored
Apr 26, 2014
by
Niels Möller
Browse files
Document EAX.
parent
0cc6681d
Changes
2
Hide whitespace changes
Inline
Side-by-side
ChangeLog
View file @
7153ad93
...
...
@@ -3,6 +3,7 @@
* nettle.texinfo (GCM): Document GCM_DIGEST_SIZE.
(UMAC): Document new UMAC constants.
(Keyed hash functions): Make HMAC and UMAC their own info nodes.
(EAX): Document EAX.
* umac.h (UMAC_MIN_NONCE_SIZE, UMAC_MAX_NONCE_SIZE): New
constants.
...
...
nettle.texinfo
View file @
7153ad93
...
...
@@ -1827,6 +1827,7 @@ signature to authenticate the message.
@menu
* CBC::
* CTR::
* EAX::
* GCM::
* CCM::
@end menu
...
...
@@ -1925,7 +1926,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,
GCM
, CBC, Cipher modes
@node CTR,
EAX
, CBC, Cipher modes
@comment node-name, next, previous, up
@subsection Counter mode
...
...
@@ -2001,7 +2002,190 @@ last three arguments define the source and destination area for the
operation.
@end deffn
@node GCM, CCM, CTR, Cipher modes
@node EAX, GCM, CTR, Cipher modes
@comment node-name, next, previous, up
@subsection EAX
The @acronym
{
EAX
}
mode combines @acronym
{
CTR
}
mode encryption,
@xref
{
CTR
}
, with a message authentication based on @acronym
{
CBC
}
,
@xref
{
CBC
}
. It is defined on top of a block cipher, and only the
encryption function of this cipher is used. The implementation in Nettle
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,
@xref
{
CCM
}
, which uses the same primitives but has some undesirable and
inelegant properties.
The @acronym
{
EAX
}
mode provides both encryption and authentication. For
@acronym
{
EAX
}
encryption, the inputs are:
@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
interface, some convenience macros, and specific functions for
@acronym
{
EAX
}
using @acronym
{
AES
}
128 as the underlying cipher. These
interfaces are defined in @file
{
<nettle/eax.h>
}
@subsubsection General @acronym
{
EAX
}
interface
@deftp
{
Context struct
}
{
struct eax
_
key
}
@acronym
{
EAX
}
state which depends only on the key, but not on the nonce
or the message.
@end deftp
@deftp
{
Context struct
}
{
struct eax
_
ctx
}
Holds state corresponding to a particular message.
@end deftp
@defvr Constant EAX
_
BLOCK
_
SIZE
@acronym
{
EAX
}
's block size, 16.
@end defvr
@defvr Constant EAX
_
DIGEST
_
SIZE
Size of the @acronym
{
EAX
}
digest, also 16.
@end defvr
@deftypefun void eax
_
set
_
key (struct eax
_
key *@var
{
key
}
, const void *@var
{
cipher
}
, nettle
_
cipher
_
func *@var
{
f
}
)
Initializes @var
{
key
}
. @var
{
cipher
}
gives a context struct for the
underlying cipher, which must have been previously initialized for
encryption, and @var
{
f
}
is the encryption function.
@end deftypefun
@deftypefun void eax
_
set
_
nonce (struct eax
_
ctx *@var
{
eax
}
, const struct eax
_
key *@var
{
key
}
, const void *@var
{
cipher
}
, nettle
_
cipher
_
func *@var
{
f
}
, size
_
t @var
{
nonce
_
length
}
, const uint8
_
t *@var
{
nonce
}
)
Initializes @var
{
ctx
}
for processing a new message, using the given
nonce.
@end deftypefun
@deftypefun void eax
_
update (struct eax
_
ctx *@var
{
eax
}
, const struct eax
_
key *@var
{
key
}
, const void *@var
{
cipher
}
, nettle
_
cipher
_
func *@var
{
f
}
, size
_
t @var
{
data
_
length
}
, const uint8
_
t *@var
{
data
}
)
Process associated data for authentication. All but the last call for
each message @emph
{
must
}
use a length that is a multiple of the block
size. Unlike many other AEAD constructions, for @acronym
{
EAX
}
it's not
necessary to complete the processing of all associated data before
encrypting or decrypting the message data.
@end deftypefun
@deftypefun void eax
_
encrypt (struct eax
_
ctx *@var
{
eax
}
, const struct eax
_
key *@var
{
key
}
, const void *@var
{
cipher
}
, nettle
_
cipher
_
func *@var
{
f
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void eax
_
decrypt (struct eax
_
ctx *@var
{
eax
}
, const struct eax
_
key *@var
{
key
}
, const void *@var
{
cipher
}
, nettle
_
cipher
_
func *@var
{
f
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
Encrypts or decrypts the data of a message. @var
{
cipher
}
is the context
struct for the underlying cipher and @var
{
f
}
is the encryption function.
All but the last call for each message @emph
{
must
}
use a length that is
a multiple of the block size.
@end deftypefun
@deftypefun void eax
_
digest (struct eax
_
ctx *@var
{
eax
}
, const struct eax
_
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. If @var
{
length
}
is
smaller than @code
{
EAX
_
DIGEST
_
SIZE
}
, only the first @var
{
length
}
octets
of the digest are written.
@end deftypefun
@subsubsection @acronym
{
EAX
}
helper macros
The following macros are defined.
@deffn Macro EAX
_
CTX (@var
{
context
_
type
}
)
This defines an all-in-one context struct, including the context of the
underlying cipher and all @acronym
{
EAX
}
state. It expands
to
@example
@
{
struct eax
_
key key;
struct eax
_
ctx eax;
context
_
type cipher;
@
}
@end example
@end deffn
For all these macros, @var
{
ctx
}
, is a context struct as defined by
@code
{
EAX
_
CTX
}
, and @var
{
encrypt
}
is the encryption function of the
underlying cipher.
@deffn Macro EAX
_
SET
_
KEY (@var
{
ctx
}
, @var
{
set
_
key
}
, @var
{
encrypt
}
, @var
{
key
}
)
@var
{
set
_
key
}
is the function for setting the encryption key for the
underlying cipher, and @var
{
key
}
is the key.
@end deffn
@deffn Macro EAX
_
SET
_
NONCE (@var
{
ctx
}
, @var
{
encrypt
}
, @var
{
length
}
, @var
{
nonce
}
)
Sets the nonce to be used for the message.
@end deffn
@deffn Macro EAX
_
UPDATE (@var
{
ctx
}
, @var
{
encrypt
}
, @var
{
length
}
, @var
{
data
}
)
Process associated data for authentication.
@end deffn
@deffn Macro EAX
_
ENCRYPT (@var
{
ctx
}
, @var
{
encrypt
}
, @var
{
length
}
, @var
{
dst
}
, @var
{
src
}
)
@deffnx Macro EAX
_
DECRYPT (@var
{
ctx
}
, @var
{
encrypt
}
, @var
{
length
}
, @var
{
dst
}
, @var
{
src
}
)
Process message data for encryption or decryption.
@end deffn
@deffn Macro EAX
_
DIGEST (@var
{
ctx
}
, @var
{
encrypt
}
, @var
{
length
}
, @var
{
digest
}
)
Extract te authentication tag for the message.
@end deffn
@subsubsection @acronym
{
EAX
}
-@acronym
{
AES
}
128 interface
The following functions implement @acronym
{
EAX
}
using @acronym
{
AES
}
-128
as the underlying cipher.
@deftp
{
Context struct
}
{
struct eax
_
aes128
_
ctx
}
The context struct, defined using @code
{
EAX
_
CTX
}
.
@end deftp
@deftypefun void eax
_
aes128
_
set
_
key (struct eax
_
aes128
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
Initializes @var
{
ctx
}
using the given key.
@end deftypefun
@deftypefun void eax
_
aes128
_
set
_
nonce (struct eax
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
iv
}
)
Initializes the per-message state, using the given nonce.
@end deftypefun
@deftypefun void eax
_
aes128
_
update (struct eax
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
Process associated data for authentication. All but the last call for
each message @emph
{
must
}
use a length that is a multiple of the block
size.
@end deftypefun
@deftypefun void eax
_
aes128
_
encrypt (struct eax
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void eax
_
aes128
_
decrypt (struct eax
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
Encrypts or decrypts the data of a message. All but the last call for
each message @emph
{
must
}
use a length that is a multiple of the block
size.
@end deftypefun
@deftypefun void eax
_
aes128
_
digest (struct eax
_
aes128
_
ctx *@var
{
ctx
}
, 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. If @var
{
length
}
is
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
@comment node-name, next, previous, up
@subsection Galois counter mode
...
...
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
