ChaCha20-Poly1305 AEAD construction based on RFC 7539. More...

Functions
static int	chachapoly_pad_aad (mbedtls_chachapoly_context *ctx)
	Adds nul bytes to pad the AAD for Poly1305.
static int	chachapoly_pad_ciphertext (mbedtls_chachapoly_context *ctx)
	Adds nul bytes to pad the ciphertext for Poly1305.
void	mbedtls_chachapoly_init (mbedtls_chachapoly_context *ctx)
	This function initializes the specified ChaCha20-Poly1305 context.
void	mbedtls_chachapoly_free (mbedtls_chachapoly_context *ctx)
	This function releases and clears the specified ChaCha20-Poly1305 context.
int	mbedtls_chachapoly_setkey (mbedtls_chachapoly_context *ctx, const unsigned char key[32])
	This function sets the ChaCha20-Poly1305 symmetric encryption key.
int	mbedtls_chachapoly_starts (mbedtls_chachapoly_context *ctx, const unsigned char nonce[12], mbedtls_chachapoly_mode_t mode)
	This function starts a ChaCha20-Poly1305 encryption or decryption operation.
int	mbedtls_chachapoly_update_aad (mbedtls_chachapoly_context ctx, const unsigned char aad, size_t aad_len)
	This function feeds additional data to be authenticated into an ongoing ChaCha20-Poly1305 operation.
int	mbedtls_chachapoly_update (mbedtls_chachapoly_context ctx, size_t len, const unsigned char input, unsigned char *output)
	Thus function feeds data to be encrypted or decrypted into an on-going ChaCha20-Poly1305 operation.
int	mbedtls_chachapoly_finish (mbedtls_chachapoly_context *ctx, unsigned char mac[16])
	This function finished the ChaCha20-Poly1305 operation and generates the MAC (authentication tag).
int	mbedtls_chachapoly_encrypt_and_tag (mbedtls_chachapoly_context ctx, size_t length, const unsigned char nonce[12], const unsigned char aad, size_t aad_len, const unsigned char input, unsigned char output, unsigned char tag[16])
	This function performs a complete ChaCha20-Poly1305 authenticated encryption with the previously-set key.
int	mbedtls_chachapoly_auth_decrypt (mbedtls_chachapoly_context ctx, size_t length, const unsigned char nonce[12], const unsigned char aad, size_t aad_len, const unsigned char tag[16], const unsigned char input, unsigned char output)
	This function performs a complete ChaCha20-Poly1305 authenticated decryption with the previously-set key.
int	mbedtls_chachapoly_self_test (int verbose)
	The ChaCha20-Poly1305 checkup routine.

Detailed Description

