Data Structures
struct	mbedtls_chacha20_context

struct	mbedtls_chachapoly_context

Macros
#define	MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA -0x0051
	Invalid input parameter(s). More...

#define	MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE -0x0053
	Feature not available. More...

#define	MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED -0x0055
	Chacha20 hardware accelerator failed. More...

Enumerations
enum	mbedtls_chachapoly_mode_t { MBEDTLS_CHACHAPOLY_ENCRYPT , MBEDTLS_CHACHAPOLY_DECRYPT }

Functions
void	mbedtls_chacha20_init (mbedtls_chacha20_context *ctx)
	This function initializes the specified ChaCha20 context. More...

void	mbedtls_chacha20_free (mbedtls_chacha20_context *ctx)
	This function releases and clears the specified ChaCha20 context. More...

int	mbedtls_chacha20_setkey (mbedtls_chacha20_context *ctx, const unsigned char key[32])
	This function sets the encryption/decryption key. More...

int	mbedtls_chacha20_starts (mbedtls_chacha20_context *ctx, const unsigned char nonce[12], uint32_t counter)
	This function sets the nonce and initial counter value. More...

int	mbedtls_chacha20_update (mbedtls_chacha20_context ctx, size_t size, const unsigned char input, unsigned char *output)
	This function encrypts or decrypts data. More...

int	mbedtls_chacha20_crypt (const unsigned char key[32], const unsigned char nonce[12], uint32_t counter, size_t size, const unsigned char input, unsigned char output)
	This function encrypts or decrypts data with ChaCha20 and the given key and nonce. More...

void	mbedtls_chachapoly_init (mbedtls_chachapoly_context *ctx)
	This function initializes the specified ChaCha20-Poly1305 context. More...

void	mbedtls_chachapoly_free (mbedtls_chachapoly_context *ctx)
	This function releases and clears the specified ChaCha20-Poly1305 context. More...

int	mbedtls_chachapoly_setkey (mbedtls_chachapoly_context *ctx, const unsigned char key[32])
	This function sets the ChaCha20-Poly1305 symmetric encryption key. More...

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. More...

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. More...

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. More...

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). More...

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. More...

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. More...

Detailed Description

Macro Definition Documentation

◆ MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA

#define MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA -0x0051

Invalid input parameter(s).

Definition at line 51 of file chacha20.h.

◆ MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE

#define MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE -0x0053

Feature not available.

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

Definition at line 55 of file chacha20.h.

◆ MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED

#define MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED -0x0055

Chacha20 hardware accelerator failed.

Definition at line 59 of file chacha20.h.

Enumeration Type Documentation

◆ mbedtls_chachapoly_mode_t

enum mbedtls_chachapoly_mode_t

Enumerator
MBEDTLS_CHACHAPOLY_ENCRYPT	The mode value for performing encryption.
MBEDTLS_CHACHAPOLY_DECRYPT	The mode value for performing decryption.

Definition at line 56 of file chachapoly.h.

Function Documentation

◆ mbedtls_chacha20_init()

void mbedtls_chacha20_init ( mbedtls_chacha20_context * ctx )

This function initializes the specified ChaCha20 context.

             It must be the first API called before using
             the context.

             It is usually followed by calls to
             \c mbedtls_chacha20_setkey() and
             \c mbedtls_chacha20_starts(), then one or more calls to
             to \c mbedtls_chacha20_update(), and finally to
             \c mbedtls_chacha20_free().

Parameters

ctx	The ChaCha20 context to initialize. This must not be `NULL`.

◆ mbedtls_chacha20_free()

void mbedtls_chacha20_free ( mbedtls_chacha20_context * ctx )

This function releases and clears the specified ChaCha20 context.

Parameters

ctx	The ChaCha20 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 context.

◆ mbedtls_chacha20_setkey()

int mbedtls_chacha20_setkey	(	mbedtls_chacha20_context *	ctx,
		const unsigned char	key[32]
	)

This function sets the encryption/decryption key.

Note: After using this function, you must also call mbedtls_chacha20_starts() to set a nonce before you start encrypting/decrypting data with mbedtls_chacha_update().

Parameters

ctx	The ChaCha20 context to which the key should be bound. It must be initialized.
key	The encryption/decryption key. This must be `32` Bytes in length.

Returns: 0 on success.; MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.

◆ mbedtls_chacha20_starts()

int mbedtls_chacha20_starts	(	mbedtls_chacha20_context *	ctx,
		const unsigned char	nonce[12],
		uint32_t	counter
	)

This function sets the nonce and initial counter value.

Note: A ChaCha20 context can be re-used with the same key by calling this function to change the nonce.

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

Parameters

ctx	The ChaCha20 context to which the nonce should be bound. It must be initialized and bound to a key.
nonce	The nonce. This must be `12` Bytes in size.
counter	The initial counter value. This is usually `0`.

Returns: 0 on success.; MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is NULL.

◆ mbedtls_chacha20_update()

int mbedtls_chacha20_update	(	mbedtls_chacha20_context *	ctx,
		size_t	size,
		const unsigned char *	input,
		unsigned char *	output
	)

