poly1305.h File Reference

Poly1305 function definitions
Contains the public api and documentation for the Poly1305 implementation. More...

#include "common.h"

Go to the source code of this file.

Data Structures
struct	qsc_poly1305_state
	Contains the Poly1305 internal state. More...

Macros
#define	QSC_POLY1305_BLOCK_SIZE   16
	The natural block size of the message input in bytes.
#define	QSC_POLY1305_KEY_SIZE   32
	The Poly1305 key size in bytes.
#define	QSC_POLY1305_MAC_SIZE   16
	The Poly1305 MAC code size in bytes.

Typedefs
typedef QSC_EXPORT_API struct qsc_poly1305_state	qsc_poly1305_state

Functions
QSC_EXPORT_API void	qsc_poly1305_blockupdate (qsc_poly1305_state *ctx, const uint8_t *message)
	Update the poly1305 generator with a single block of message input. Absorbs block sized lengths of input message into the ctx.
QSC_EXPORT_API void	qsc_poly1305_compute (uint8_t *output, const uint8_t *message, size_t msglen, const uint8_t *key)
	Compute the MAC code and return the result in the mac byte array.
QSC_EXPORT_API void	qsc_poly1305_dispose (qsc_poly1305_state *ctx)
	Dispose of the ctx resetting all values to zero.
QSC_EXPORT_API void	qsc_poly1305_finalize (qsc_poly1305_state *ctx, uint8_t *mac)
	Finalize the message ctx and returns the MAC code. Absorb the last block of message and create the MAC array. .
QSC_EXPORT_API void	qsc_poly1305_initialize (qsc_poly1305_state *ctx, const uint8_t *key)
	Initialize the ctx with the secret key.
QSC_EXPORT_API void	qsc_poly1305_reset (qsc_poly1305_state *ctx)
	Reset the ctx values to zero.
QSC_EXPORT_API void	qsc_poly1305_update (qsc_poly1305_state *ctx, const uint8_t *message, size_t msglen)
	Update the poly1305 generator with a length of message input. Absorbs the input message into the ctx.
QSC_EXPORT_API int32_t	qsc_poly1305_verify (const uint8_t *code, const uint8_t *message, size_t msglen, const uint8_t *key)
	Verify a MAC code. Tests the code against the message and returns MQC_STATUS_SUCCESS or MQC_STATUS_FAILURE.

Detailed Description

Poly1305 function definitions
Contains the public api and documentation for the Poly1305 implementation.

Poly1305 Examples

uint8_t key[QSC_POLY1305_KEY_SIZE];
uint8_t mac[QSC_POLY1305_MAC_SIZE];
uint8_t msg[34];
 
// simplified
qsc_poly1305_compute(mac, msg, 34, key);
 
// long-form
size_t i;
qsc_poly1305_state ctx;
 
qsc_poly1305_initialize(&ctx, key);
 
for (i = 0; i < 32; i += QSC_POLY1305_BLOCK_SIZE)
{
  qsc_poly1305_blockupdate(&ctx, msg + i);
}
 
qsc_poly1305_update(&ctx, msg + i, 2);
qsc_poly1305_finalize(&ctx, mac);

Remarks

For usage examples, see poly1305_test.h

Function Documentation

qsc_poly1305_blockupdate()

QSC_EXPORT_API void qsc_poly1305_blockupdate	(	qsc_poly1305_state *	ctx,
		const uint8_t *	message )

Update the poly1305 generator with a single block of message input. Absorbs block sized lengths of input message into the ctx.

Warning

Message length must be a single 16 byte message block.

Parameters

ctx	[struct] The function ctx; must be initialized
message	[const] The input message byte array

qsc_poly1305_compute()

QSC_EXPORT_API void qsc_poly1305_compute	(	uint8_t *	output,
		const uint8_t *	message,
		size_t	msglen,
		const uint8_t *	key )

Compute the MAC code and return the result in the mac byte array.

Warning

The output array must be at least 16 bytes in length.

Parameters

output	The output byte array; receives the MAC code
message	[const] The message input byte array
msglen	The number of message bytes to process
key	[const] The 32 byte key array

qsc_poly1305_dispose()

QSC_EXPORT_API void qsc_poly1305_dispose

(

qsc_poly1305_state *

ctx

)

Dispose of the ctx resetting all values to zero.

Parameters

ctx	[struct] The function ctx

qsc_poly1305_finalize()

QSC_EXPORT_API void qsc_poly1305_finalize	(	qsc_poly1305_state *	ctx,
		uint8_t *	mac )

Finalize the message ctx and returns the MAC code. Absorb the last block of message and create the MAC array.
.

Parameters

ctx	[struct] The function ctx; must be initialized
mac	The MAC byte array; receives the MAC code

qsc_poly1305_initialize()

QSC_EXPORT_API void qsc_poly1305_initialize	(	qsc_poly1305_state *	ctx,
		const uint8_t *	key )

Initialize the ctx with the secret key.

Parameters

ctx	[struct] The function ctx
key	[const] The secret key byte array

qsc_poly1305_reset()

QSC_EXPORT_API void qsc_poly1305_reset

(

qsc_poly1305_state *

ctx

)

Reset the ctx values to zero.

Parameters

ctx	The function ctx

qsc_poly1305_update()

QSC_EXPORT_API void qsc_poly1305_update	(	qsc_poly1305_state *	ctx,
		const uint8_t *	message,
		size_t	msglen )

Update the poly1305 generator with a length of message input. Absorbs the input message into the ctx.

Parameters

ctx	[struct] The function ctx; must be initialized
message	[const] The input message byte array
msglen	The number of input message bytes to process

qsc_poly1305_verify()

QSC_EXPORT_API int32_t qsc_poly1305_verify	(	const uint8_t *	code,
		const uint8_t *	message,
		size_t	msglen,
		const uint8_t *	key )

Verify a MAC code. Tests the code against the message and returns MQC_STATUS_SUCCESS or MQC_STATUS_FAILURE.

Parameters

code	[const] The MAC code byte array
message	[const] The message byte array
msglen	The number of message bytes to process
key	[const] The secret key byte array

Returns

Returns success or failure