ChaCha20-Poly1305 AEAD construction based on RFC 7539.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of mbed TLS (https://tls.mbed.org)

Definition in file chachapoly.c.

Function Documentation

static int chachapoly_pad_aad ( mbedtls_chachapoly_context * ctx ) [static]

Adds nul bytes to pad the AAD for Poly1305.

Parameters:

ctx	The ChaCha20-Poly1305 context.

Definition at line 57 of file chachapoly.c.

static int chachapoly_pad_ciphertext ( mbedtls_chachapoly_context * ctx ) [static]

Adds nul bytes to pad the ciphertext for Poly1305.

Parameters:

ctx	The ChaCha20-Poly1305 context.

Definition at line 77 of file chachapoly.c.

int mbedtls_chachapoly_auth_decrypt	(	mbedtls_chachapoly_context *	ctx,
		size_t	length,
		const unsigned char	nonce[12],
		const unsigned char *	aad,
		size_t	aad_len,
		const unsigned char	tag[16],
		const unsigned char *	input,
		unsigned char *	output
	)

This function performs a complete ChaCha20-Poly1305 authenticated decryption with the previously-set key.

Note:: Before using this function, you must set the key with mbedtls_chachapoly_setkey().

Parameters:

ctx	The ChaCha20-Poly1305 context to use (holds the key).
length	The length (in bytes) of the data to decrypt.
nonce	The 96-bit (12 bytes) nonce/IV to use.
aad	The buffer containing the additional authenticated data (AAD). This pointer can be NULL if aad_len == 0.
aad_len	The length (in bytes) of the AAD data to process.
tag	The buffer holding the authentication tag.
input	The buffer containing the data to decrypt. This pointer can be NULL if ilen == 0.
output	The buffer to where the decrypted data is written. This pointer can be NULL if ilen == 0.

Returns:: 0 on success.; MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA if one or more of the required parameters are NULL.; MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED if the data was not authentic.

Definition at line 358 of file chachapoly.c.

int mbedtls_chachapoly_encrypt_and_tag	(	mbedtls_chachapoly_context *	ctx,
		size_t	length,
		const unsigned char	nonce[12],
		const unsigned char *	aad,
		size_t	aad_len,
		const unsigned char *	input,
		unsigned char *	output,
		unsigned char	tag[16]
	)

This function performs a complete ChaCha20-Poly1305 authenticated encryption with the previously-set key.

Note:: Before using this function, you must set the key with mbedtls_chachapoly_setkey().

Warning:: You must never use the same nonce twice with the same key. This would void any confidentiality and authenticity guarantees for the messages encrypted with the same nonce and key.

Parameters:

ctx	The ChaCha20-Poly1305 context to use (holds the key).
length	The length (in bytes) of the data to encrypt or decrypt.
nonce	The 96-bit (12 bytes) nonce/IV to use.
aad	The buffer containing the additional authenticated data (AAD). This pointer can be NULL if aad_len == 0.
aad_len	The length (in bytes) of the AAD data to process.
input	The buffer containing the data to encrypt or decrypt. This pointer can be NULL if ilen == 0.
output	The buffer to where the encrypted or decrypted data is written. This pointer can be NULL if ilen == 0.
tag	The buffer to where the computed 128-bit (16 bytes) MAC is written.

Returns:: 0 on success.; MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA if one or more of the required parameters are NULL.

Definition at line 344 of file chachapoly.c.

int mbedtls_chachapoly_finish	(	mbedtls_chachapoly_context *	ctx,
		unsigned char	mac[16]
	)

This function finished the ChaCha20-Poly1305 operation and generates the MAC (authentication tag).

Parameters:

ctx	The ChaCha20-Poly1305 context to use.
mac	The buffer to where the 128-bit (16 bytes) MAC is written.

Warning:: Decryption with the piecewise API is discouraged, see the warning on mbedtls_chachapoly_init().

Returns:: 0 on success.; MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA if ctx or mac are NULL.; MBEDTLS_ERR_CHACHAPOLY_BAD_STATE if the operation has not been started or has been finished.

Definition at line 255 of file chachapoly.c.

void mbedtls_chachapoly_free ( mbedtls_chachapoly_context * ctx )

This function releases and clears the specified ChaCha20-Poly1305 context.

Parameters:

ctx	The ChachaPoly context to clear.

Definition at line 104 of file chachapoly.c.

void mbedtls_chachapoly_init ( mbedtls_chachapoly_context * ctx )

This function initializes the specified ChaCha20-Poly1305 context.

It must be the first API called before using the context. It must be followed by a call to mbedtls_chachapoly_setkey() before any operation can be done, and to mbedtls_chachapoly_free() once all operations with that context have been finished.

In order to encrypt or decrypt full messages at once, for each message you should make a single call to mbedtls_chachapoly_crypt_and_tag() or mbedtls_chachapoly_auth_decrypt().

In order to encrypt messages piecewise, for each message you should make a call to mbedtls_chachapoly_starts(), then 0 or more calls to mbedtls_chachapoly_update_aad(), then 0 or more calls to mbedtls_chachapoly_update(), then one call to mbedtls_chachapoly_finish().

Warning:: Decryption with the piecewise API is discouraged! Always use mbedtls_chachapoly_auth_decrypt() when possible!

If however this is not possible because the data is too large to fit in memory, you need to:

call mbedtls_chachapoly_starts() and (if needed) mbedtls_chachapoly_update_aad() as above,
call mbedtls_chachapoly_update() multiple times and ensure its output (the plaintext) is NOT used in any other way than placing it in temporary storage at this point,
call mbedtls_chachapoly_finish() to compute the authentication tag and compared it in constant time to the tag received with the ciphertext.

If the tags are not equal, you must immediately discard all previous outputs of mbedtls_chachapoly_update(), otherwise you can now safely use the plaintext.

Parameters:

ctx	The ChachaPoly context to initialize.

Definition at line 91 of file chachapoly.c.

int mbedtls_chachapoly_self_test ( int verbose )

The ChaCha20-Poly1305 checkup routine.

Returns:: 0 on success.; 1 on failure.

Definition at line 498 of file chachapoly.c.

int mbedtls_chachapoly_setkey	(	mbedtls_chachapoly_context *	ctx,
		const unsigned char	key[32]
	)

This function sets the ChaCha20-Poly1305 symmetric encryption key.

Parameters:

ctx	The ChaCha20-Poly1305 context to which the key should be bound.
key	The 256-bit (32 bytes) key.

Returns:: 0 on success.; MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA if ctx or key are NULL.

Definition at line 117 of file chachapoly.c.

int mbedtls_chachapoly_starts	(	mbedtls_chachapoly_context *	ctx,
		const unsigned char	nonce[12],
		mbedtls_chachapoly_mode_t	mode
	)

This function starts a ChaCha20-Poly1305 encryption or decryption operation.

Warning:: You must never use the same nonce twice with the same key. This would void any confidentiality and authenticity guarantees for the messages encrypted with the same nonce and key.

Note:: If the context is being used for AAD only (no data to encrypt or decrypt) then mode can be set to any value.

Warning:: Decryption with the piecewise API is discouraged, see the warning on mbedtls_chachapoly_init().

Parameters:

ctx	The ChaCha20-Poly1305 context.
nonce	The nonce/IV to use for the message. Must be 12 bytes.
mode	The operation to perform: MBEDTLS_CHACHAPOLY_ENCRYPT or MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).

