Algorithms - Poly1305

Functions
int	wc_Poly1305SetKey (Poly1305 *poly1305, const byte *key, word32 kySz)
	This function sets the key for a Poly1305 context structure, initializing it for hashing. Note: A new key should be set after generating a message hash with wc_Poly1305Final to ensure security. More...
int	wc_Poly1305Update (Poly1305 *poly1305, const byte *m, word32 bytes)
	This function updates the message to hash with the Poly1305 structure. More...
int	wc_Poly1305Final (Poly1305 *poly1305, byte *tag)
	This function calculates the hash of the input messages and stores the result in mac. After this is called, the key should be reset. More...
int	wc_Poly1305_MAC (Poly1305 *ctx, byte *additional, word32 addSz, byte *input, word32 sz, byte *tag, word32 tagSz)
	Takes in an initialized Poly1305 struct that has a key loaded and creates a MAC (tag) using recent TLS AEAD padding scheme. More...

Detailed Description

Function Documentation

wc_Poly1305_MAC()

int wc_Poly1305_MAC	(	Poly1305 *	ctx,
		byte *	additional,
		word32	addSz,
		byte *	input,
		word32	sz,
		byte *	tag,
		word32	tagSz
	)

Takes in an initialized Poly1305 struct that has a key loaded and creates a MAC (tag) using recent TLS AEAD padding scheme.

Returns

0 Success

BAD_FUNC_ARG Returned if ctx, input, or tag is null or if additional is null and addSz is greater than 0 or if tagSz is less than WC_POLY1305_MAC_SZ.

Parameters

ctx	Initialized Poly1305 struct to use
additional	Additional data to use
addSz	Size of additional buffer
input	Input buffer to create tag from
sz	Size of input buffer
tag	Buffer to hold created tag
tagSz	Size of input tag buffer (must be at least WC_POLY1305_MAC_SZ(16))

Example

Poly1305 ctx;
byte key[] = { }; // initialize with 32 byte key to use for hashing
byte additional[] = { }; // initialize with additional data
byte msg[] = { }; // initialize with message
byte tag[16];
 
wc_Poly1305SetKey(&ctx, key, sizeof(key));
if(wc_Poly1305_MAC(&ctx, additional, sizeof(additional), (byte*)msg,
sizeof(msg), tag, sizeof(tag)) != 0)
{
    // Handle the error
}

See also

wc_Poly1305SetKey

wc_Poly1305Update

wcPoly1305Final

wc_Poly1305Final()

int wc_Poly1305Final	(	Poly1305 *	poly1305,
		byte *	tag
	)

This function calculates the hash of the input messages and stores the result in mac. After this is called, the key should be reset.

Returns

0 Returned on successfully computing the final MAC

BAD_FUNC_ARG Returned if the Poly1305 structure is NULL

Parameters

ctx	pointer to a Poly1305 structure with which to generate the MAC
mac	pointer to the buffer in which to store the MAC. Should be POLY1305_DIGEST_SIZE (16 bytes) wide

Example

Poly1305 enc;
byte mac[POLY1305_DIGEST_SIZE]; // space for a 16 byte mac
 
byte key[] = { }; // initialize with 32 byte key to use for encryption
 
byte msg[] = { }; // initialize with message to hash
wc_Poly1305SetKey(&enc, key, sizeof(key));
wc_Poly1305Update(key, msg, sizeof(msg));
 
if ( wc_Poly1305Final(&enc, mac) != 0 ) {
    // error computing final MAC
}

See also

wc_Poly1305SetKey

wc_Poly1305Update

wc_Poly1305SetKey()

int wc_Poly1305SetKey	(	Poly1305 *	poly1305,
		const byte *	key,
		word32	kySz
	)

This function sets the key for a Poly1305 context structure, initializing it for hashing. Note: A new key should be set after generating a message hash with wc_Poly1305Final to ensure security.

Returns

0 Returned on successfully setting the key and initializing the Poly1305 structure

BAD_FUNC_ARG Returned if the given key is not 32 bytes long, or the Poly1305 context is NULL

Parameters

ctx	pointer to a Poly1305 structure to initialize
key	pointer to the buffer containing the key to use for hashing
keySz	size of the key in the buffer. Should be 32 bytes

Example

Poly1305 enc;
byte key[] = { initialize with 32 byte key to use for hashing };
wc_Poly1305SetKey(&enc, key, sizeof(key));

See also

wc_Poly1305Update

wc_Poly1305Final

wc_Poly1305Update()

int wc_Poly1305Update	(	Poly1305 *	poly1305,
		const byte *	m,
		word32	bytes
	)

This function updates the message to hash with the Poly1305 structure.

Returns

0 Returned on successfully updating the message to hash

BAD_FUNC_ARG Returned if the Poly1305 structure is NULL

Parameters

ctx	pointer to a Poly1305 structure for which to update the message to hash
m	pointer to the buffer containing the message which should be added to the hash
bytes	size of the message to hash

Example

Poly1305 enc;
byte key[] = { }; // initialize with 32 byte key to use for encryption
 
byte msg[] = { }; // initialize with message to hash
wc_Poly1305SetKey(&enc, key, sizeof(key));
 
if( wc_Poly1305Update(key, msg, sizeof(msg)) != 0 ) {
    // error updating message to hash
}

See also

wc_Poly1305SetKey

wc_Poly1305Final