nettle: HMAC
1
1 6.5.1 HMAC
1 ----------
1
1 One can build keyed hash functions from ordinary hash functions. Older
1 constructions simply concatenate secret key and message and hashes that,
1 but such constructions have weaknesses. A better construction is HMAC,
1 described in ‘RFC 2104’.
1
1 For an underlying hash function ‘H’, with digest size ‘l’ and
1 internal block size ‘b’, HMAC-H is constructed as follows: From a given
1 key ‘k’, two distinct subkeys ‘k_i’ and ‘k_o’ are constructed, both of
1 length ‘b’. The HMAC-H of a message ‘m’ is then computed as ‘H(k_o |
1 H(k_i | m))’, where ‘|’ denotes string concatenation.
1
1 HMAC keys can be of any length, but it is recommended to use keys of
1 length ‘l’, the digest size of the underlying hash function ‘H’. Keys
1 that are longer than ‘b’ are shortened to length ‘l’ by hashing with
1 ‘H’, so arbitrarily long keys aren’t very useful.
1
1 Nettle’s HMAC functions are defined in ‘<nettle/hmac.h>’. There are
1 abstract functions that use a pointer to a ‘struct nettle_hash’ to
1 represent the underlying hash function and ‘void *’ pointers that point
1 to three different context structs for that hash function. There are
1 also concrete functions for HMAC-MD5, HMAC-RIPEMD160 HMAC-SHA1,
1 HMAC-SHA256, and HMAC-SHA512. First, the abstract functions:
1
1 -- Function: void hmac_set_key (void *OUTER, void *INNER, void *STATE,
1 const struct nettle_hash *H, size_t LENGTH, const uint8_t
1 *KEY)
1 Initializes the three context structs from the key. The OUTER and
1 INNER contexts corresponds to the subkeys ‘k_o’ and ‘k_i’. STATE
1 is used for hashing the message, and is initialized as a copy of
1 the INNER context.
1
1 -- Function: void hmac_update (void *STATE, const struct nettle_hash
1 *H, size_t LENGTH, const uint8_t *DATA)
1 This function is called zero or more times to process the message.
1 Actually, ‘hmac_update(state, H, length, data)’ is equivalent to
1 ‘H->update(state, length, data)’, so if you wish you can use the
1 ordinary update function of the underlying hash function instead.
1
1 -- Function: void hmac_digest (const void *OUTER, const void *INNER,
1 void *STATE, const struct nettle_hash *H, size_t LENGTH,
1 uint8_t *DIGEST)
1 Extracts the MAC of the message, writing it to DIGEST. OUTER and
1 INNER are not modified. LENGTH is usually equal to
1 ‘H->digest_size’, but if you provide a smaller value, only the
1 first LENGTH octets of the MAC are written.
1
1 This function also resets the STATE context so that you can start
1 over processing a new message (with the same key).
1
1 Like for CBC, there are some macros to help use these functions
1 correctly.
1
1 -- Macro: HMAC_CTX (TYPE)
1 Expands to
1 {
1 type outer;
1 type inner;
1 type state;
1 }
1
1 It can be used to define a HMAC context struct, either directly,
1
1 struct HMAC_CTX(struct md5_ctx) ctx;
1
1 or to give it a struct tag,
1
1 struct hmac_md5_ctx HMAC_CTX (struct md5_ctx);
1
1 -- Macro: HMAC_SET_KEY (CTX, H, LENGTH, KEY)
1 CTX is a pointer to a context struct as defined by ‘HMAC_CTX’, H is
1 a pointer to a ‘const struct nettle_hash’ describing the underlying
1 hash function (so it must match the type of the components of CTX).
1 The last two arguments specify the secret key.
1
1 -- Macro: HMAC_DIGEST (CTX, H, LENGTH, DIGEST)
1 CTX is a pointer to a context struct as defined by ‘HMAC_CTX’, H is
1 a pointer to a ‘const struct nettle_hash’ describing the underlying
1 hash function. The last two arguments specify where the digest is
1 written.
1
1 Note that there is no ‘HMAC_UPDATE’ macro; simply call ‘hmac_update’
1 function directly, or the update function of the underlying hash
1 function.
1
1 6.5.2 Concrete HMAC functions
1 -----------------------------
1
1 Now we come to the specialized HMAC functions, which are easier to use
1 than the general HMAC functions.
1
1 6.5.2.1 HMAC-MD5
1 ................
1
1 -- Context struct: struct hmac_md5_ctx
1
1 -- Function: void hmac_md5_set_key (struct hmac_md5_ctx *CTX, size_t
1 KEY_LENGTH, const uint8_t *KEY)
1 Initializes the context with the key.
1
1 -- Function: void hmac_md5_update (struct hmac_md5_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 Process some more data.
1
1 -- Function: void hmac_md5_digest (struct hmac_md5_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
1 ‘MD5_DIGEST_SIZE’, in which case only the first LENGTH octets of
1 the MAC are written.
1
1 This function also resets the context for processing new messages,
1 with the same key.
1
1 6.5.2.2 HMAC-RIPEMD160
1 ......................
1
1 -- Context struct: struct hmac_ripemd160_ctx
1
1 -- Function: void hmac_ripemd160_set_key (struct hmac_ripemd160_ctx
1 *CTX, size_t KEY_LENGTH, const uint8_t *KEY)
1 Initializes the context with the key.
1
1 -- Function: void hmac_ripemd160_update (struct hmac_ripemd160_ctx
1 *CTX, size_t LENGTH, const uint8_t *DATA)
1 Process some more data.
1
1 -- Function: void hmac_ripemd160_digest (struct hmac_ripemd160_ctx
1 *CTX, size_t LENGTH, uint8_t *DIGEST)
1 Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
1 ‘RIPEMD160_DIGEST_SIZE’, in which case only the first LENGTH octets
1 of the MAC are written.
1
1 This function also resets the context for processing new messages,
1 with the same key.
1
1 6.5.2.3 HMAC-SHA1
1 .................
1
1 -- Context struct: struct hmac_sha1_ctx
1
1 -- Function: void hmac_sha1_set_key (struct hmac_sha1_ctx *CTX, size_t
1 KEY_LENGTH, const uint8_t *KEY)
1 Initializes the context with the key.
1
1 -- Function: void hmac_sha1_update (struct hmac_sha1_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 Process some more data.
1
1 -- Function: void hmac_sha1_digest (struct hmac_sha1_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
1 ‘SHA1_DIGEST_SIZE’, in which case only the first LENGTH octets of
1 the MAC are written.
1
1 This function also resets the context for processing new messages,
1 with the same key.
1
1 6.5.2.4 HMAC-SHA256
1 ...................
1
1 -- Context struct: struct hmac_sha256_ctx
1
1 -- Function: void hmac_sha256_set_key (struct hmac_sha256_ctx *CTX,
1 size_t KEY_LENGTH, const uint8_t *KEY)
1 Initializes the context with the key.
1
1 -- Function: void hmac_sha256_update (struct hmac_sha256_ctx *CTX,
1 size_t LENGTH, const uint8_t *DATA)
1 Process some more data.
1
1 -- Function: void hmac_sha256_digest (struct hmac_sha256_ctx *CTX,
1 size_t LENGTH, uint8_t *DIGEST)
1 Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
1 ‘SHA256_DIGEST_SIZE’, in which case only the first LENGTH octets of
1 the MAC are written.
1
1 This function also resets the context for processing new messages,
1 with the same key.
1
1 6.5.2.5 HMAC-SHA512
1 ...................
1
1 -- Context struct: struct hmac_sha512_ctx
1
1 -- Function: void hmac_sha512_set_key (struct hmac_sha512_ctx *CTX,
1 size_t KEY_LENGTH, const uint8_t *KEY)
1 Initializes the context with the key.
1
1 -- Function: void hmac_sha512_update (struct hmac_sha512_ctx *CTX,
1 size_t LENGTH, const uint8_t *DATA)
1 Process some more data.
1
1 -- Function: void hmac_sha512_digest (struct hmac_sha512_ctx *CTX,
1 size_t LENGTH, uint8_t *DIGEST)
1 Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
1 ‘SHA512_DIGEST_SIZE’, in which case only the first LENGTH octets of
1 the MAC are written.
1
1 This function also resets the context for processing new messages,
1 with the same key.
1