hqc.h File Reference

Contains the public API for the HQC CCA-secure Key Encapsulation Mechanism. More...

#include "qsccommon.h"
#include "hqcbase.h"

Go to the source code of this file.

Macros
#define	QSC_HQC_PUBLICKEY_SIZE   7237U
	The byte size of the public-key array.
#define	QSC_HQC_PRIVATEKEY_SIZE   7333U
	The byte size of the secret private-key array.
#define	QSC_HQC_CIPHERTEXT_SIZE   14421U
	The byte size of the ciphertext array.
#define	QSC_HQC_SEED_SIZE   32U
	The byte size of the seed array.
#define	QSC_HQC_SHAREDSECRET_SIZE   32U
	The byte size of the shared secret-key array.
#define	QSC_HQC_ALGNAME   "HQC"
	The formal algorithm name.

Functions
QSC_EXPORT_API bool	qsc_hqc_decapsulate (uint8_t *secret, const uint8_t *ciphertext, const uint8_t *privatekey)
	Decapsulates the shared secret for a given ciphertext using a private key.
QSC_EXPORT_API bool	qsc_hqc_encapsulate (uint8_t *secret, uint8_t *ciphertext, const uint8_t *publickey, bool(*rng_generate)(uint8_t *, size_t))
	Encapsulates a shared secret key using a public key.
void	qsc_hqc_seeded_encapsulate (uint8_t *secret, uint8_t *ciphertext, const uint8_t *publickey, const uint8_t seed[QSC_HQC_SEED_SIZE])
	Generates cipher text and shared secret for given public key and a random seed.
QSC_EXPORT_API bool	qsc_hqc_generate_keypair (uint8_t *publickey, uint8_t *privatekey, bool(*rng_generate)(uint8_t *, size_t))
	Generates a Kyber public/private key pair.
QSC_EXPORT_API void	qsc_hqc_generate_seeded_keypair (uint8_t *publickey, uint8_t *privatekey, uint8_t *seed)
	Generates public and private key for the CCA-Secure Kyber key encapsulation mechanism using input seeds.

Detailed Description

Contains the public API for the HQC CCA-secure Key Encapsulation Mechanism.

The Hamming Quasi-Cyclic (HQC) key encapsulation mechanism provides functionality for generating key pairs, encapsulating a shared secret using a public key, and decapsulating the shared secret using a private key.

This interface supports the HQC parameter sets corresponding to NIST security categories 1, 3, and 5. The active implementation is selected at compile time using one of the parameter guard macros QSC_HQC_S1N2321, QSC_HQC_S3N4602, or QSC_HQC_S5N7333.

// Example usage:
uint8_t pk[QSC_HQC_PUBLICKEY_SIZE];
uint8_t sk[QSC_HQC_PRIVATEKEY_SIZE];
uint8_t ct[QSC_HQC_CIPHERTEXT_SIZE];
uint8_t ss[QSC_HQC_SHAREDSECRET_SIZE];
 
qsc_hqc_generate_keypair(pk, sk, rng_generate);
qsc_hqc_encapsulate(ss, ct, pk, rng_generate);
if (qsc_hqc_decapsulate(ss, ct, sk) == false)
{
    // Decapsulation failed.
}

Reference Links:

• HQC Project Page
• NIST Post-Quantum Cryptography Round 4 Submissions

Function Documentation

qsc_hqc_decapsulate()

QSC_EXPORT_API bool qsc_hqc_decapsulate	(	uint8_t *	secret,
		const uint8_t *	ciphertext,
		const uint8_t *	privatekey )

Decapsulates the shared secret for a given ciphertext using a private key.

Combines the ciphertext with the private key to derive the shared secret.

Parameters

secret	[uint8_t*] Pointer to the output shared secret key (array of QSC_HQC_SHAREDSECRET_SIZE).
ciphertext	[const uint8_t*] Pointer to the ciphertext array (size QSC_HQC_CIPHERTEXT_SIZE).
privatekey	[const uint8_t*] Pointer to the secret key array (size QSC_HQC_PRIVATEKEY_SIZE).

Returns

[bool] Returns true if decapsulation succeeds.

qsc_hqc_encapsulate()

QSC_EXPORT_API bool qsc_hqc_encapsulate	(	uint8_t *	secret,
		uint8_t *	ciphertext,
		const uint8_t *	publickey,
		bool(*	rng_generate )(uint8_t *, size_t) )

Encapsulates a shared secret key using a public key.

Generates ciphertext and a shared secret; used for key encapsulation.

Parameters

secret	[uint8_t*] Pointer to the output shared secret key (array of QSC_HQC_SHAREDSECRET_SIZE).
ciphertext	[uint8_t*] Pointer to the output ciphertext array (size QSC_HQC_CIPHERTEXT_SIZE).
publickey	[const uint8_t*] Pointer to the public key array (size QSC_HQC_PUBLICKEY_SIZE).
rng_generate	[bool (*)(uint8_t*, size_t)] Pointer to a random generator function.

Returns

[bool] Returns true if encapsulation succeeds.

qsc_hqc_generate_keypair()

QSC_EXPORT_API bool qsc_hqc_generate_keypair	(	uint8_t *	publickey,
		uint8_t *	privatekey,
		bool(*	rng_generate )(uint8_t *, size_t) )

Generates a Kyber public/private key pair.

Produces a key pair for the Kyber key encapsulation mechanism.

Parameters

publickey	[uint8_t*] Pointer to the output public key array (size QSC_HQC_PUBLICKEY_SIZE)
privatekey	[uint8_t*] Pointer to the output private key array (size QSC_HQC_PRIVATEKEY_SIZE)
rng_generate	[bool (*)(uint8_t*, size_t)] Pointer to a random generator function.

Returns

[bool] Returns true if key generation succeeds.

qsc_hqc_generate_seeded_keypair()

QSC_EXPORT_API void qsc_hqc_generate_seeded_keypair	(	uint8_t *	publickey,
		uint8_t *	privatekey,
		uint8_t *	seed )

Generates public and private key for the CCA-Secure Kyber key encapsulation mechanism using input seeds.

Note

Used exclusively for the NIST ACVP KAT tests, use the other call to generate the key-pair.

Parameters

publickey	[uint8_t*] Pointer to output public key (an already allocated array of HQC_PUBLICKEY_SIZE bytes)
privatekey	[uint8_t*] Pointer to output private key (an already allocated array of HQC_SECRETKEY_SIZE bytes)
seed	[uint8_t*] Pointer to the random seed

qsc_hqc_seeded_encapsulate()

void qsc_hqc_seeded_encapsulate	(	uint8_t *	secret,
		uint8_t *	ciphertext,
		const uint8_t *	publickey,
		const uint8_t	seed[QSC_HQC_SEED_SIZE] )

Generates cipher text and shared secret for given public key and a random seed.

Note

Used exclusively for the NIST ACVP KAT tests, use the other call to encapsulate a key.

Parameters

ct	[uint8_t*] Pointer to output cipher text (an already allocated array of HQC_CIPHERTEXT_SIZE bytes)
ss	[uint8_t*] Pointer to output shared secret (an already allocated array of HQC_BYTES bytes)
pk	[const uint8_t*] Pointer to input public key (an already allocated array of HQC_PUBLICKEY_SIZE bytes)
seed	[const uint8_t*] Pointer to the random seed (a populated random array of QSC_HQC_SEED_SIZE bytes)