File poly1305.h

This file contains Poly1305 definitions and functions.

     Poly1305 is a one-time message authenticator that can be used to
     authenticate messages. Poly1305-AES was created by Daniel
     Bernstein https://cr.yp.to/mac/poly1305-20050329.pdf The generic
     Poly1305 algorithm (not tied to AES) was also standardized in RFC
     7539.

Author: Daniel King damaki.gh@gmail.com

Defines

MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA: Invalid input parameter(s).

Functions

void mbedtls_poly1305_init(mbedtls_poly1305_context *ctx)

This function initializes the specified Poly1305 context.

             It must be the first API called before using
             the context.

             It is usually followed by a call to
             \c mbedtls_poly1305_starts(), then one or more calls to
             \c mbedtls_poly1305_update(), then one call to
             \c mbedtls_poly1305_finish(), then finally
             \c mbedtls_poly1305_free().

Parameters: ctx – The Poly1305 context to initialize. This must not be NULL.

void mbedtls_poly1305_free(mbedtls_poly1305_context *ctx)

This function releases and clears the specified Poly1305 context.

Parameters: ctx – The Poly1305 context to clear. This may be NULL, in which case this function is a no-op. If it is not NULL, it must point to an initialized Poly1305 context.

int mbedtls_poly1305_starts(mbedtls_poly1305_context *ctx, const unsigned char key[32])

This function sets the one-time authentication key.

Warning

The key must be unique and unpredictable for each invocation of Poly1305.

Parameters

ctx – The Poly1305 context to which the key should be bound. This must be initialized.
key – The buffer containing the 32 Byte (256 Bit) key.

Returns

0 on success.

Returns

A negative error code on failure.

int mbedtls_poly1305_update(mbedtls_poly1305_context *ctx, const unsigned char *input, size_t ilen)

This functions feeds an input buffer into an ongoing Poly1305 computation.

It is called between mbedtls_cipher_poly1305_starts() and mbedtls_cipher_poly1305_finish(). It can be called repeatedly to process a stream of data.

Parameters

ctx – The Poly1305 context to use for the Poly1305 operation. This must be initialized and bound to a key.
ilen – The length of the input data in Bytes. Any value is accepted.
input – The buffer holding the input data. This pointer can be NULL if ilen == 0.

Returns

0 on success.

Returns

A negative error code on failure.

int mbedtls_poly1305_finish(mbedtls_poly1305_context *ctx, unsigned char mac[16])

This function generates the Poly1305 Message Authentication Code (MAC).

Parameters

ctx – The Poly1305 context to use for the Poly1305 operation. This must be initialized and bound to a key.
mac – The buffer to where the MAC is written. This must be a writable buffer of length 16 Bytes.

Returns

0 on success.

Returns

A negative error code on failure.

int mbedtls_poly1305_mac(const unsigned char key[32], const unsigned char *input, size_t ilen, unsigned char mac[16])

This function calculates the Poly1305 MAC of the input buffer with the provided key.

Warning

The key must be unique and unpredictable for each invocation of Poly1305.

Parameters

key – The buffer containing the 32 Byte (256 Bit) key.
ilen – The length of the input data in Bytes. Any value is accepted.
input – The buffer holding the input data. This pointer can be NULL if ilen == 0.
mac – The buffer to where the MAC is written. This must be a writable buffer of length 16 Bytes.

Returns

0 on success.

Returns

A negative error code on failure.

int mbedtls_poly1305_self_test(int verbose)

The Poly1305 checkup routine.

Returns: 0 on success.
Returns: 1 on failure.