This function encrypts or decrypts data.

             Since ChaCha20 is a stream cipher, the same operation is
             used for encrypting and decrypting data.

Note: The input and output pointers must either be equal or point to non-overlapping buffers.; mbedtls_chacha20_setkey() and mbedtls_chacha20_starts() must be called at least once to setup the context before this function can be called.; This function can be called multiple times in a row in order to encrypt of decrypt data piecewise with the same key and nonce.

Parameters

ctx	The ChaCha20 context to use for encryption or decryption. It must be initialized and bound to a key and nonce.
size	The length of the input data in Bytes.
input	The buffer holding the input data. This pointer can be `NULL` if `size == 0`.
output	The buffer holding the output data. This must be able to hold `size` Bytes. This pointer can be `NULL` if `size == 0`.

Returns: 0 on success.; A negative error code on failure.

◆ mbedtls_chacha20_crypt()

int mbedtls_chacha20_crypt	(	const unsigned char	key[32],
		const unsigned char	nonce[12],
		uint32_t	counter,
		size_t	size,
		const unsigned char *	input,
		unsigned char *	output
	)

This function encrypts or decrypts data with ChaCha20 and the given key and nonce.

Since ChaCha20 is a stream cipher, the same operation is used for encrypting and decrypting data.

Warning: You must never use the same (key, nonce) pair more than once. This would void any confidentiality guarantees for the messages encrypted with the same nonce and key.

Note: The input and output pointers must either be equal or point to non-overlapping buffers.

Parameters

key	The encryption/decryption key. This must be `32` Bytes in length.
nonce	The nonce. This must be `12` Bytes in size.
counter	The initial counter value. This is usually `0`.
size	The length of the input data in Bytes.
input	The buffer holding the input data. This pointer can be `NULL` if `size == 0`.
output	The buffer holding the output data. This must be able to hold `size` Bytes. This pointer can be `NULL` if `size == 0`.

Returns: 0 on success.; A negative error code on failure.

◆ mbedtls_chachapoly_init()

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
             \c mbedtls_chachapoly_setkey() before any operation can be
             done, and to \c 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
             \c mbedtls_chachapoly_crypt_and_tag() or
             \c mbedtls_chachapoly_auth_decrypt().

             In order to encrypt messages piecewise, for each
             message you should make a call to
             \c mbedtls_chachapoly_starts(), then 0 or more calls to
             \c mbedtls_chachapoly_update_aad(), then 0 or more calls to
             \c mbedtls_chachapoly_update(), then one call to
             \c 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. Must not be `NULL`.

◆ mbedtls_chachapoly_free()

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. This may be `NULL`, in which case this function is a no-op.

◆ mbedtls_chachapoly_setkey()

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. This must be initialized.
key	The `256` Bit (`32` Bytes) key.

Returns: 0 on success.; A negative error code on failure.

◆ mbedtls_chachapoly_starts()

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. This must be initialized and bound to a key.
nonce	The nonce/IV to use for the message. This must be a redable buffer of length `12` Bytes.
mode	The operation to perform: MBEDTLS_CHACHAPOLY_ENCRYPT or MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).

Returns: 0 on success.; A negative error code on failure.

◆ mbedtls_chachapoly_update_aad()

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. This must be initialized and bound to a key.
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.

◆ mbedtls_chachapoly_update()

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. This must be initialized.
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. This must be able to hold `len` bytes. This pointer can be `NULL` if `len == 0`.

Returns: 0 on success.; MBEDTLS_ERR_CHACHAPOLY_BAD_STATE if the operation has not been started or has been finished.; Another negative error code on other kinds of failure.

◆ mbedtls_chachapoly_finish()

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. This must be initialized.
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_CHACHAPOLY_BAD_STATE if the operation has not been started or has been finished.; Another negative error code on other kinds of failure.

◆ mbedtls_chachapoly_encrypt_and_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.

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). This must be initialized.
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. This must not be `NULL`.

Returns: 0 on success.; A negative error code on failure.

◆ mbedtls_chachapoly_auth_decrypt()

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. This must be a readable buffer of length `16` Bytes.
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_CHACHAPOLY_AUTH_FAILED if the data was not authentic.; Another negative error code on other kinds of failure.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA

◆ MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE

◆ MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED

Enumeration Type Documentation

◆ mbedtls_chachapoly_mode_t

Function Documentation

◆ mbedtls_chacha20_init()

◆ mbedtls_chacha20_free()

◆ mbedtls_chacha20_setkey()

◆ mbedtls_chacha20_starts()

◆ mbedtls_chacha20_update()

◆ mbedtls_chacha20_crypt()

◆ mbedtls_chachapoly_init()

◆ mbedtls_chachapoly_free()

◆ mbedtls_chachapoly_setkey()

◆ mbedtls_chachapoly_starts()

◆ mbedtls_chachapoly_update_aad()

◆ mbedtls_chachapoly_update()

◆ mbedtls_chachapoly_finish()

◆ mbedtls_chachapoly_encrypt_and_tag()

◆ mbedtls_chachapoly_auth_decrypt()