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