Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
What's new
7
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Open sidebar
Nettle
nettle
Commits
7153ad93
Commit
7153ad93
authored
Apr 26, 2014
by
Niels Möller
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Document EAX.
parent
0cc6681d
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
187 additions
and
2 deletions
+187
-2
ChangeLog
ChangeLog
+1
-0
nettle.texinfo
nettle.texinfo
+186
-2
No files found.
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
Markdown
is supported
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
