Poly1305

Data Structures
struct	mbedtls_poly1305_context

Macros
#define	MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA   -0x0057
	Invalid input parameter(s).
#define	MBEDTLS_ERR_POLY1305_FEATURE_UNAVAILABLE   -0x0059
	Feature not available.
#define	MBEDTLS_ERR_POLY1305_HW_ACCEL_FAILED   -0x005B
	Poly1305 hardware accelerator failed.

Functions
void	mbedtls_poly1305_init (mbedtls_poly1305_context *ctx)
	This function initializes the specified Poly1305 context.
void	mbedtls_poly1305_free (mbedtls_poly1305_context *ctx)
	This function releases and clears the specified Poly1305 context.
int	mbedtls_poly1305_starts (mbedtls_poly1305_context *ctx, const unsigned char key[32])
	This function sets the one-time authentication key.
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.
int	mbedtls_poly1305_finish (mbedtls_poly1305_context *ctx, unsigned char mac[16])
	This function generates the Poly1305 Message Authentication Code (MAC).
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.

Detailed Description

Macro Definition Documentation

MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA

#define MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA   -0x0057

Invalid input parameter(s).

Definition at line 51 of file poly1305.h.

MBEDTLS_ERR_POLY1305_FEATURE_UNAVAILABLE

#define MBEDTLS_ERR_POLY1305_FEATURE_UNAVAILABLE   -0x0059

Feature not available.

For example, s part of the API is not implemented.

Definition at line 55 of file poly1305.h.

MBEDTLS_ERR_POLY1305_HW_ACCEL_FAILED

#define MBEDTLS_ERR_POLY1305_HW_ACCEL_FAILED   -0x005B

Poly1305 hardware accelerator failed.

Definition at line 59 of file poly1305.h.

Function Documentation

mbedtls_poly1305_init()

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.

mbedtls_poly1305_free()

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.

mbedtls_poly1305_starts()

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.

A negative error code on failure.

mbedtls_poly1305_update()

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.

A negative error code on failure.

mbedtls_poly1305_finish()

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.

A negative error code on failure.

mbedtls_poly1305_mac()

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.

A negative error code on failure.