csx.h File Reference

ChaCha-based authenticated Stream cipher eXtension. More...

#include "qsccommon.h"
#include "sha3.h"

Go to the source code of this file.

Data Structures
struct	qsc_csx_keyparams
	The key parameters structure containing key, nonce, and info arrays and lengths. Use this structure to load an input cipher-key and optional info tweak, using the qsc_csx_initialize function. Keys must be random and secret, and align to the corresponding key size of the cipher implemented. The info parameter is optional, and can be a salt or cryptographic key. The nonce is always QSC_CSX_NONCE_SIZE in length. More...
struct	qsc_csx_state
	The internal state structure containing the round-key array. More...

Macros
#define	QSC_CSX_AUTHENTICATED
	Enables KMAC authentication mode.
#define	QSC_CSX_BLOCK_SIZE   128U
	The internal block size in bytes, required by the encryption and decryption functions.
#define	QSC_CSX_INFO_SIZE   48U
	The maximum byte length of the info string.
#define	QSC_CSX_KEY_SIZE   64U
	The size in bytes of the CSX-512 input cipher-key.
#define	QSC_CSX_MAC_SIZE   64U
	The CSX-512 MAC code array length in bytes.
#define	QSC_CSX_NONCE_SIZE   16U
	The byte size of the nonce array.
#define	QSC_CSX_STATE_SIZE   16U
	The uint64 size of the internal state array.

Functions
QSC_EXPORT_API void	qsc_csx_dispose (qsc_csx_state *ctx)
	Dispose of the CSX cipher state.
QSC_EXPORT_API void	qsc_csx_initialize (qsc_csx_state *ctx, const qsc_csx_keyparams *keyparams, bool encryption)
	Initialize the state with the input cipher-key and optional info tweak.
QSC_EXPORT_API void	qsc_csx_set_associated (qsc_csx_state *ctx, const uint8_t *data, size_t length)
	Set the associated data string used in authenticating the message. The associated data may be packet header information, domain specific data, or a secret shared by a group. The associated data must be set after initialization, and before each transformation call. The data is erased after each call to the transform.
QSC_EXPORT_API void	qsc_csx_store_nonce (const qsc_csx_state *ctx, uint8_t nonce[QSC_CSX_NONCE_SIZE])
	Retrieves the current nonce from the state.
