One-time authentication in Sodium uses Poly1305, a Wegman-Carter authenticator designed by D. J. Bernstein.
Poly1305 takes a 32-byte, one-time key and a message and produces a 16-byte tag that authenticates the message such that an attacker has a negligible chance of producing a valid tag for a inauthentic message.
Poly1305 keys have to be:
secret. An attacker can compute a valid authentication tag for any message, for any given key. The security of Poly1305 relies on the fact that attackers don't know the key being used to compute the tag. This implies that they have to be:
unpredictable. Do not use timestamps or counters.
unique. Never reuse a key. A new key is required for every single message. The key can be recovered if two messages are authenticated with the same key.
The standard way to use Poly1305's is to derive a dedicated subkey from a (key, nonce) tuple, for example by taking the first bytes generated by a stream cipher.
Due to its output size, Poly1305 is recommended for online protocols, exchanging many small messages, rather than for authenticating very large files.
Finally, Poly1305 is not a replacement for a hash function.
#defineMESSAGE((constunsignedchar*)"Data to authenticate")
The crypto_onetimeauth() function authenticates a message in whose length is inlen using a secret key k (crypto_onetimeauth_KEYBYTES bytes) and puts the authenticator into out (crypto_onetimeauth_BYTES bytes).