rcs.h File Reference

Rijndael-256 authenticated Cipher Stream. More...

#include "common.h"
#include "sha3.h"
#include "qmac.h"

Go to the source code of this file.

Data Structures
struct	qsc_rcs_keyparams
	The key parameters structure containing key, nonce, and info arrays and lengths. More...
struct	qsc_rcs_state
	The internal state structure containing the round-key array. More...

Macros
#define	QSC_RCS_AUTHENTICATED
	Enables the AEAD cipher authentication mode.
#define	QSC_RCS_AUTH_QMAC
	Enables the reduced rounds QMAC implementation.
#define	QSC_RCS_BLOCK_SIZE   32ULL
	The internal block size in bytes, required by the encryption and decryption functions.
#define	QSC_RCS256_KEY_SIZE   32ULL
	The size in bytes of the RCS-256 input cipher-key.
#define	QSC_RCS256_MAC_SIZE   32ULL
	The RCS-256 MAC code array length in bytes.
#define	QSC_RCS512_KEY_SIZE   64ULL
	The size in bytes of the RCS-512 input cipher-key.
#define	QSC_RCS512_MAC_SIZE   32ULL
	The RCS-512 MAC code array length in bytes.
#define	QSC_RCS_NONCE_SIZE   32ULL
	The nonce size in bytes.

Enumerations
enum	rcs_cipher_type { RCS256 = 0x01 , RCS512 = 0x02 }
	The pre-defined cipher mode implementations. More...

Functions
QSC_EXPORT_API void	qsc_rcs_dispose (qsc_rcs_state *ctx)
	Dispose of the RCS cipher state.
QSC_EXPORT_API void	qsc_rcs_initialize (qsc_rcs_state *ctx, const qsc_rcs_keyparams *keyparams, bool encryption)
	Initialize the state with the input cipher-key and optional info tweak.
QSC_EXPORT_API void	qsc_rcs_set_associated (qsc_rcs_state *ctx, const uint8_t *data, size_t length)
	Set the associated data string used in authenticating the message.
QSC_EXPORT_API void	qsc_rcs_store_nonce (const qsc_rcs_state *ctx, uint8_t nonce[QSC_RCS_NONCE_SIZE])
	Retrieves the current nonce from the state.
