aes.h File Reference

An implementation of the AES symmetric cipher along with modes and an AEAD scheme. More...

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

Go to the source code of this file.

Data Structures
struct	qsc_aes_keyparams
	Structure for AES key parameters. More...
struct	qsc_aes_state
	AES cipher ctx structure. More...
struct	qsc_aes_hba256_state
	State structure for AES-based Hash Based Authentication (HBA-256). More...
struct	qsc_aes_gcm128_state
	State structure for AES-based Galois Counter Mode (GCM-128). More...
struct	qsc_aes_gcm256_state
	State structure for AES-based Galois Counter Mode (GCM-256). More...

Macros
#define	QSC_HBA_KMAC_EXTENSION
	Enables the cSHAKE/KMAC extensions for the HBA cipher mode.
#define	QSC_HBA_HKDF_EXTENSION
	Enables the HKDF extensions for the HBA cipher mode as an alternative to the cSHAKE mode.
#define	QSC_AES_BLOCK_SIZE   16U
	Internal AES block size in bytes.
#define	QSC_AES_IV_SIZE   16U
	Initialization vector (IV) size in bytes.
#define	QSC_AES128_KEY_SIZE   16U
	Key size in bytes for AES-128.
#define	QSC_AES256_KEY_SIZE   32U
	Key size in bytes for AES-256.
#define	QSC_GCM128_MAC_SIZE   16U
	Size in bytes of the MAC tag produced by GCM-AES-128.
#define	QSC_GCM256_MAC_SIZE   16U
	Size in bytes of the MAC code for GCM-AES-256.
#define	QSC_GCM_MAXAAD_SIZE   65536U
	Maximum allowed size (in bytes) for Associated Additional Data (AAD) in GCM.
#define	QSC_GCM_NONCE_SIZE   12U
	The standard nonce size used by GCM-AES-256.
#define	QSC_GCM_MAX_NONCE_SIZE   32U
#define	QSC_HBA256_MAC_SIZE   32U
	Size in bytes of the MAC code for HBA-256.
#define	QSC_HBA_MAXAAD_SIZE   256U
	Maximum allowed size (in bytes) for Associated Additional Data (AAD) in HBA.
#define	QSC_HBA_MAXINFO_SIZE   256U
	Maximum allowed size (in bytes) for key information tweaks in HBA.
#define	QSC_HBA_KMAC_AUTH
	When defined, enables the use of KMAC for authenticating HBA.

Typedefs
typedef QSC_EXPORT_API struct qsc_aes_gcm128_state	qsc_aes_gcm128_state
typedef QSC_EXPORT_API struct qsc_aes_gcm256_state	qsc_aes_gcm256_state

Enumerations
enum	qsc_aes_cipher_type { qsc_aes_cipher_128 = 0x01U , qsc_aes_cipher_256 = 0x02U }
	Pre-defined cipher key sizes for AES. More...
enum	qsc_aes_cipher_mode { qsc_aes_mode_cbc = 0x01U , qsc_aes_mode_ctr = 0x02U , qsc_aes_mode_ecb = 0x03U }
	Pre-defined AES cipher mode implementations. More...

Functions
QSC_EXPORT_API void	qsc_aes_dispose (qsc_aes_state *ctx)
	Erase and dispose of the AES ctx.
QSC_EXPORT_API void	qsc_aes_initialize (qsc_aes_state *ctx, const qsc_aes_keyparams *keyparams, bool encryption, qsc_aes_cipher_type ctype)
	Initialize the AES ctx with the given key parameters.
QSC_EXPORT_API void	qsc_aes_cbc_decrypt (qsc_aes_state *ctx, uint8_t *output, size_t *outputlen, const uint8_t *input, size_t length)
	Decrypt ciphertext using AES in Cipher Block Chaining (CBC) mode.
