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.
Single-part example
1
#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).
The crypto_onetimeauth_verify() function verifies, in constant time, that h is a correct authenticator for the message in whose length is inlen bytes, using the secret key k.
It returns -1 if the verification fails, or 0 on success.
The crypto_onetimeauth_init() function initializes a structure pointed by state using a key key.
A 16 bytes alignment is required for the address of state. The size of this value can be obtained using sizeof(crypto_onetimeauth_state), or crypto_onetimeauth_statebytes().
crypto_onetimeauth_update() can then be called more than one in order to compute the authenticator from sequential chunks of the message.
Finally, crypto_onetimeauth_final() puts the authenticator into out.
The state must be initialized with crypto_onetimeauth_init() before updating or finalizing it.
After crypto_onetimeauth_final() returns, the state should not be used any more, unless it is reinitialized using crypto_onetimeauth_init().