Returns:: 0 on success.; MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA if ctx or mac are NULL.

Definition at line 132 of file chachapoly.c.

int mbedtls_chachapoly_update	(	mbedtls_chachapoly_context *	ctx,
		size_t	len,
		const unsigned char *	input,
		unsigned char *	output
	)

Thus function feeds data to be encrypted or decrypted into an on-going ChaCha20-Poly1305 operation.

The direction (encryption or decryption) depends on the mode that was given when calling mbedtls_chachapoly_starts().

You may call this function multiple times to process an arbitrary amount of data. It is permitted to call this function 0 times, if no data is to be encrypted or decrypted.

Warning:: Decryption with the piecewise API is discouraged, see the warning on mbedtls_chachapoly_init().

Parameters:

ctx	The ChaCha20-Poly1305 context to use.
len	The length (in bytes) of the data to encrypt or decrypt.
input	The buffer containing the data to encrypt or decrypt. This pointer can be NULL if len == 0.
output	The buffer to where the encrypted or decrypted data is written. Must be able to hold `len` bytes. This pointer can be NULL if len == 0.

Returns:: 0 on success.; MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA if ctx, input, or output are NULL.; MBEDTLS_ERR_CHACHAPOLY_BAD_STATE if the operation has not been started or has been finished.

Definition at line 198 of file chachapoly.c.

int mbedtls_chachapoly_update_aad	(	mbedtls_chachapoly_context *	ctx,
		const unsigned char *	aad,
		size_t	aad_len
	)

This function feeds additional data to be authenticated into an ongoing ChaCha20-Poly1305 operation.

The Additional Authenticated Data (AAD), also called Associated Data (AD) is only authenticated but not encrypted nor included in the encrypted output. It is usually transmitted separately from the ciphertext or computed locally by each party.

Note:: This function is called before data is encrypted/decrypted. I.e. call this function to process the AAD before calling mbedtls_chachapoly_update().

You may call this function multiple times to process an arbitrary amount of AAD. It is permitted to call this function 0 times, if no AAD is used.

This function cannot be called any more if data has been processed by mbedtls_chachapoly_update(), or if the context has been finished.

Warning:: Decryption with the piecewise API is discouraged, see the warning on mbedtls_chachapoly_init().

Parameters:

ctx	The ChaCha20-Poly1305 context to use.
aad_len	The length (in bytes) of the AAD. The length has no restrictions.
aad	Buffer containing the AAD. This pointer can be NULL if aad_len == 0.

Returns:: 0 on success.; MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA if ctx or aad are NULL.; MBEDTLS_ERR_CHACHAPOLY_BAD_STATE if the operations has not been started or has been finished, or if the AAD has been finished.

Definition at line 175 of file chachapoly.c.

Type:	Program
Created:	12 Feb 2019
Imports:	15
Forks:	0
Commits:	7
Dependents:	0
Dependencies:	3
Followers:	1

Important changes to repositories hosted on mbed.com

chachapoly.c File Reference

Functions

Detailed Description

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

chachapoly.c File Reference

Functions

Detailed Description

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning