PolarSSL is now part of ARM Official announcement and rebranded as mbed TLS.

API Documentation (Doxygen generated)

These pages are generated with doxygen directly from the source code!

poly1305.h File Reference

This file contains Poly1305 definitions and functions. More...

#include "config.h"
#include <stdint.h>
#include <stddef.h>
Include dependency graph for poly1305.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  mbedtls_poly1305_context
 

Macros

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

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

Detailed Description

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 damak.nosp@m.i.gh.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

Definition in file poly1305.h.

Macro Definition Documentation

#define MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA   -0x0057

Invalid input parameter(s).

Definition at line 45 of file poly1305.h.

#define MBEDTLS_ERR_POLY1305_FEATURE_UNAVAILABLE   -0x0059

Feature not available.

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

Definition at line 49 of file poly1305.h.

#define MBEDTLS_ERR_POLY1305_HW_ACCEL_FAILED   -0x005B

Poly1305 hardware accelerator failed.

Definition at line 53 of file poly1305.h.

Typedef Documentation

Function Documentation

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

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

Parameters
ctxThe Poly1305 context to use for the Poly1305 operation. This must be initialized and bound to a key.
macThe 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.
void mbedtls_poly1305_free ( mbedtls_poly1305_context ctx)

This function releases and clears the specified Poly1305 context.

Parameters
ctxThe 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.
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 mbedtls_poly1305_starts(), then one or more calls to mbedtls_poly1305_update(), then one call to mbedtls_poly1305_finish(), then finally mbedtls_poly1305_free().

Parameters
ctxThe Poly1305 context to initialize. This must not be NULL.
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
keyThe buffer containing the 32 Byte (256 Bit) key.
ilenThe length of the input data in Bytes. Any value is accepted.
inputThe buffer holding the input data. This pointer can be NULL if ilen == 0.
macThe 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.
int mbedtls_poly1305_self_test ( int  verbose)

The Poly1305 checkup routine.

Returns
0 on success.
1 on failure.
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
ctxThe Poly1305 context to which the key should be bound. This must be initialized.
keyThe buffer containing the 32 Byte (256 Bit) key.
Returns
0 on success.
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
ctxThe Poly1305 context to use for the Poly1305 operation. This must be initialized and bound to a key.
ilenThe length of the input data in Bytes. Any value is accepted.
inputThe buffer holding the input data. This pointer can be NULL if ilen == 0.
Returns
0 on success.
A negative error code on failure.