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).

Typedefs

typedef struct mbedtls_poly1305_context mbedtls_poly1305_context

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.

struct mbedtls_poly1305_context
#include <poly1305.h>

Public Members

uint32_t private_r[4]
uint32_t private_s[4]

The value for ‘r’ (low 128 bits of the key).

uint32_t private_acc[5]

The value for ‘s’ (high 128 bits of the key).

uint8_t private_queue[16]

The accumulator number.

size_t private_queue_len

The current partial block of data.