Monocypher

Boring crypto that simply works

Poly1305

Poly1305 one-time message authentication codes

Synopsis

#include <monocypher.h>

void crypto_poly1305(uint8_t        mac[16],
                     const uint8_t *message,
                     size_t         message_size,
                     const          uint8_t key[32]);

void crypto_poly1305_init(crypto_poly1305_ctx *ctx,
                          const uint8_t        key[32]);

void crypto_poly1305_update(crypto_poly1305_ctx *ctx,
                            const uint8_t       *message,
                            size_t               message_size);

void crypto_poly1305_final(crypto_poly1305_ctx *ctx,
                           uint8_t              mac[16]);

Description

Poly1305 is a one-time message authentication code. "One-time" means the authentication key can be used only once. This makes Poly1305 easy to misuse. On the other hand, Poly1305 is fast, and provably secure if used correctly.

Poly1305 is a low-level primitive. Consider using authenticated encryption.

The arguments are:

Direct interface

crypto_poly1305() produces a message authentication code for the given message and authentication key. To verify the integrity of a message, use crypto_verify16() to compare the received MAC to the output mac.

Incremental interface

crypto_poly1305_init() initialises a context. key should be wiped once the context is initialised. Then, crypto_poly1305_update() authenticates the message chunk by chunk. Once the message is entirely processed, crypto_poly1305_final() yields the message authentication code.

Return values

These functions return nothing.

Examples

To authenticate a message:

const uint8_t msg[500]; /* Message to authenticate           */
const uint8_t key[ 32]; /* Random secret key (use only once) */
uint8_t       mac[ 16]; /* Message authentication code (MAC) */
crypto_poly1305(mac, msg, 500, key);
/* Wipe the key */
crypto_wipe(key, 32);

To verify the above message:

const uint8_t msg     [500]; /* Message to verify */
const uint8_t key     [ 32]; /* The above key     */
const uint8_t mac     [ 16]; /* The above MAC     */
uint8_t       real_mac[ 16]; /* The actual MAC    */
crypto_poly1305(real_mac, msg, 500, key);
/* Wipe the key */
crypto_wipe(key, 32);
if (crypto_verify16(mac, real_mac)) {
    /* Corrupted message, abort processing */
} else {
    /* Genuine message */
}
/* The real mac is secret.  Wipe it */
crypto_wipe(real_mac, 16);

Incremental authentication:

const uint8_t msg[500]; /* Message to authenticate           */
const uint8_t key[ 32]; /* Random secret key (use only once) */
uint8_t       mac[ 16]; /* Message authentication code (MAC) */
crypto_poly1305_ctx ctx;
crypto_poly1305_init(&ctx, key);
/* Wipe the key */
crypto_wipe(key, 32);
for (int i = 0; i < 500; i += 100) {
    crypto_poly1305_update(&ctx, msg, 100);
}
crypto_poly1305_final(&ctx, mac);

Standards

These functions implement Poly1305, described in RFC 7539.

Security considerations

Poly1305 is difficult to use correctly. Do not use it unless you are absolutely sure what you are doing. Use authenticated encryption instead; see crypto_lock() . If you are certain you do not want encryption, refer to crypto_blake2b() on how to use Blake2b to generate message authentication codes.

Authentication key requirements

Poly1305 is a one time authenticator. This puts rather stringent constraints on the authentication key:

The only practical source for the authentication key is a chunk of the encryption stream used to encrypt the message. That chunk must be dedicated to the authentication key: if it is reused to encrypt the message itself, the attacker may recover that chunk by guessing the message, then forge arbitrary messages.

To get this right, you need a session key, a unique nonce, and a stream cipher. Generate a stream with the session key and nonce. Take the first 32 bytes of that stream as your authentication key, then use the rest of the stream to encrypt your message. This is the approach used by crypto_lock_aead() .

Protection against side channels

Use crypto_verify16() to compare message authentication codes. Avoid standard buffer comparison functions. They may not run in constant time, enabling an attacker to exploit timing attacks to recover the MAC.

The authentication key should be wiped with crypto_wipe() after use.

The incremental interface automatically wipes its context when finished so users do not need to do it themselves.