kyber.h File Reference

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

#include "common.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   32ULL
	The byte size of the seed array.
#define	QSC_KYBER_SHAREDSECRET_SIZE   32ULL
	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_decrypt (uint8_t *secret, const uint8_t *ciphertext, const uint8_t *privatekey)
	Decrypts the shared secret for a given ciphertext using a private key.
QSC_EXPORT_API void	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.
QSC_EXPORT_API void	qsc_kyber_encrypt (uint8_t *secret, uint8_t *ciphertext, const uint8_t *publickey, const uint8_t seed[QSC_KYBER_SEED_SIZE])
	Encrypts to encapsulate a shared secret key using a public key.
QSC_EXPORT_API void	qsc_kyber_generate_keypair (uint8_t *publickey, uint8_t *privatekey, bool(*rng_generate)(uint8_t *, size_t))
	Generates a Kyber public/private key pair.

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)
• SHA-3 Standard (FIPS 202)

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_decrypt()

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

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

Alternative decryption function; functionally equivalent to decapsulation.

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 decryption succeeds.

qsc_kyber_encapsulate()

QSC_EXPORT_API void 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.

qsc_kyber_encrypt()

QSC_EXPORT_API void qsc_kyber_encrypt	(	uint8_t *	secret,
		uint8_t *	ciphertext,
		const uint8_t *	publickey,
		const uint8_t	seed[QSC_KYBER_SEED_SIZE] )

Encrypts to encapsulate a shared secret key using a public key.

Generates ciphertext and a shared secret based on a public key and a given seed.

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).
seed	[const uint8_t[QSC_KYBER_SEED_SIZE]] Pointer to the random seed array.

qsc_kyber_generate_keypair()

QSC_EXPORT_API void 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.