Secret-key authentication

Example

  1. #define MESSAGE (const unsigned char *) "test"
  2. #define MESSAGE_LEN 4
  4. unsigned char key[crypto_auth_KEYBYTES];
  5. unsigned char mac[crypto_auth_BYTES];
  7. crypto_auth_keygen(key);
  8. crypto_auth(mac, MESSAGE, MESSAGE_LEN, key);
  10. if (crypto_auth_verify(mac, MESSAGE, MESSAGE_LEN, key) != 0) {
  11.     /* message forged! */
  12. }

Purpose

This operation computes an authentication tag for a message and a secret key, and provides a way to verify that a given tag is valid for a given message and a key.

The function computing the tag deterministic: the same (message, key) tuple will always produce the same output.

However, even if the message is public, knowing the key is required in order to be able to compute a valid tag. Therefore, the key should remain confidential. The tag, however, can be public.

A typical use case is:

  • A prepares a message, add an authentication tag, sends it to B
  • A doesn’t store the message
  • Later on, B sends the message and the authentication tag to A
  • A uses the authentication tag to verify that it created this message.

This operation does not encrypt the message. It only computes and verifies an authentication tag.

Usage

  1. int crypto_auth(unsigned char *out, const unsigned char *in,
  2.                 unsigned long long inlen, const unsigned char *k);

The crypto_auth() function computes a tag for the message in, whose length is inlen bytes, and the key k. k should be crypto_auth_KEYBYTES bytes. The function puts the tag into out. The tag is crypto_auth_BYTES bytes long.

  1. int crypto_auth_verify(const unsigned char *h, const unsigned char *in,
  2.                        unsigned long long inlen, const unsigned char *k);

The crypto_auth_verify() function verifies that the tag stored at h is a valid tag for the message in whose length is inlen bytes, and the key k.

It returns -1 if the verification fails, and 0 if it passes.

  1. void crypto_auth_keygen(unsigned char k[crypto_auth_KEYBYTES]);

This helper function introduced in libsodium 1.0.12 creates a random key k.

It is equivalent to calling randombytes_buf() but improves code clarity and can prevent misuse by ensuring that the provided key length is always be correct.

Constants

  • crypto_auth_BYTES
  • crypto_auth_KEYBYTES

Algorithm details

  • HMAC-SHA512-256