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
b5ab7fc1
Commit
b5ab7fc1
authored
Apr 18, 2013
by
Niels Möller
Browse files
UMAC documentation.
parent
f6309ddc
Changes
2
Hide whitespace changes
Inline
Side-by-side
ChangeLog
View file @
b5ab7fc1
2013-04-18 Niels Möller <nisse@lysator.liu.se>
* nettle.texinfo (Keyed hash functions): Document UMAC.
* umac.h (UMAC32_DIGEST_SIZE, UMAC64_DIGEST_SIZE)
(UMAC96_DIGEST_SIZE, UMAC128_DIGEST_SIZE): New constants.
(UMAC_DATA_SIZE): New name, for consistency with hash functions.
...
...
nettle.texinfo
View file @
b5ab7fc1
...
...
@@ -2358,6 +2358,119 @@ This function also resets the context for processing new messages, with
the same key.
@end deftypefun
@subsection @acronym
{
UMAC
}
@cindex UMAC
@acronym
{
UMAC
}
is a message authentication code based on universal
hashing, and designed for high performance on modern processors (in
contrast to GCM, @xref
{
GCM
}
, which is designed primarily for hardware
performance). On processors with good integer multiplication
performance, it can be 10 times faster than SHA256 and SHA512.
@acronym
{
UMAC
}
is specified in @cite
{
RFC 4418
}
.
The secret key is always 128 bits (16 octets). The key is used as an
encryption key for the @acronym
{
AES
}
block cipher. This cipher is used
in counter mode to generate various internal subkeys needed in
@acronym
{
UMAC
}
. Messages are of arbitrary size, and for each message,
@acronym
{
UMAC
}
also needs a unique nonce. Nonce values must not be
reused for two messages with the same key, but they need not be kept
secret.
The nonce must be at least one octet, and at most 16; nonces shorter
than 16 octets are zero-padded. Nettle's implementation of
@acronym
{
UMAC
}
increments the nonce for automatically each message, so
explicitly setting the nonce for each message is optional. This
auto-increment uses network byte order and it takes the length of the
nonce into acount. E.g., if the initial nonce is ``abc'' (3 octets),
this value is zero-padded to 16 octets for the first message. For the
next message, the nonce is incremented to ``abd'', and this incremented
value is zero-padded to 16 octets.
@acronym
{
UMAC
}
is defined in four variants, for different output sizes:
32 bits (4 octest), 64 bits (8 octets), 96 bits (12 octets) and 128 bits
(16 octets), corresponding to different tradeoffs between speed and
security. Using a shorter output size sometimes (but not always!) gives
the same result as using a longer output size and truncating the result.
So it is important to use the right variant. For consistency with other
hash and @acronym
{
MAC
}
functions, Nettle's @code
{_
digest
}
functions for
@acronym
{
UMAC
}
accept a length parameter so that the output can be
truncated to any desired size, but it is recommended to stick to the
specified output size and select the @acronym
{
umac
}
variant
corresponding to the desired size.
The internal block size of @acronym
{
UMAC
}
is 1024 octets, and it also
generates more than 1024 bytes of subkeys. This makes the size of the
context struct a bit larger than other hash functions and @acronym
{
MAC
}
algorithms in Nettle.
Nettle defines @acronym
{
UMAC
}
in @file
{
<nettle/umac.h>
}
.
@deftp
{
Context struct
}
{
struct umac32
_
ctx
}
@deftpx
{
Context struct
}
{
struct umac64
_
ctx
}
@deftpx
{
Context struct
}
{
struct umac96
_
ctx
}
@deftpx
{
Context struct
}
{
struct umac128
_
ctx
}
Each @acronym
{
UMAC
}
variant uses its own context struct.
@end deftp
@defvr Constant UMAC
_
KEY
_
SIZE
The UMAC key size, 16.
@end defvr
@defvr Constant UMAC32
_
DIGEST
_
SIZE
The size of an UMAC32 digest, 4.
@end defvr
@defvr Constant UMAC64
_
DIGEST
_
SIZE
The size of an UMAC64 digest, 8.
@end defvr
@defvr Constant UMAC96
_
DIGEST
_
SIZE
The size of an UMAC96 digest, 12.
@end defvr
@defvr Constant UMAC128
_
DIGEST
_
SIZE
The size of an UMAC128 digest, 16.
@end defvr
@defvr Constant UMAC128
_
DATA
_
SIZE
The internal block size of UMAC.
@end defvr
@deftypefun void umac32
_
set
_
key (struct umac32
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
@deftypefunx void umac64
_
set
_
key (struct umac64
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
@deftypefunx void umac96
_
set
_
key (struct umac96
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
@deftypefunx void umac128
_
set
_
key (struct umac128
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
These functions initialize the @acronym
{
UMAC
}
context struct. They also
initialize the nonce to zero (with length 16, for auto-increment).
@end deftypefun
@deftypefun void umac32
_
set
_
nonce (struct umac32
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
nonce
}
)
@deftypefunx void umac64
_
set
_
nonce (struct umac64
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
nonce
}
)
@deftypefunx void umac96
_
set
_
nonce (struct umac96
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
nonce
}
)
@deftypefunx void umac128
_
set
_
nonce (struct umac128
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
nonce
}
)
Sets the nonce to be used for the next message. In general, nonces
should be set before processing of the message. This is not strictly
required for @acronym
{
UMAC
}
(the nonce only affects the final processing
generating the digest), but it is nevertheless recommended that this
function is called @emph
{
before
}
the first @code
{_
update
}
call for the
message.
@end deftypefun
@deftypefun void umac32
_
update (struct umac32
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
@deftypefunx void umac64
_
update (struct umac64
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
@deftypefunx void umac96
_
update (struct umac96
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
@deftypefunx void umac128
_
update (struct umac128
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
These functions are called zero or more times to process the message.
@end deftypefun
@deftypefun void umac32
_
digest (struct umac32
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
@deftypefunx void umac64
_
digest (struct umac64
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
@deftypefunx void umac96
_
digest (struct umac96
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
@deftypefunx void umac128
_
digest (struct umac128
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
Extracts the @acronym
{
MAC
}
of the message, writing it to @var
{
digest
}
.
@var
{
length
}
is usually equal to the specified output size, but if you
provide a smaller value, only the first @var
{
length
}
octets of the
@acronym
{
MAC
}
are written. These functions reset the context for
processing of a new message with the same key. The nonce is incremented
as described above, the new value is used unless you call the
@code
{_
set
_
nonce
}
function explicitly for each message.
@end deftypefun
@node Key derivation functions, Public-key algorithms, Keyed hash functions, Reference
@comment node-name, next, previous, up
@section Key derivation Functions
...
...
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
