mceliece.h File Reference

Contains the primary public API for the Niederreiter dual form of the McEliece asymmetric cipher implementation. More...

#include "qsccommon.h"

Go to the source code of this file.

Macros
#define	QSC_MCELIECE_KEYGEN_STACK_BYTES   (4U * 1024U * 1024U)
	Minimum stack size required to call qsc_mceliece_generate_keypair.
#define	QSC_MCELIECE_CIPHERTEXT_SIZE   240
	The byte size of the ciphertext array.
#define	QSC_MCELIECE_PRIVATEKEY_SIZE   13932
	The byte size of the secret private-key array.
#define	QSC_MCELIECE_PUBLICKEY_SIZE   1044992
	The byte size of the public-key array.
#define	QSC_MCELIECE_SEED_SIZE   32ULL
	The byte size of the seed array.
#define	QSC_MCELIECE_SHAREDSECRET_SIZE   32ULL
	The byte size of the shared secret-key array.
#define	QSC_MCELIECE_ALGNAME   "MCELIECE"
	The formal algorithm name.

Functions
QSC_EXPORT_API bool	qsc_mceliece_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_mceliece_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.
QSC_EXPORT_API bool	qsc_mceliece_generate_keypair (uint8_t *publickey, uint8_t *privatekey, bool(*rng_generate)(uint8_t *, size_t))
	Generates a McEliece public/private key pair.

Detailed Description

Contains the primary public API for the Niederreiter dual form of the McEliece asymmetric cipher implementation.

This header defines the functions and constants for the McEliece Key Encapsulation Mechanism (KEM) implementation. Depending on the defined parameter set (e.g. QSC_MCELIECE_S1N3488T64, QSC_MCELIECE_S3N4608T96, etc.), the sizes of the ciphertext, private key, and public key vary. The API supports key encapsulation (encryption) and decapsulation (decryption) operations.

uint8_t ct[QSC_MCELIECE_CIPHERTEXT_SIZE];
uint8_t pk[QSC_MCELIECE_PUBLICKEY_SIZE];
uint8_t sk[QSC_MCELIECE_PRIVATEKEY_SIZE];
uint8_t ssa[QSC_MCELIECE_SHAREDSECRET_SIZE];
uint8_t ssb[QSC_MCELIECE_SHAREDSECRET_SIZE];
 
// Create the public and secret keys.
qsc_mceliece_generate_keypair(pk, sk, rng_generate);
 
// Output the ciphertext and the shared secret.
qsc_mceliece_encapsulate(ssb, ct, pk, rng_generate);
 
// Decapsulate to retrieve the shared secret.
if (qsc_mceliece_decapsulate(ssa, ct, sk) == false)
{
    // Decapsulation failed; handle error.
}

Reference Links:

• Classic McEliece Specification
• SHA3 Standard (FIPS 202)

Macro Definition Documentation

QSC_MCELIECE_KEYGEN_STACK_BYTES

#define QSC_MCELIECE_KEYGEN_STACK_BYTES   (4U * 1024U * 1024U)

Minimum stack size required to call qsc_mceliece_generate_keypair.

Key generation allocates a ~1.7 MiB Gaussian-elimination matrix on the stack (matching the NIST round-4 reference implementation). Callers running on threads with small default stacks (macOS secondary threads: 512 KiB, Windows default: 1 MiB, musl libc: 128 KiB) MUST either set a larger stack size before creating the thread, or use the provided qsc_mceliece_generate_keypair_ex() wrapper which spawns a dedicated thread with the correct stack size.

Function Documentation

qsc_mceliece_decapsulate()

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

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

Parameters

secret	[uint8_t*] Pointer to the output shared secret key (array of QSC_MCELIECE_SHAREDSECRET_SIZE).
ciphertext	[const uint8_t*] Pointer to the ciphertext array (size QSC_MCELIECE_CIPHERTEXT_SIZE).
privatekey	[const uint8_t*] Pointer to the private key array (size QSC_MCELIECE_PRIVATEKEY_SIZE).

Returns

[bool] Returns true if decapsulation succeeds.

qsc_mceliece_encapsulate()

QSC_EXPORT_API bool qsc_mceliece_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.

Parameters

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

Returns

[bool] Returns true if encapsulation succeeds.

qsc_mceliece_generate_keypair()

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

Generates a McEliece public/private key pair.

Parameters

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

Returns

[bool] Returns true if key generation succeeds.