qmac.h File Reference

QMAC function definitions. More...

#include "common.h"

Go to the source code of this file.

Data Structures
struct	qsc_qmac_state
	The QMAC state. More...
struct	qsc_qmac_keyparams
	The key parameters structure containing key and info arrays and lengths. More...

Macros
#define	QSC_QMAC_BLOCK_SIZE   32ULL
	The natural block size of the message input in bytes.
#define	QSC_QMAC_KEY_SIZE   32ULL
	The QMAC key size in bytes.
#define	QSC_QMAC_MAC_SIZE   32ULL
	The QMAC MAC code size in bytes.
#define	QSC_QMAC_NONCE_SIZE   32ULL
	The QMAC nonce size in bytes.
#define	QSC_QMAC_STATE_SIZE   (QSC_QMAC_BLOCK_SIZE / sizeof(uint64_t))
	The QMAC state size.

Enumerations
enum	qsc_qmac_modes { qsc_qmac_mode_256 = 0x00U , qsc_qmac_mode_512 = 0x01U }
	The QMAC mode types. More...

Functions
QSC_EXPORT_API void	qsc_qmac_compute (uint8_t *output, qsc_qmac_keyparams *keyparams, const uint8_t *message, size_t msglen)
	Compute the MAC code.
QSC_EXPORT_API void	qsc_qmac_dispose (qsc_qmac_state *ctx)
	Dispose of the state.
QSC_EXPORT_API void	qsc_qmac_finalize (qsc_qmac_state *ctx, uint8_t *output)
	Finalize the message state and return the MAC code.
QSC_EXPORT_API void	qsc_qmac_initialize (qsc_qmac_state *ctx, qsc_qmac_keyparams *keyparams)
	Initialize the state with the secret key.
QSC_EXPORT_API void	qsc_qmac_update (qsc_qmac_state *ctx, const uint8_t *message, size_t msglen)
	Update the QMAC generator with a single block of message input.

Detailed Description

QMAC function definitions.

This header defines the public API for the QMAC (Quantum-Safe Message Authentication Code) implementation. The QMAC algorithm is used for generating message authentication codes using hash and finalization keys generated by Keccak, and a 256-bit carryless multiplication, and reduction using a Galois field GF(2^256) to process the message state. It supports different modes (QMAC-256 and QMAC-512) as determined by the qsc_qmac_modes enumeration. The API includes functions to compute a MAC, initialize and update the QMAC state, finalize the computation, and securely dispose of the state.

Additionally, this module provides documentation and references for:

• GMAC (Galois Message Authentication Code): a variant of GCM used for authentication.
• Carryless multiplication: an efficient method for performing multiplication in binary fields, as utilized by GMAC.
• Galois fields: the underlying mathematical structure used in GMAC and other cryptographic primitives.
• SHA3: the cryptographic hash standard specified in FIPS 202.

Reference Links:

• GMAC (NIST SP 800-38D)
• Carryless Multiplication (Intel Optimization Reference Manual)
• Galois Fields (MathWorks Documentation)
• SHA3 FIPS 202

Enumeration Type Documentation

qsc_qmac_modes

enum qsc_qmac_modes

The QMAC mode types.

Enumerator
qsc_qmac_mode_256	the qmac-256 mode
qsc_qmac_mode_512	the qmac-512 mode

Function Documentation

qsc_qmac_compute()

QSC_EXPORT_API void qsc_qmac_compute	(	uint8_t *	output,
		qsc_qmac_keyparams *	keyparams,
		const uint8_t *	message,
		size_t	msglen )

Compute the MAC code.

Computes the QMAC code for the provided message using the given key parameters.

Parameters

output	[uint8_t*] Pointer to the output byte array; receives the MAC code.
keyparams	[qsc_qmac_keyparams*] Pointer to the QMAC key parameters structure.
message	[const uint8_t*] Pointer to the message input byte array.
msglen	[size_t] The number of message bytes to process.

qsc_qmac_dispose()

QSC_EXPORT_API void qsc_qmac_dispose

(

qsc_qmac_state *

ctx

)

Dispose of the state.

Erases all variables and resets the state.

Parameters

ctx	[qsc_qmac_state*] Pointer to the QMAC state structure; must be initialized.

qsc_qmac_finalize()

QSC_EXPORT_API void qsc_qmac_finalize	(	qsc_qmac_state *	ctx,
		uint8_t *	output )

Finalize the message state and return the MAC code.

Absorbs the last block of message and creates the MAC code.

Parameters

ctx	[qsc_qmac_state*] Pointer to the QMAC state structure; must be initialized.
output	[uint8_t*] Pointer to the MAC output byte array.

qsc_qmac_initialize()

QSC_EXPORT_API void qsc_qmac_initialize	(	qsc_qmac_state *	ctx,
		qsc_qmac_keyparams *	keyparams )

Initialize the state with the secret key.

Initializes the QMAC state using the provided key parameters.

Parameters

ctx	[qsc_qmac_state*] Pointer to the QMAC state structure.
keyparams	[qsc_qmac_keyparams*] Pointer to the QMAC key parameters structure.

qsc_qmac_update()

QSC_EXPORT_API void qsc_qmac_update	(	qsc_qmac_state *	ctx,
		const uint8_t *	message,
		size_t	msglen )

Update the QMAC generator with a single block of message input.

Absorbs a block-sized portion of the input message into the QMAC state.

Parameters

ctx	[qsc_qmac_state*] Pointer to the QMAC state structure; must be initialized.
message	[const uint8_t*] Pointer to the input message byte array.
msglen	[size_t] The length of the message; must equal one block (QSC_QMAC_BLOCK_SIZE).