QSC_EXPORT_API bool	qsc_csx_transform (qsc_csx_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Transform an array of bytes. In encryption mode, the input plain-text is encrypted and then an authentication MAC code is appended to the cipher-text. In decryption mode, the input cipher-text is authenticated internally and compared to the MAC code appended to the cipher-text, if the codes to not match, the cipher-text is not decrypted and the call fails.
QSC_EXPORT_API bool	qsc_csx_extended_transform (qsc_csx_state *ctx, uint8_t *output, const uint8_t *input, size_t length, bool finalize)
	A multi-call transform for a large array of bytes, such as required by file encryption. This call can be used to transform and authenticate a very large array of bytes (+1GB). On the last call in the sequence, set the finalize parameter to true to complete authentication, and write the MAC code to the end of the output array in encryption mode, or compare to the embedded MAC code and authenticate in decryption mode. In encryption mode, the input plain-text is encrypted, then authenticated, and the MAC code is appended to the cipher-text. In decryption mode, the input cipher-text is authenticated internally and compared to the MAC code appended to the cipher-text, if the codes do not match, the cipher-text is not decrypted and the call fails.

Detailed Description

ChaCha-based authenticated Stream cipher eXtension.

This header defines the public API for the CSX-512 cipher, a wide-block ChaCha-based authenticated stream cipher extension. CSX-512 is a vectorized, 64-bit, 40-round stream cipher that uses a 512-bit input key, a 16-byte nonce, and an optional tweak (info) parameter. The cipher employs the Keccak cSHAKE-512 extended output function (XOF) to expand the input cipher-key into both the cipher key and the MAC key. It integrates a post-quantum secure MAC function (KMAC) for message authentication, operating in an encrypt-then-MAC configuration to provide authenticated encryption with associated data (AEAD). In decryption mode, the MAC code embedded in the ciphertext is verified prior to decryption, ensuring data integrity and authenticity.

Example Usage:

// External message, key, nonce, and custom-info arrays
#define CSTLEN 20
#define MSGLEN 200
uint8_t cust[CSTLEN] = { ... };
uint8_t key[QSC_CSX_KEY_SIZE] = { ... };
uint8_t msg[MSGLEN] = { ... };
uint8_t nonce[QSC_CSX_NONCE_SIZE] = { ... };
uint8_t cpt[MSGLEN + QSC_CSX_MAC_SIZE] = { 0U };
qsc_csx_state state;
qsc_csx_keyparams kp = { key, QSC_CSX_KEY_SIZE, nonce, cust, CSTLEN };
 
// Initialize the state for encryption
qsc_csx_initialize(&state, &kp, true);
// Encrypt the message
qsc_csx_transform(&state, cpt, msg, MSGLEN);

Reference Links:

• Official ChaCha20 Specification
• NIST FIPS 202 (SHA-3) Standard
• Galois Field Theory Reference

Function Documentation

qsc_csx_dispose()

QSC_EXPORT_API void qsc_csx_dispose

(

qsc_csx_state *

ctx

)

Dispose of the CSX cipher state.

Warning

The dispose function must be called when disposing of the cipher. This function destroys the internal state of the cipher.

Parameters

ctx	[struct] The cipher state structure

qsc_csx_extended_transform()

QSC_EXPORT_API bool qsc_csx_extended_transform	(	qsc_csx_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length,
		bool	finalize )

A multi-call transform for a large array of bytes, such as required by file encryption. This call can be used to transform and authenticate a very large array of bytes (+1GB). On the last call in the sequence, set the finalize parameter to true to complete authentication, and write the MAC code to the end of the output array in encryption mode, or compare to the embedded MAC code and authenticate in decryption mode. In encryption mode, the input plain-text is encrypted, then authenticated, and the MAC code is appended to the cipher-text. In decryption mode, the input cipher-text is authenticated internally and compared to the MAC code appended to the cipher-text, if the codes do not match, the cipher-text is not decrypted and the call fails.

Warning

The cipher must be initialized before this function can be called

Parameters

ctx	[struct] The cipher state structure
output	[uint8_t*] A pointer to the output array
input	[const] A pointer to the input array
length	[size_t] The number of bytes to transform
finalize	[bool] Complete authentication on a stream if set to true

Returns

: [bool] Returns true if the cipher has been transformed the data successfully, false on failure

qsc_csx_initialize()

QSC_EXPORT_API void qsc_csx_initialize	(	qsc_csx_state *	ctx,
		const qsc_csx_keyparams *	keyparams,
		bool	encryption )

Initialize the state with the input cipher-key and optional info tweak.

Warning

When using a CTR based construction the nonce must be unique for a given key. Re-using a nonce-key pair on a different plaintext input represents a catastrophic loss of security.

Parameters

ctx	[struct] The cipher state structure
keyparams	[const struct] The secret input cipher-key and nonce structure
encryption	[bool] Initialize the cipher for encryption, or false for decryption mode

qsc_csx_set_associated()

QSC_EXPORT_API void qsc_csx_set_associated	(	qsc_csx_state *	ctx,
		const uint8_t *	data,
		size_t	length )

Set the associated data string used in authenticating the message. The associated data may be packet header information, domain specific data, or a secret shared by a group. The associated data must be set after initialization, and before each transformation call. The data is erased after each call to the transform.

Warning

The cipher must be initialized before this function can be called

Parameters

ctx	[struct] The cipher state structure
data	[const] The associated data array
length	[size_t] The associated data array length

qsc_csx_store_nonce()

QSC_EXPORT_API void qsc_csx_store_nonce	(	const qsc_csx_state *	ctx,
		uint8_t	nonce[QSC_CSX_NONCE_SIZE] )

Retrieves the current nonce from the state.

Warning

If reusing a nonce/key, the nonce must be retrieved after the last finalized transform call.

Parameters

ctx	[struct] The cipher state structure
nonce	[uint8_t*] The output nonce array

qsc_csx_transform()

QSC_EXPORT_API bool qsc_csx_transform	(	qsc_csx_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Transform an array of bytes. In encryption mode, the input plain-text is encrypted and then an authentication MAC code is appended to the cipher-text. In decryption mode, the input cipher-text is authenticated internally and compared to the MAC code appended to the cipher-text, if the codes to not match, the cipher-text is not decrypted and the call fails.

Warning

The cipher must be initialized before this function can be called

Parameters

ctx	[struct] The cipher state structure.
output	[uint8_t*] A pointer to the output array.
input	[const] A pointer to the input array.
length	[size_t] The number of bytes to transform (not including the tag length).

Returns

: [bool] Returns true if the cipher has been transformed the data successfully, false on failure