The crypto_auth_hmacsha256() function authenticates a message in whose length is inlen using the secret key k whose length is crypto_auth_hmacsha256_KEYBYTES, and puts the authenticator into out (crypto_auth_hmacsha256_BYTES bytes).
The crypto_auth_hmacsha256_verify() function verifies in constant time that h is a correct authenticator for the message in whose length is inlen under a secret key k (crypto_auth_hmacsha256_KEYBYTES bytes).
It returns -1 if the verification fails, and 0 on success.
A multi-part (streaming) API can be used instead of crypto_auth_hmacsha256():
HMAC-SHA-512-256 is implemented as HMAC-SHA-512 with the output truncated to 256 bits. This is slightly faster than HMAC-SHA-256. Note that this construction is not the same as HMAC-SHA-512/256, which is HMAC using the SHA-512/256 function.
The state must be initialized with crypto_auth_hmacsha*_init() before updating or finalizing it. After crypto_auth_hmacsha*_final() returns, the state should not be used any more, unless it is reinitialized using crypto_auth_hmacsha*_init().
Arbitrary key lengths are supported using the multi-part interface.
crypto_auth_hmacsha256_*() can be used to create AWS HMAC-SHA256 request signatures.
Only use these functions for interoperability with 3rd party services. For everything else, you should probably use crypto_auth()/crypto_auth_verify() or crypto_generichash_*() instead.