diff --git a/ChangeLog b/ChangeLog index aa7ba67a2b31a8a430251812e914bcf07f4f98ab..278fe27d5fb45b80de481233bf3aaf8a3c7076aa 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,7 @@ 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. diff --git a/nettle.texinfo b/nettle.texinfo index b182cd3ab0137429c295b12b38a3e3d0ee854923..44ee3124d69bd7f77f1895fc30140182fca3d93c 100644 --- a/nettle.texinfo +++ b/nettle.texinfo @@ -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