chacha.h File Reference

Contains the public API and documentation for the ChaCha20 implementation. More...

#include "common.h"
#include "poly1305.h"

Go to the source code of this file.

Data Structures
struct	qsc_chacha_state
	Internal state structure for the ChaCha20 cipher. More...
struct	qsc_chacha_keyparams
	Key parameters for the ChaCha20 cipher. More...
struct	qsc_chacha_poly1305_state

Macros
#define	QSC_CHACHA_BLOCK_SIZE   64ULL
	The internal block size used by the ChaCha20 cipher (in bytes).
#define	QSC_CHACHA_KEY128_SIZE   16ULL
	The size of the 128-bit secret key (in bytes).
#define	QSC_CHACHA_KEY256_SIZE   32ULL
	The size of the 256-bit secret key (in bytes).
#define	QSC_CHACHA_NONCE_SIZE   12ULL
	The size of the nonce in bytes.
#define	QSC_CHACHA_ROUND_COUNT   20ULL
	The number of mixing rounds used by ChaCha20.

Functions
QSC_EXPORT_API void	qsc_chacha_dispose (qsc_chacha_state *ctx)
	Dispose of the ChaCha20 cipher state.
QSC_EXPORT_API void	qsc_chacha_initialize (qsc_chacha_state *ctx, const qsc_chacha_keyparams *keyparams)
	Initialize the ChaCha20 cipher state with the secret key and nonce.