QSC_EXPORT_API void	qsc_aes_cbc_encrypt (qsc_aes_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Encrypt plaintext using AES in Cipher Block Chaining (CBC) mode.
QSC_EXPORT_API void	qsc_aes_cbc_decrypt_block (qsc_aes_state *ctx, uint8_t *output, const uint8_t *input)
	Decrypt a single 16-byte block using AES in CBC mode.
QSC_EXPORT_API void	qsc_aes_cbc_encrypt_block (qsc_aes_state *ctx, uint8_t *output, const uint8_t *input)
	Encrypt a single 16-byte block using AES in CBC mode.
QSC_EXPORT_API void	qsc_pkcs7_add_padding (uint8_t *input, size_t length)
	Add PKCS#7 padding to a plaintext block.
QSC_EXPORT_API size_t	qsc_pkcs7_padding_length (const uint8_t *input)
	Determine the length of PKCS#7 padding in a decrypted block.
QSC_EXPORT_API void	qsc_aes_ctrbe_transform (qsc_aes_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Transform data using AES in Counter (CTR) mode with Big Endian counter incrementation.
QSC_EXPORT_API void	qsc_aes_ctrle_transform (qsc_aes_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Transform data using AES in Counter (CTR) mode with Little Endian counter incrementation.
QSC_EXPORT_API void	qsc_aes_ecb_decrypt_block (const qsc_aes_state *ctx, uint8_t *output, const uint8_t *input)
	Decrypt a single 16-byte block using AES in Electronic CodeBook (ECB) mode.
QSC_EXPORT_API void	qsc_aes_ecb_encrypt_block (const qsc_aes_state *ctx, uint8_t *output, const uint8_t *input)
	Encrypt a single 16-byte block using AES in Electronic CodeBook (ECB) mode.
QSC_EXPORT_API void	qsc_aes_hba256_dispose (qsc_aes_hba256_state *ctx)
	Dispose of an HBA-256 ctx.
QSC_EXPORT_API void	qsc_aes_hba256_initialize (qsc_aes_hba256_state *ctx, const qsc_aes_keyparams *keyparams, bool encrypt)
	Initialize the HBA-256 ctx for authenticated encryption or decryption.
QSC_EXPORT_API void	qsc_aes_hba256_set_associated (qsc_aes_hba256_state *ctx, const uint8_t *data, size_t datalen)
	Set the associated data (AAD) for HBA-256 authenticated encryption.
QSC_EXPORT_API bool	qsc_aes_hba256_transform (qsc_aes_hba256_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Transform data using the HBA-256 authenticated encryption mode.
QSC_EXPORT_API bool	qsc_aes_gcm128_decrypt (qsc_aes_gcm128_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Decrypt ciphertext and verify the authentication tag using GCM-AES-128.
QSC_EXPORT_API void	qsc_aes_gcm128_dispose (qsc_aes_gcm128_state *ctx)
	Dispose of a GCM-128 context.
QSC_EXPORT_API void	qsc_aes_gcm128_encrypt (qsc_aes_gcm128_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Encrypt plaintext and append an authentication tag using GCM-AES-128.
QSC_EXPORT_API void	qsc_aes_gcm128_initialize (qsc_aes_gcm128_state *ctx, const qsc_aes_keyparams *keyparams, bool encryption)
	Initialize the GCM-128 context for authenticated encryption or decryption.
QSC_EXPORT_API void	qsc_aes_gcm128_set_associated (qsc_aes_gcm128_state *ctx, const uint8_t *data, size_t datalen)
	Supply associated additional data (AAD) to GCM-128.
QSC_EXPORT_API bool	qsc_aes_gcm128_transform (qsc_aes_gcm128_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Unified GCM-128 encrypt-or-decrypt transform.
QSC_EXPORT_API bool	qsc_aes_gcm256_decrypt (qsc_aes_gcm256_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Decrypt ciphertext and verify the authentication tag using GCM-AES-256.
QSC_EXPORT_API void	qsc_aes_gcm256_dispose (qsc_aes_gcm256_state *ctx)
	Dispose of an GCM-256 ctx.
QSC_EXPORT_API void	qsc_aes_gcm256_encrypt (qsc_aes_gcm256_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Encrypt data using the GCM-AES-256 authenticated encryption mode.
QSC_EXPORT_API void	qsc_aes_gcm256_initialize (qsc_aes_gcm256_state *ctx, const qsc_aes_keyparams *keyparams, bool encryption)
	Initialize the GCM-256 ctx for authenticated encryption or decryption.
QSC_EXPORT_API void	qsc_aes_gcm256_set_associated (qsc_aes_gcm256_state *ctx, const uint8_t *data, size_t datalen)
	Set the associated data (AAD) for GCM-256 authenticated encryption.
QSC_EXPORT_API bool	qsc_aes_gcm256_transform (qsc_aes_gcm256_state *ctx, uint8_t *output, const uint8_t *input, size_t length)
	Transform an array of bytes.

Detailed Description

An implementation of the AES symmetric cipher along with modes and an AEAD scheme.

This header provides the interface for an implementation of the AES block cipher. Supported features include:

• AES-128 and AES-256 key sizes.
• Multiple cipher modes: Cipher Block Chaining (CBC), Counter (CTR) with both Big Endian and Little Endian counter increments, and Electronic Code Book (ECB).
• PKCS#7 padding for block alignment.
• A Hash-Based Authenticated (HBA-256) mode for authenticated encryption using AES-256.

The HBA-256 mode supports both cSHAKE-based (via KMAC) and HKDF-based authentication. See QSC_HBA_KMAC_EXTENSION and QSC_HBA_HKDF_EXTENSION for details on enabling each mode.

Example Usage (AES-256 CTR mode):

#include "aes.h"
 
const size_t MSG_LEN = 200;
const size_t CST_LEN = 20;
uint8_t msg[MSG_LEN] = { 0U };
uint8_t key[QSC_AES256_KEY_SIZE] = { 0U };
uint8_t nonce[QSC_AES_BLOCK_SIZE] = { 0U };
uint8_t cust[CST_LEN] = { 0U };
 
uint8_t output[MSG_LEN] = { 0U };
qsc_aes_keyparams kp = { .key = key, .keylen = QSC_AES256_KEY_SIZE, .nonce = nonce, .noncelen = QSC_AES_BLOCK_SIZE, .info = cust, .infolen = CST_LEN };
 
qsc_aes_state ctx;
qsc_aes_initialize(&ctx, &kp, true, qsc_aes_cipher_256);
qsc_aes_ctrbe_transform(&ctx, output, msg, MSG_LEN);

See also

qsc_aes_initialize, qsc_aes_dispose, qsc_aes_cbc_encrypt, qsc_aes_ctrbe_transform, qsc_aes_hba256_initialize

Reference Links

• AES Specification NIST FIPS 197
• CBC and CTR Mode (NIST SP 800-38A)
• SHA3 Implementation NIST FIPS 202

Macro Definition Documentation

QSC_AES_BLOCK_SIZE

#define QSC_AES_BLOCK_SIZE   16U

Internal AES block size in bytes.

All AES operations use a fixed block size of 16 bytes.

QSC_AES_IV_SIZE

#define QSC_AES_IV_SIZE   16U

Initialization vector (IV) size in bytes.

The IV (or nonce) size is equal to the block size.

QSC_GCM_NONCE_SIZE

#define QSC_GCM_NONCE_SIZE   12U

The standard nonce size used by GCM-AES-256.

Maximum GCM IV length accepted by initialize function. Nonces longer than 32 bytes serve no cryptographic purpose and protect against accidental runaway in the GHASH IV derivation loop.

QSC_HBA_HKDF_EXTENSION

#define QSC_HBA_HKDF_EXTENSION

Enables the HKDF extensions for the HBA cipher mode as an alternative to the cSHAKE mode.

When defined (and if QSC_HBA_KMAC_EXTENSION is not defined), HMAC(SHA2) is used by default.

QSC_HBA_KMAC_AUTH

#define QSC_HBA_KMAC_AUTH

When defined, enables the use of KMAC for authenticating HBA.

If QSC_HBA_KMAC_EXTENSION is disabled, HMAC (SHA2) is used by default.

QSC_HBA_KMAC_EXTENSION

#define QSC_HBA_KMAC_EXTENSION

Enables the cSHAKE/KMAC extensions for the HBA cipher mode.

When defined, the HBA-256 mode uses cSHAKE/KMAC for message authentication.

Enumeration Type Documentation

qsc_aes_cipher_mode

enum qsc_aes_cipher_mode

Pre-defined AES cipher mode implementations.

Modes include CBC (Cipher Block Chaining), CTR (Counter mode), and ECB (Electronic Code Book). Note: ECB mode is considered insecure and should only be used for testing or as a building block.

Enumerator
qsc_aes_mode_cbc	Cipher Block Chaining (CBC) mode
qsc_aes_mode_ctr	Counter (CTR) mode using a segmented integer counter
qsc_aes_mode_ecb	Electronic CodeBook (ECB) mode (insecure)

qsc_aes_cipher_type

enum qsc_aes_cipher_type

Pre-defined cipher key sizes for AES.

The enumeration lists supported AES cipher types.

Enumerator
qsc_aes_cipher_128	AES-128 block cipher (128-bit key)
qsc_aes_cipher_256	AES-256 block cipher (256-bit key)

Function Documentation

qsc_aes_cbc_decrypt()

QSC_EXPORT_API void qsc_aes_cbc_decrypt	(	qsc_aes_state *	ctx,
		uint8_t *	output,
		size_t *	outputlen,
		const uint8_t *	input,
		size_t	length )

Decrypt ciphertext using AES in Cipher Block Chaining (CBC) mode.

Decrypts the input data in CBC mode and removes PKCS#7 padding.

Parameters

ctx	[struct] Pointer to an initialized qsc_aes_state structure.
output	[uint8_t*] Pointer to the output buffer where plaintext will be stored.
outputlen	[size_t*] Pointer to a size_t that receives the length of the decrypted data.
input	[const uint8_t*] Pointer to the input ciphertext.
length	[size_t] Number of bytes of input ciphertext.

Warning

The ctx must be initialized by qsc_aes_initialize.

See also

qsc_aes_cbc_encrypt, qsc_pkcs7_padding_length

qsc_aes_cbc_decrypt_block()

QSC_EXPORT_API void qsc_aes_cbc_decrypt_block	(	qsc_aes_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input )

Decrypt a single 16-byte block using AES in CBC mode.

Decrypts one block of ciphertext and performs the XOR with the previous ciphertext block (or IV).

Parameters

ctx	[struct] Pointer to an initialized qsc_aes_state structure.
output	[uint8_t*] Pointer to a 16-byte buffer to receive the decrypted block.
input	[const uint8_t*] Pointer to a 16-byte block of ciphertext.

Warning

The ctx must be initialized by qsc_aes_initialize.

qsc_aes_cbc_encrypt()

QSC_EXPORT_API void qsc_aes_cbc_encrypt	(	qsc_aes_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Encrypt plaintext using AES in Cipher Block Chaining (CBC) mode.

Encrypts the input data in CBC mode, automatically applying PKCS#7 padding to the final block.

Parameters

ctx	[struct] Pointer to an initialized qsc_aes_state structure.
output	[uint8_t*] Pointer to the output buffer where ciphertext will be stored.
input	[const uint8_t*] Pointer to the input plaintext.
length	[size_t] Number of bytes of input plaintext.

Warning

The ctx must be initialized by qsc_aes_initialize.

See also

qsc_aes_cbc_decrypt, qsc_pkcs7_add_padding

qsc_aes_cbc_encrypt_block()

QSC_EXPORT_API void qsc_aes_cbc_encrypt_block	(	qsc_aes_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input )

Encrypt a single 16-byte block using AES in CBC mode.

Encrypts one block of plaintext by XOR-ing with the previous ciphertext block (or IV) and applying AES encryption.

Parameters

ctx	[struct] Pointer to an initialized qsc_aes_state structure.
output	[uint8_t*] Pointer to a 16-byte buffer to receive the ciphertext block.
input	[const uint8_t*] Pointer to a 16-byte block of plaintext.

Warning

The ctx must be initialized by qsc_aes_initialize.

qsc_aes_ctrbe_transform()

QSC_EXPORT_API void qsc_aes_ctrbe_transform	(	qsc_aes_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Transform data using AES in Counter (CTR) mode with Big Endian counter incrementation.

Encrypts or decrypts data in CTR mode. The same function is used for both operations.

Parameters

ctx	[struct] Pointer to an initialized qsc_aes_state structure.
output	[uint8_t*] Pointer to the buffer where the transformed data will be stored.
input	[const uint8_t*] Pointer to the input data.
length	[size_t] Number of bytes to process.

Warning

The ctx must be initialized by qsc_aes_initialize.

See also

qsc_aes_ctrle_transform

qsc_aes_ctrle_transform()

QSC_EXPORT_API void qsc_aes_ctrle_transform	(	qsc_aes_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Transform data using AES in Counter (CTR) mode with Little Endian counter incrementation.

Encrypts or decrypts data in CTR mode using a little endian counter.

Parameters

ctx	[struct] Pointer to an initialized qsc_aes_state structure.
output	[uint8_t*] Pointer to the buffer where the transformed data will be stored.
input	[const uint8_t*] Pointer to the input data.
length	[size_t] Number of bytes to process.

Warning

The ctx must be initialized by qsc_aes_initialize.

See also

qsc_aes_ctrbe_transform

qsc_aes_dispose()

QSC_EXPORT_API void qsc_aes_dispose

(

qsc_aes_state *

ctx

)

Erase and dispose of the AES ctx.

Securely clears the round-key array and resets the key length.

Parameters

ctx	[struct] Pointer to a qsc_aes_state structure.

See also

qsc_aes_initialize

qsc_aes_ecb_decrypt_block()

QSC_EXPORT_API void qsc_aes_ecb_decrypt_block	(	const qsc_aes_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input )

Decrypt a single 16-byte block using AES in Electronic CodeBook (ECB) mode.

ECB mode should only be used for testing or as a building block due to its inherent insecurity.

Parameters

ctx	[const struct] Pointer to an initialized qsc_aes_state structure.
output	[uint8_t*] Pointer to a 16-byte buffer to receive the decrypted plaintext.
input	[const uint8_t*] Pointer to a 16-byte ciphertext block.

Warning

ECB mode does not provide semantic security.

qsc_aes_ecb_encrypt_block()

QSC_EXPORT_API void qsc_aes_ecb_encrypt_block	(	const qsc_aes_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input )

Encrypt a single 16-byte block using AES in Electronic CodeBook (ECB) mode.

Parameters

ctx	[const struct] Pointer to an initialized qsc_aes_state structure.
output	[uint8_t*] Pointer to a 16-byte buffer to receive the ciphertext.
input	[const uint8_t*] Pointer to a 16-byte plaintext block.

Warning

ECB mode is insecure and should be used only for testing.

qsc_aes_gcm128_decrypt()

QSC_EXPORT_API bool qsc_aes_gcm128_decrypt	(	qsc_aes_gcm128_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Decrypt ciphertext and verify the authentication tag using GCM-AES-128.

Authenticates the ciphertext via GHASH, then decrypts it using AES-128 in GCTR mode. The input buffer must contain the raw ciphertext immediately followed by the QSC_GCM128_MAC_SIZE-byte authentication tag. The plaintext is written to output only when authentication succeeds; on failure the output buffer is securely zeroed and the function returns false.

Parameters

ctx	[struct] Pointer to an initialized qsc_aes_gcm128_state structure.
output	[uint8_t*] Pointer to the plaintext output buffer. Must be at least (length - QSC_GCM128_MAC_SIZE) bytes.
input	[const uint8_t*] Pointer to the ciphertext buffer with the appended MAC tag. Length must equal (ciphertext length + QSC_GCM128_MAC_SIZE).
length	[size_t] Total number of bytes in input, including the QSC_GCM128_MAC_SIZE-byte tag.

Returns

[bool] true if authentication and decryption succeeded; false if the tag did not match (output is zeroed).

Warning

The ctx must be initialized via qsc_aes_gcm128_initialize before use.

See also

qsc_aes_gcm128_initialize, qsc_aes_gcm128_set_associated, qsc_aes_gcm128_encrypt, qsc_aes_gcm128_transform

qsc_aes_gcm128_dispose()

QSC_EXPORT_API void qsc_aes_gcm128_dispose

(

qsc_aes_gcm128_state *

ctx

)

Dispose of a GCM-128 context.

Securely erases all key material and internal state held by the context, including the cipher round keys, counter block, GHASH subkey, pre-counter block, and accumulator. Must be called when the context is no longer needed to prevent sensitive data from remaining in memory.

Parameters

ctx	[struct] Pointer to a qsc_aes_gcm128_state structure to dispose.

Warning

Must be called before the context goes out of scope.

See also

qsc_aes_gcm128_initialize

qsc_aes_gcm128_encrypt()

QSC_EXPORT_API void qsc_aes_gcm128_encrypt	(	qsc_aes_gcm128_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Encrypt plaintext and append an authentication tag using GCM-AES-128.

Encrypts length bytes of input using AES-128 in GCTR mode, then computes a GHASH-based authentication tag over the ciphertext (and any previously supplied AAD) and appends the QSC_GCM128_MAC_SIZE-byte tag immediately after the ciphertext in output.

Parameters

ctx	[struct] Pointer to an initialized qsc_aes_gcm128_state structure.
output	[uint8_t*] Pointer to the output buffer. Must be at least (length + QSC_GCM128_MAC_SIZE) bytes.
input	[const uint8_t*] Pointer to the plaintext input buffer.
length	[size_t] Number of plaintext bytes to encrypt (excluding the tag).

Warning

The ctx must be initialized via qsc_aes_gcm128_initialize before use.

The nonce used during initialization must never be reused with the same key; doing so is a catastrophic loss of security.

See also

qsc_aes_gcm128_initialize, qsc_aes_gcm128_set_associated, qsc_aes_gcm128_decrypt, qsc_aes_gcm128_transform

qsc_aes_gcm128_initialize()

QSC_EXPORT_API void qsc_aes_gcm128_initialize	(	qsc_aes_gcm128_state *	ctx,
		const qsc_aes_keyparams *	keyparams,
		bool	encryption )

Initialize the GCM-128 context for authenticated encryption or decryption.

Performs full GCM initialization: expands the 128-bit key into AES round keys, computes the GHASH subkey H = AES(K, 0^128), and derives the pre-counter block J0 from the supplied nonce. When the nonce is exactly 12 bytes it is used directly with a 32-bit counter suffix; any other length is processed through GHASH per the GCM specification.

Parameters

ctx	[struct] Pointer to a qsc_aes_gcm128_state structure to initialize.
keyparams	[const struct] Pointer to a constant qsc_aes_keyparams structure supplying the 128-bit key (keylen == QSC_AES128_KEY_SIZE), the nonce (noncelen in [1, QSC_GCM_MAX_NONCE_SIZE]), and an optional info field (unused by GCM, may be NULL/0).
encryption:[bool]	true to prepare the context for encryption; false for decryption.

Warning

Must be called before qsc_aes_gcm128_set_associated, qsc_aes_gcm128_encrypt, qsc_aes_gcm128_decrypt, or qsc_aes_gcm128_transform.

A nonce must never be reused under the same key.

See also

qsc_aes_gcm128_dispose, qsc_aes_gcm128_encrypt, qsc_aes_gcm128_decrypt

qsc_aes_gcm128_set_associated()

QSC_EXPORT_API void qsc_aes_gcm128_set_associated	(	qsc_aes_gcm128_state *	ctx,
		const uint8_t *	data,
		size_t	datalen )

Supply associated additional data (AAD) to GCM-128.

Feeds datalen bytes of unencrypted associated data into the GHASH accumulator so they are covered by the authentication tag. Must be called after qsc_aes_gcm128_initialize and before qsc_aes_gcm128_encrypt or qsc_aes_gcm128_decrypt. May be called multiple times; each call appends to the running AAD.

Parameters

ctx	[struct] Pointer to an initialized qsc_aes_gcm128_state structure.
data	[const uint8_t*] Pointer to the associated data buffer.
datalen	[size_t] Length of the associated data in bytes. Must not exceed QSC_GCM_MAXAAD_SIZE per call.

Warning

Must be called before any call to qsc_aes_gcm128_encrypt or qsc_aes_gcm128_decrypt.

See also

qsc_aes_gcm128_encrypt, qsc_aes_gcm128_decrypt

qsc_aes_gcm128_transform()

QSC_EXPORT_API bool qsc_aes_gcm128_transform	(	qsc_aes_gcm128_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Unified GCM-128 encrypt-or-decrypt transform.

Dispatches to qsc_aes_gcm128_encrypt or qsc_aes_gcm128_decrypt according to the mode set during initialization.

In encryption mode length is the number of plaintext bytes; the output buffer receives the ciphertext followed by the QSC_GCM128_MAC_SIZE-byte tag and the function returns true.

In decryption mode length is the number of plaintext bytes (i.e. the ciphertext length excluding the tag); the function internally reads (length + QSC_GCM128_MAC_SIZE) bytes from input, verifies the tag, and returns true on success or false on authentication failure (output is securely zeroed on failure).

Parameters

ctx	[struct] Pointer to an initialized qsc_aes_gcm128_state structure.
output	[uint8_t*] Pointer to the output buffer.
input	[const uint8_t*] Pointer to the input buffer.
length	[size_t] Plaintext byte count (see above for per-mode semantics).

Returns

[bool] true on success; false if authentication failed during decryption.

See also

qsc_aes_gcm128_initialize, qsc_aes_gcm128_set_associated, qsc_aes_gcm128_encrypt, qsc_aes_gcm128_decrypt

qsc_aes_gcm256_decrypt()

QSC_EXPORT_API bool qsc_aes_gcm256_decrypt	(	qsc_aes_gcm256_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Decrypt ciphertext and verify the authentication tag using GCM-AES-256.

Authenticates the ciphertext via GHASH, then decrypts it using AES-256 in GCTR mode. The input buffer must contain the raw ciphertext immediately followed by the QSC_GCM256_MAC_SIZE-byte authentication tag. The plaintext is written to output only when authentication succeeds; on failure the output buffer is securely zeroed and the function returns false.

Parameters

ctx	[struct] Pointer to an initialized qsc_aes_gcm256_state.
output	[uint8_t*] Pointer to the plaintext output buffer. * Must be at least (length QSC_GCM256_MAC_SIZE) bytes.
input	[const uint8_t*] Pointer to the ciphertext with appended MAC. Total length must be ciphertext_len QSC_GCM256_MAC_SIZE.
length	[size_t] Total number of bytes in input including the tag.

Returns

[bool] true if authentication and decryption succeeded; false otherwise.

qsc_aes_gcm256_dispose()

QSC_EXPORT_API void qsc_aes_gcm256_dispose

(

qsc_aes_gcm256_state *

ctx

)

Dispose of an GCM-256 ctx.

Securely clears all internal ctx and keys used by the GCM-256 authenticated encryption mode.

Parameters

ctx	[struct] Pointer to a qsc_aes_gcm256_state structure.

Warning

Must be called before the ctx goes out of scope.

See also

qsc_aes_gcm256_set_associated, qsc_aes_gcm_decrypt, qsc_aes_gcm_encrypt, qsc_aes_gcm_initialize

qsc_aes_gcm256_encrypt()

QSC_EXPORT_API void qsc_aes_gcm256_encrypt	(	qsc_aes_gcm256_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Encrypt data using the GCM-AES-256 authenticated encryption mode.

In encryption mode, this function encrypts the plaintext using AES-256 in CTR mode, computes a MAC over the nonce and ciphertext, and appends the MAC to the output.

Parameters

ctx	[struct] Pointer to an initialized qsc_aes_gcm256_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_aes_gcm256_initialize, qsc_aes_gcm256_set_associated

qsc_aes_gcm256_initialize()

QSC_EXPORT_API void qsc_aes_gcm256_initialize	(	qsc_aes_gcm256_state *	ctx,
		const qsc_aes_keyparams *	keyparams,
		bool	encryption )

Initialize the GCM-256 ctx 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_aes_gcm256_state structure to initialize.
keyparams	[const struct] Pointer to a constant qsc_aes_keyparams structure that provides the key, nonce, and optional info.
encryption	[bool] A flag that specifies true for encryption, false for decryption.

Warning

Must be called before using qsc_aes_gcm256_set_associated, qsc_aes_gcm256_encrypt or qsc_aes_gcm256_decrypt.

See also

qsc_aes_gcm256_decrypt, qsc_aes_gcm256_encrypt, qsc_aes_gcm256_dispose

qsc_aes_gcm256_set_associated()

QSC_EXPORT_API void qsc_aes_gcm256_set_associated	(	qsc_aes_gcm256_state *	ctx,
		const uint8_t *	data,
		size_t	datalen )

Set the associated data (AAD) for GCM-256 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_aes_gcm256_encrypt

Parameters

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

See also

qsc_aes_gcm256_encrypt

qsc_aes_gcm256_transform()

QSC_EXPORT_API bool qsc_aes_gcm256_transform	(	qsc_aes_gcm256_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_aes_gcm256_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] Plaintext byte count (see per-mode semantics).

In encryption mode: number of plaintext bytes to encrypt. The output buffer receives ciphertext followed by the QSC_GCM256_MAC_SIZE-byte tag; caller must allocate at least (length + QSC_GCM256_MAC_SIZE) bytes.

In decryption mode: number of plaintext bytes to recover (excluding * the tag). The function reads (length + QSC_GCM256_MAC_SIZE) bytes from input.

Returns

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

qsc_aes_hba256_dispose()

QSC_EXPORT_API void qsc_aes_hba256_dispose

(

qsc_aes_hba256_state *

ctx

)

Dispose of an HBA-256 ctx.

Securely clears all internal ctx and keys used by the HBA-256 authenticated encryption mode.

Parameters

ctx	[struct] Pointer to a qsc_aes_hba256_state structure.

Warning

Must be called before the ctx goes out of scope.

See also

qsc_aes_hba256_initialize, qsc_aes_hba256_transform

qsc_aes_hba256_initialize()

QSC_EXPORT_API void qsc_aes_hba256_initialize	(	qsc_aes_hba256_state *	ctx,
		const qsc_aes_keyparams *	keyparams,
		bool	encrypt )

Initialize the HBA-256 ctx 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_aes_hba256_state structure to initialize.
keyparams	[const struct] Pointer to a constant qsc_aes_keyparams structure that provides the key, nonce, and optional info.
encrypt	[bool] Set to true for encryption mode, or false for decryption mode.

Warning

Must be called before using qsc_aes_hba256_set_associated or qsc_aes_hba256_transform.

See also

qsc_aes_hba256_transform, qsc_aes_hba256_dispose

qsc_aes_hba256_set_associated()

QSC_EXPORT_API void qsc_aes_hba256_set_associated	(	qsc_aes_hba256_state *	ctx,
		const uint8_t *	data,
		size_t	datalen )

Set the associated data (AAD) for HBA-256 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_aes_hba256_transform.

Parameters

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

See also

qsc_aes_hba256_transform

qsc_aes_hba256_transform()

QSC_EXPORT_API bool qsc_aes_hba256_transform	(	qsc_aes_hba256_state *	ctx,
		uint8_t *	output,
		const uint8_t *	input,
		size_t	length )

Transform data using the HBA-256 authenticated encryption mode.

In encryption mode, this function encrypts the plaintext using AES-256 in CTR mode, computes a MAC over the nonce and ciphertext, and appends the MAC to the output. In decryption mode, it first verifies the MAC before decrypting the ciphertext.

Parameters

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

Returns

[bool] Returns true if the transformation (and MAC verification in decryption mode) was successful; otherwise, false.

See also

qsc_aes_hba256_initialize, qsc_aes_hba256_set_associated

qsc_aes_initialize()

QSC_EXPORT_API void qsc_aes_initialize	(	qsc_aes_state *	ctx,
		const qsc_aes_keyparams *	keyparams,
		bool	encryption,
		qsc_aes_cipher_type	ctype )

Initialize the AES ctx with the given key parameters.

Expands the input cipher key into a round-key array for encryption or decryption. Note that for CTR mode the cipher is always initialized for encryption.

Warning

When using a CTR based construction (CTR-BE, CTR-LE, AES-GCM), 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] Pointer to the qsc_aes_state structure to initialize.
keyparams	[const struct] Pointer to a constant qsc_aes_keyparams structure containing key, nonce, and optional info.
encryption	[bool] Set to true to initialize for encryption; false for decryption.
ctype	[enum] Specifies the AES cipher type (qsc_aes_cipher_128 or qsc_aes_cipher_256).

Warning

Ensure that ctx->roundkeys is cleared and its size set before calling.

See also

qsc_aes_dispose

qsc_pkcs7_add_padding()

QSC_EXPORT_API void qsc_pkcs7_add_padding	(	uint8_t *	input,
		size_t	length )

Add PKCS#7 padding to a plaintext block.

Pads the input block with a padding byte equal to the number of padded bytes.

Parameters

input	[uint8_t*] Pointer to the plaintext block (will be modified in-place).
length	[size_t] Number of bytes that are less than the block size (i.e. QSC_AES_BLOCK_SIZE - actual data length).

See also

qsc_pkcs7_padding_length

qsc_pkcs7_padding_length()

QSC_EXPORT_API size_t qsc_pkcs7_padding_length

(

const uint8_t *

input

)

Determine the length of PKCS#7 padding in a decrypted block.

Analyzes a block of decrypted data and returns the number of padding bytes.

Parameters

input

[const uint8_t*] Pointer to a decrypted block of plaintext.

Returns

[size_t] The number of padding bytes, or 0U if the padding is invalid.

See also

qsc_pkcs7_add_padding