QSC_EXPORT_API bool	qsc_rcs_transform (qsc_rcs_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Transform an array of bytes.
QSC_EXPORT_API bool	qsc_rcs_extended_transform (qsc_rcs_state *ctx, uint8_t *output, const uint8_t *input, size_t length, bool finalize)
	A multi-call transform for a large array of bytes.

Detailed Description

Rijndael-256 authenticated Cipher Stream.

This header defines the API for the RCS (Rijndael-256 authenticated Cipher Stream) encryption functions. RCS is a hybrid cipher that combines a wide-block Rijndael-256 rounds function with a cryptographically strong pseudo-random generator (cSHAKE) to expand the round-key array (key-schedule). The cryptographic XOF (cSHAKE) generates the round key array used by the modified Rijndael rounds function, enabling a higher number of mixing rounds:

• RCS-256 uses 22 rounds (compared to 14 in standard AES-256).
• RCS-512 employs 30 rounds with a 512-bit key configuration.

The cipher supports authenticated encryption with associated data (AEAD) by integrating a keyed MAC function (KMAC or QMAC) that appends an authentication code to the ciphertext. It also supports a tweakable configuration by allowing a user-specified info parameter to customize the cSHAKE output, which can be used as a secondary key or domain separator.

// RCS-256 encryption example:
#define CSTLEN 20
#define MSGLEN 200
uint8_t cust[CSTLEN] = { ... };
uint8_t key[QSC_RCS256_KEY_SIZE] = { ... };
uint8_t msg[MSGLEN] = { ... };
uint8_t nonce[QSC_RCS_BLOCK_SIZE] = { ... };
uint8_t cpt[MSGLEN + QSC_RCS256_MAC_SIZE] = { 0 };
qsc_rcs_state state;
qsc_rcs_keyparams kp = { key, QSC_RCS256_KEY_SIZE, nonce, cust, CSTLEN };
 
qsc_rcs_initialize(&state, &kp, true);
qsc_rcs_transform(&state, cpt, msg, MSGLEN);
 
// RCS-256 decryption example:
uint8_t cpt[CPTLEN] = { qsc_rcs_transform(state, in) };
uint8_t key[QSC_RCS256_KEY_SIZE] = { ... };
uint8_t nonce[QSC_RCS_BLOCK_SIZE] = { ... };
uint8_t cust[CSTLEN] = { ... };
const size_t MSGLEN = CPTLEN - QSC_RCS256_MAC_SIZE;
uint8_t msg[MSGLEN] = { 0 };
qsc_rcs_keyparams kp = { key, QSC_RCS256_KEY_SIZE, nonce, cust, CSTLEN };
 
qsc_rcs_initialize(&state, &kp, false);
if (qsc_rcs_transform(&state, msg, cpt, MSGLEN) == false)
{
    // Authentication has failed, handle error...
}

Reference Links:

• Rijndael Specification (NIST FIPS 197)
• SHA3 Specification (FIPS 202)

Enumeration Type Documentation

rcs_cipher_type

enum rcs_cipher_type

The pre-defined cipher mode implementations.

Enumerator
RCS256	The RCS-256 cipher
RCS512	The RCS-512 cipher

Function Documentation

qsc_rcs_dispose()

QSC_EXPORT_API void qsc_rcs_dispose

(

qsc_rcs_state *

ctx

)

Dispose of the RCS 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	[qsc_rcs_state*] A pointer to the cipher state structure.

qsc_rcs_extended_transform()

QSC_EXPORT_API bool qsc_rcs_extended_transform	(	qsc_rcs_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length,
		bool	finalize )

A multi-call transform for a large array of bytes.

This function can be used to transform and authenticate a very large array of bytes (e.g., >1GB). On the last call in the sequence, set the finalize parameter to true to complete authentication. In encryption mode, the plain-text is encrypted and the MAC code is appended. In decryption mode, the cipher-text is authenticated; if the MAC codes do not match, the call fails.

Parameters

ctx	[qsc_rcs_state*] A pointer to the cipher state structure.
output	[uint8_t*] A pointer to the output array.
input	[const uint8_t*] A pointer to the input array.
length	[size_t] The number of bytes to transform.
finalize	[bool] A flag to indicate if this is the final call.

Returns

[bool] Returns true if the data was transformed successfully, false on failure.

qsc_rcs_initialize()

QSC_EXPORT_API void qsc_rcs_initialize	(	qsc_rcs_state *	ctx,
		const qsc_rcs_keyparams *	keyparams,
		bool	encryption )

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

Parameters

ctx	[qsc_rcs_state*] A pointer to the cipher state structure.
keyparams	[const qsc_rcs_state*] A pointer to the secret input cipher-key and nonce structure.
encryption	[bool] A flag that specifies true for encryption, false for decryption.

qsc_rcs_set_associated()

QSC_EXPORT_API void qsc_rcs_set_associated	(	qsc_rcs_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.

Parameters

ctx	[qsc_rcs_state*] A pointer to the cipher state structure.
data	[const uint8_t*] A pointer to the associated data array.
length	[size_t] The associated data array length.

qsc_rcs_store_nonce()

QSC_EXPORT_API void qsc_rcs_store_nonce	(	const qsc_rcs_state *	ctx,
		uint8_t	nonce[QSC_RCS_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_rcs_transform()

QSC_EXPORT_API bool qsc_rcs_transform	(	qsc_rcs_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 an authentication MAC code is appended to the cipher-text. In decryption mode, the input cipher-text is authenticated and compared to the MAC code. If the codes do not match, the cipher-text is not decrypted and the call fails.

Parameters

ctx	[qsc_rcs_state*] A pointer to the cipher state structure.
output	[uint8_t*] A pointer to the output array.
input	[const uint8_t*] A pointer to the input array.
length	[size_t] The number of bytes to transform.

Returns

[bool] Returns true if the data was transformed successfully, false on failure.