kyber.h File Reference

Contains the public API for the FIPS 203 implementation of the Kyber CCA-secure Key Encapsulation Mechanism. More...

#include "qsccommon.h"
#include "kyberbase.h"

Go to the source code of this file.

Macros
#define	QSC_KYBER_CIPHERTEXT_SIZE   (QSC_KYBER_INDCPA_BYTES)
	The byte size of the ciphertext array.
#define	QSC_KYBER_PRIVATEKEY_SIZE   (QSC_KYBER_INDCPA_SECRETKEY_BYTES + QSC_KYBER_INDCPA_PUBLICKEY_BYTES + (2 * QSC_KYBER_SYMBYTES))
	The byte size of the secret private-key array.
#define	QSC_KYBER_PUBLICKEY_SIZE   (QSC_KYBER_INDCPA_PUBLICKEY_BYTES)
	The byte size of the public-key array.
#define	QSC_KYBER_SEED_SIZE   32U
	The byte size of the seed array.
#define	QSC_KYBER_SHAREDSECRET_SIZE   32U
	The byte size of the shared secret-key array.
#define	QSC_KYBER_ALGNAME   "KYBER"
	The formal algorithm name.

Functions
QSC_EXPORT_API bool	qsc_kyber_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_kyber_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_kyber_seeded_encapsulate (uint8_t *secret, uint8_t *ciphertext, const uint8_t *publickey, const uint8_t m[QSC_KYBER_SYMBYTES])
	Generates cipher text and shared secret for given public key and a random seed.
QSC_EXPORT_API bool	qsc_kyber_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_kyber_generate_seeded_keypair (uint8_t *publickey, uint8_t *privatekey, uint8_t *d, uint8_t *z)
	Generates public and private key for the CCA-Secure Kyber key encapsulation mechanism using input seeds.

Detailed Description

Contains the public API for the FIPS 203 implementation of the Kyber CCA-secure Key Encapsulation Mechanism.

The Kyber key encapsulation mechanism (KEM) provides functionality for generating key pairs, encapsulating a shared secret using a public key, and decapsulating the shared secret using a private key. It is the FIPS 203 Kyber implementation with an additional K=5 parameter to enhance security.

// Example usage:
uint8_t pk[QSC_KYBER_PUBLICKEY_SIZE];
uint8_t sk[QSC_KYBER_PRIVATEKEY_SIZE];
uint8_t ct[QSC_KYBER_CIPHERTEXT_SIZE];
uint8_t ss[QSC_KYBER_SHAREDSECRET_SIZE];
 
qsc_kyber_generate_keypair(pk, sk, rng_generate);
qsc_kyber_encapsulate(ss, ct, pk, rng_generate);
if (!qsc_kyber_decapsulate(ss, ct, sk))
{
    // Decapsulation failed.
}

Reference Links:

• Kyber Specification (FIPS 203)

Function Documentation

qsc_kyber_decapsulate()

QSC_EXPORT_API bool qsc_kyber_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_KYBER_SHAREDSECRET_SIZE).
ciphertext	[const uint8_t*] Pointer to the ciphertext array (size QSC_KYBER_CIPHERTEXT_SIZE).
privatekey	[const uint8_t*] Pointer to the secret key array (size QSC_KYBER_PRIVATEKEY_SIZE).

Returns

[bool] Returns true if decapsulation succeeds.

qsc_kyber_encapsulate()

QSC_EXPORT_API bool qsc_kyber_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_KYBER_SHAREDSECRET_SIZE).
ciphertext	[uint8_t*] Pointer to the output ciphertext array (size QSC_KYBER_CIPHERTEXT_SIZE).
publickey	[const uint8_t*] Pointer to the public key array (size QSC_KYBER_PUBLICKEY_SIZE).
rng_generate	[bool (*)(uint8_t*, size_t)] Pointer to a random generator function.

Returns

[bool] Returns true if encapsulation succeeds.

qsc_kyber_generate_keypair()

QSC_EXPORT_API bool qsc_kyber_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_KYBER_PUBLICKEY_SIZE)
privatekey	[uint8_t*] Pointer to the output private key array (size QSC_KYBER_PRIVATEKEY_SIZE)
rng_generate	[bool (*)(uint8_t*, size_t)] Pointer to a random generator function.

Returns

[bool] Returns true if key generation succeeds.

qsc_kyber_generate_seeded_keypair()

QSC_EXPORT_API void qsc_kyber_generate_seeded_keypair	(	uint8_t *	publickey,
		uint8_t *	privatekey,
		uint8_t *	d,
		uint8_t *	z )

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

pk	[uint8_t*] Pointer to output public key (an already allocated array of KYBER_PUBLICKEY_SIZE bytes)
sk	[uint8_t*] Pointer to output private key (an already allocated array of KYBER_SECRETKEY_SIZE bytes)
d	[uint8_t*] Pointer to the random d coin (a populated random array of QSC_KYBER_SYMBYTES bytes)
z	[uint8_t*] Pointer to the random z coin (a populated random array of QSC_KYBER_SYMBYTES bytes)

qsc_kyber_seeded_encapsulate()

void qsc_kyber_seeded_encapsulate	(	uint8_t *	secret,
		uint8_t *	ciphertext,
		const uint8_t *	publickey,
		const uint8_t	m[QSC_KYBER_SYMBYTES] )

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 KYBER_CIPHERTEXT_SIZE bytes)
ss	[uint8_t*] Pointer to output shared secret (an already allocated array of KYBER_BYTES bytes)
pk	[const uint8_t*] Pointer to input public key (an already allocated array of KYBER_PUBLICKEY_SIZE bytes)
m	[const uint8_t*] Pointer to the random coin (a populated random array of QSC_KYBER_SYMBYTES bytes)