nettle: UMAC
1
1 6.5.3 UMAC
1 ----------
1
1 UMAC is a message authentication code based on universal hashing, and
1 designed for high performance on modern processors (in contrast to GCM,
1 ⇒GCM, which is designed primarily for hardware performance). On
1 processors with good integer multiplication performance, it can be 10
1 times faster than SHA256 and SHA512. UMAC is specified in ‘RFC 4418’.
1
1 The secret key is always 128 bits (16 octets). The key is used as an
1 encryption key for the AES block cipher. This cipher is used in counter
1 mode to generate various internal subkeys needed in UMAC. Messages are
1 of arbitrary size, and for each message, UMAC also needs a unique nonce.
1 Nonce values must not be reused for two messages with the same key, but
1 they need not be kept secret.
1
1 The nonce must be at least one octet, and at most 16; nonces shorter
1 than 16 octets are zero-padded. Nettle’s implementation of UMAC
1 increments the nonce automatically for each message, so explicitly
1 setting the nonce for each message is optional. This auto-increment
1 uses network byte order and it takes the length of the nonce into
1 account. E.g., if the initial nonce is “abc” (3 octets), this value is
1 zero-padded to 16 octets for the first message. For the next message,
1 the nonce is incremented to “abd”, and this incremented value is
1 zero-padded to 16 octets.
1
1 UMAC is defined in four variants, for different output sizes: 32 bits
1 (4 octets), 64 bits (8 octets), 96 bits (12 octets) and 128 bits (16
1 octets), corresponding to different trade-offs between speed and
1 security. Using a shorter output size sometimes (but not always!)
1 gives the same result as using a longer output size and truncating the
1 result. So it is important to use the right variant. For consistency
1 with other hash and MAC functions, Nettle’s ‘_digest’ functions for UMAC
1 accept a length parameter so that the output can be truncated to any
1 desired size, but it is recommended to stick to the specified output
1 size and select the umac variant corresponding to the desired size.
1
1 The internal block size of UMAC is 1024 octets, and it also generates
1 more than 1024 bytes of subkeys. This makes the size of the context
1 struct quite a bit larger than other hash functions and MAC algorithms
1 in Nettle.
1
1 Nettle defines UMAC in ‘<nettle/umac.h>’.
1
1 -- Context struct: struct umac32_ctx
1 -- Context struct: struct umac64_ctx
1 -- Context struct: struct umac96_ctx
1 -- Context struct: struct umac128_ctx
1 Each UMAC variant uses its own context struct.
1
1 -- Constant: UMAC_KEY_SIZE
1 The UMAC key size, 16.
1 -- Constant: UMAC_MIN_NONCE_SIZE
1 -- Constant: UMAC_MAX_NONCE_SIZE
1 The the minimum and maximum sizes for an UMAC nonce, 1 and 16,
1 respectively.
1 -- Constant: UMAC32_DIGEST_SIZE
1 The size of an UMAC32 digest, 4.
1 -- Constant: UMAC64_DIGEST_SIZE
1 The size of an UMAC64 digest, 8.
1 -- Constant: UMAC96_DIGEST_SIZE
1 The size of an UMAC96 digest, 12.
1 -- Constant: UMAC128_DIGEST_SIZE
1 The size of an UMAC128 digest, 16.
1 -- Constant: UMAC_BLOCK_SIZE
1 The internal block size of UMAC.
1
1 -- Function: void umac32_set_key (struct umac32_ctx *CTX, const uint8_t
1 *KEY)
1 -- Function: void umac64_set_key (struct umac64_ctx *CTX, const uint8_t
1 *KEY)
1 -- Function: void umac96_set_key (struct umac96_ctx *CTX, const uint8_t
1 *KEY)
1 -- Function: void umac128_set_key (struct umac128_ctx *CTX, const
1 uint8_t *KEY)
1 These functions initialize the UMAC context struct. They also
1 initialize the nonce to zero (with length 16, for auto-increment).
1
1 -- Function: void umac32_set_nonce (struct umac32_ctx *CTX, size_t
1 LENGTH, const uint8_t *NONCE)
1 -- Function: void umac64_set_nonce (struct umac64_ctx *CTX, size_t
1 LENGTH, const uint8_t *NONCE)
1 -- Function: void umac96_set_nonce (struct umac96_ctx *CTX, size_t
1 LENGTH, const uint8_t *NONCE)
1 -- Function: void umac128_set_nonce (struct umac128_ctx *CTX, size_t
1 LENGTH, const uint8_t *NONCE)
1 Sets the nonce to be used for the next message. In general, nonces
1 should be set before processing of the message. This is not
1 strictly required for UMAC (the nonce only affects the final
1 processing generating the digest), but it is nevertheless
1 recommended that this function is called _before_ the first
1 ‘_update’ call for the message.
1
1 -- Function: void umac32_update (struct umac32_ctx *CTX, size_t LENGTH,
1 const uint8_t *DATA)
1 -- Function: void umac64_update (struct umac64_ctx *CTX, size_t LENGTH,
1 const uint8_t *DATA)
1 -- Function: void umac96_update (struct umac96_ctx *CTX, size_t LENGTH,
1 const uint8_t *DATA)
1 -- Function: void umac128_update (struct umac128_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 These functions are called zero or more times to process the
1 message.
1
1 -- Function: void umac32_digest (struct umac32_ctx *CTX, size_t LENGTH,
1 uint8_t *DIGEST)
1 -- Function: void umac64_digest (struct umac64_ctx *CTX, size_t LENGTH,
1 uint8_t *DIGEST)
1 -- Function: void umac96_digest (struct umac96_ctx *CTX, size_t LENGTH,
1 uint8_t *DIGEST)
1 -- Function: void umac128_digest (struct umac128_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 Extracts the MAC of the message, writing it to DIGEST. LENGTH is
1 usually equal to the specified output size, but if you provide a
1 smaller value, only the first LENGTH octets of the MAC are written.
1 These functions reset the context for processing of a new message
1 with the same key. The nonce is incremented as described above,
1 the new value is used unless you call the ‘_set_nonce’ function
1 explicitly for each message.
1