QSC_EXPORT_API void	qsc_chacha_transform (qsc_chacha_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Process a block of input data using the ChaCha20 cipher.
QSC_EXPORT_API void	qsc_chacha_poly1305_set_associated (qsc_chacha_poly1305_state *ctx, const uint8_t *data, size_t datalen)
	Set the associated data (AAD) for ChaCha-Poly1305 authenticated encryption.
QSC_EXPORT_API bool	qsc_chacha_poly1305_decrypt (qsc_chacha_poly1305_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Decrypt data using the ChaCha-Poly1305 authenticated encryption mode.
QSC_EXPORT_API void	qsc_chacha_poly1305_dispose (qsc_chacha_poly1305_state *ctx)
	Dispose of an ChaCha-Poly1305 state.
QSC_EXPORT_API void	qsc_chacha_poly1305_initialize (qsc_chacha_poly1305_state *ctx, const qsc_chacha_keyparams *keyparams)
	Initialize the ChaCha-Poly1305 state for authenticated encryption or decryption.
QSC_EXPORT_API void	qsc_chacha_poly1305_encrypt (qsc_chacha_poly1305_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Encrypt data using the ChaCha-Poly1305 authenticated encryption mode.

Detailed Description

Contains the public API and documentation for the ChaCha20 implementation.

This header defines the API for the ChaCha20 stream cipher implementation used by TLS and specified in RFC?7539. The cipher supports both 128-bit and 256-bit key sizes (16 or 32 bytes respectively) and requires an 12-byte nonce for initialization. The implementation includes support for AVX, AVX2, and AVX512 intrinsics where available, ensuring high-performance encryption on modern processors. ChaCha20 is widely recognized for its security and efficiency in both software and hardware implementations.

Example Usage:

#include "chacha.h"
 
size_t const MSG_LEN = 1024;
uint8_t key[32] = { 0 };                      // 256-bit key
uint8_t nonce[QSC_CHACHA_NONCE_SIZE] = { 0 }; // 12-byte nonce
uint8_t msg[MSG_LEN] = { 0 };
uint8_t out[MSG_LEN] = { 0 };
 
qsc_chacha_state ctx;
qsc_chacha_keyparams kp = { key, 32, nonce };
 
qsc_chacha_initialize(&ctx, &kp);
qsc_chacha_transform(&ctx, out, msg, MSG_LEN);

Reference Links:

• ChaCha20 Stream Cipher Specification

Function Documentation

qsc_chacha_dispose()

QSC_EXPORT_API void qsc_chacha_dispose

(

qsc_chacha_state *

ctx

)

Dispose of the ChaCha20 cipher state.

Securely clears the internal state array.

Parameters

ctx	[qsc_chacha_state*] Pointer to the ChaCha20 state structure.

qsc_chacha_initialize()

QSC_EXPORT_API void qsc_chacha_initialize	(	qsc_chacha_state *	ctx,
		const qsc_chacha_keyparams *	keyparams )

Initialize the ChaCha20 cipher state with the secret key and nonce.

Warning

The key must be either 16 or 32 bytes in length, and the nonce must be exactly 12 bytes.

Parameters

ctx	[qsc_chacha_state*] Pointer to the ChaCha20 state structure.
keyparams	[const qsc_chacha_keyparams*] Pointer to the key parameters structure containing the key and nonce.

qsc_chacha_poly1305_decrypt()

QSC_EXPORT_API bool qsc_chacha_poly1305_decrypt	(	qsc_chacha_poly1305_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Decrypt data using the ChaCha-Poly1305 authenticated encryption mode.

This function decrypts the plaintext using ChaCha in Poly1305 mode, computes a MAC over the ciphertext, and writes the MAC to the tag parameter.

Parameters

ctx	[struct] Pointer to an initialized qsc_chacha_poly1305_state structure.
output	[uint8_t*] Pointer to the plaintext buffer.
input	[const uint8_t*] Pointer to the ciphertext data with the appended MAC.
length	[size_t] Length of the input ciphertext in bytes.

Returns

[bool] Returns true if the MAC verification and transformation was successful; otherwise, false.

See also

qsc_chacha_poly1305_initialize, qsc_chacha_poly1305_set_associated

qsc_chacha_poly1305_dispose()

QSC_EXPORT_API void qsc_chacha_poly1305_dispose

(

qsc_chacha_poly1305_state *

ctx

)

Dispose of an ChaCha-Poly1305 state.

Securely clears all internal state and keys used by the ChaCha-Poly1305 authenticated encryption mode.

Parameters

ctx	[struct] Pointer to a qsc_chacha_poly1305_state structure.

Warning

Must be called before the state goes out of scope.

See also

qsc_chacha_poly1305_set_associated, qsc_chacha_poly1305_decrypt, qsc_chacha_poly1305_encrypt, qsc_chacha_poly1305_initialize

qsc_chacha_poly1305_encrypt()

QSC_EXPORT_API void qsc_chacha_poly1305_encrypt	(	qsc_chacha_poly1305_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Encrypt data using the ChaCha-Poly1305 authenticated encryption mode.

In encryption mode, this function encrypts the plaintext using ChaCha20, computes a MAC over the ciphertext, and appends the MAC to the output.

Parameters

ctx	[struct] Pointer to an initialized qsc_chacha_poly1305_state structure.
output	[uint8_t*] Pointer to the output buffer, must be large enough to hold ciphertext plus MAC.
input	[const uint8_t*] Pointer to the input data; ciphertext with appended MAC.
length	[size_t] Length of the input data in bytes (excluding the MAC for decryption).

See also

qsc_chacha_poly1305_initialize, qsc_chacha_poly1305_set_associated

qsc_chacha_poly1305_initialize()

QSC_EXPORT_API void qsc_chacha_poly1305_initialize	(	qsc_chacha_poly1305_state *	ctx,
		const qsc_chacha_keyparams *	keyparams )

Initialize the ChaCha-Poly1305 state for authenticated encryption or decryption.

Generates the cipher key and MAC key from the provided key parameters and sets up the internal states.

Parameters

ctx	[struct] Pointer to a qsc_chacha_poly1305_state structure to initialize.
keyparams	[const struct] Pointer to a constant qsc_chacha_keyparams structure that provides the key.

Warning

Must be called before using qsc_chacha_poly1305_set_associated, qsc_chacha_poly1305_encrypt or qsc_chacha_poly1305_decrypt.

See also

qsc_chacha_poly1305_decrypt, qsc_chacha_poly1305_encrypt, qsc_chacha_poly1305_dispose

qsc_chacha_poly1305_set_associated()

QSC_EXPORT_API void qsc_chacha_poly1305_set_associated	(	qsc_chacha_poly1305_state *	ctx,
		const uint8_t *	data,
		size_t	datalen )

Set the associated data (AAD) for ChaCha-Poly1305 authenticated encryption.

The associated data is used to authenticate additional information (such as headers) that is not encrypted. It must be set after initialization and before each call to qsc_chacha_poly1305_encrypt

Parameters

ctx	[struct] Pointer to the qsc_chacha_poly1305_state structure.
data	[const uint8_t*] Pointer to the associated data.
datalen	[size_t] Length of the associated data in bytes.

See also

qsc_chacha_poly1305_encrypt

qsc_chacha_transform()

QSC_EXPORT_API void qsc_chacha_transform	(	qsc_chacha_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Process a block of input data using the ChaCha20 cipher.

Encrypts (or decrypts) the input data using the ChaCha20 stream cipher. Since ChaCha20 is a stream cipher, the same function is used for both encryption and decryption.

Parameters

ctx	[qsc_chacha_state*] Pointer to the ChaCha20 state structure.
output	[uint8_t*] Pointer to the output byte array.
input	[const uint8_t*] Pointer to the input byte array.
length	[size_t] The number of bytes to process.