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 notNULL
, 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()
andmbedtls_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
ifilen == 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
ifilen == 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>