Functions
enum lc_kyber_type	lc_kyber_sk_type (const struct lc_kyber_sk *sk)
	Obtain Kyber type from secret key.
enum lc_kyber_type	lc_kyber_pk_type (const struct lc_kyber_pk *pk)
	Obtain Kyber type from public key.
enum lc_kyber_type	lc_kyber_ct_type (const struct lc_kyber_ct *ct)
	Obtain Kyber type from Kyber ciphertext.
enum lc_kyber_type	lc_kyber_ss_type (const struct lc_kyber_ss *ss)
	Obtain Kyber type from shared secret.
LC_PURE unsigned int	lc_kyber_sk_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber secret key.
LC_PURE unsigned int	lc_kyber_pk_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber public key.
LC_PURE unsigned int	lc_kyber_ct_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber ciphertext.
LC_PURE unsigned int	lc_kyber_ss_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber shared secret.
int	lc_kyber_sk_load (struct lc_kyber_sk sk, const uint8_t src_key, size_t src_key_len)
	Load a Kyber secret key provided with a buffer into the leancrypto data structure.
int	lc_kyber_pk_load (struct lc_kyber_pk pk, const uint8_t src_key, size_t src_key_len)
	Load a Kyber public key provided with a buffer into the leancrypto data structure.
int	lc_kyber_ct_load (struct lc_kyber_ct ct, const uint8_t src_key, size_t src_key_len)
	Load a Kyber ciphertext key provided with a buffer into the leancrypto data structure.
int	lc_kyber_ss_load (struct lc_kyber_ss ss, const uint8_t src_key, size_t src_key_len)
	Load a Kyber shared secret provided with a buffer into the leancrypto data structure.
int	lc_kyber_sk_ptr (uint8_t *kyber_key, size_t kyber_key_len, struct lc_kyber_sk *sk)
	Obtain the reference to the Kyber key and its length.
int	lc_kyber_pk_ptr (uint8_t *kyber_key, size_t kyber_key_len, struct lc_kyber_pk *pk)
	Obtain the reference to the Kyber key and its length.
int	lc_kyber_ct_ptr (uint8_t *kyber_ct, size_t kyber_ct_len, struct lc_kyber_ct *ct)
	Obtain the reference to the Kyber ciphertext and its length.
int	lc_kyber_ss_ptr (uint8_t *kyber_ss, size_t kyber_ss_len, struct lc_kyber_ss *ss)
	Obtain the reference to the Kyber shared secret and its length.
int	lc_kyber_keypair (struct lc_kyber_pk pk, struct lc_kyber_sk sk, struct lc_rng_ctx *rng_ctx, enum lc_kyber_type kyber_type)
	Generates public and private key for IND-CCA2-secure Kyber key encapsulation mechanism.
int	lc_kyber_keypair_from_seed (struct lc_kyber_pk pk, struct lc_kyber_sk sk, const uint8_t *seed, size_t seedlen, enum lc_kyber_type kyber_type)
	Generates Kyber public and private key from a given seed.
int	lc_kyber_enc (struct lc_kyber_ct ct, struct lc_kyber_ss ss, const struct lc_kyber_pk *pk)
	Key encapsulation.
int	lc_kyber_enc_kdf (struct lc_kyber_ct ct, uint8_t ss, size_t ss_len, const struct lc_kyber_pk *pk)
	Key encapsulation with KDF applied to shared secret.
int	lc_kyber_dec (struct lc_kyber_ss ss, const struct lc_kyber_ct ct, const struct lc_kyber_sk *sk)
	Key decapsulation.
int	lc_kyber_dec_kdf (uint8_t ss, size_t ss_len, const struct lc_kyber_ct ct, const struct lc_kyber_sk *sk)
	Key decapsulation with KDF applied to shared secret.

Detailed Description

Note: Although the API uses the term "kyber", the implementation complies with FIPS 203. Thus, the term Kyber and ML-KEM are used interchangeably.

Kyber API concept

The Kyber API is accessible via the following header files with the mentioned purpose.

lc_kyber.h: This API is the generic API allowing the caller to select which Kyber type (Kyber 1024, 768 or 512) are to be used. The selection is made either with the flag specified during key generation or by matching the size of the imported data with the different lc_kyber_*_load API calls. All remaining APIs take the information about the Kyber type from the provided input data.

This header file only provides wrapper functions which selectively call the API provided with the header files below.
lc_kyber_1024.h: Direct access to Kyber 1024.
lc_kyber_768.h: Direct access to Kyber 768.
lc_kyber_512.h: Direct access to Kyber 512.

Function Documentation

◆ lc_kyber_ct_load()

int lc_kyber_ct_load	(	struct lc_kyber_ct *	ct,
		const uint8_t *	src_key,
		size_t	src_key_len )

Load a Kyber ciphertext key provided with a buffer into the leancrypto data structure.

Parameters

[out]	ct	Kyber ciphertext to be filled (the caller must have it allocated)
[in]	src_key	Buffer that holds the ciphertext to be imported
[in]	src_key_len	Buffer length that holds the ciphertext to be imported

Returns: 0 on success or < 0 on error

◆ lc_kyber_ct_ptr()

int lc_kyber_ct_ptr	(	uint8_t **	kyber_ct,
		size_t *	kyber_ct_len,
		struct lc_kyber_ct *	ct )

Obtain the reference to the Kyber ciphertext and its length.

Note: Only pointer references into the leancrypto data structure are returned which implies that any modification will modify the leancrypto ciphertext, too.

Parameters

[out]	kyber_ct	Kyber ciphertext pointer
[out]	kyber_ct_len	Length of the ciphertext buffer
[in]	ct	Kyber ciphertext from which the references are obtained

Returns: 0 on success, != 0 on error

◆ lc_kyber_ct_size()

LC_PURE unsigned int lc_kyber_ct_size ( enum lc_kyber_type kyber_type )

Return the size of the Kyber ciphertext.

Parameters

[in] kyber_type Kyber type for which the size is requested

Returns: requested size

◆ lc_kyber_ct_type()

enum lc_kyber_type lc_kyber_ct_type ( const struct lc_kyber_ct * ct )

Obtain Kyber type from Kyber ciphertext.

Parameters

[in] ct Ciphertext from which the type is to be obtained

Returns: key type

◆ lc_kyber_dec()

int lc_kyber_dec	(	struct lc_kyber_ss *	ss,
		const struct lc_kyber_ct *	ct,
		const struct lc_kyber_sk *	sk )

Key decapsulation.

Generates shared secret for given cipher text and private key

Parameters

[out]	ss	pointer to output shared secret that is the same as produced during encapsulation
[in]	ct	pointer to input cipher text generated during encapsulation
[in]	sk	pointer to input private key

Returns: 0

On failure, ss will contain a pseudo-random value.

◆ lc_kyber_dec_kdf()

int lc_kyber_dec_kdf	(	uint8_t *	ss,
		size_t	ss_len,
		const struct lc_kyber_ct *	ct,
		const struct lc_kyber_sk *	sk )

Key decapsulation with KDF applied to shared secret.

Generates cipher text and shared secret for given private key. The shared secret is derived from the Kyber SS using the KDF derived from the round 3 definition of Kyber:

 SS <- KMAC256(K = Kyber-SS, X = Kyber-CT, L = requested SS length,
          S = "Kyber KEM SS")

Parameters

[out]	ss	pointer to output shared secret that is the same as produced during encapsulation
[in]	ss_len	length of shared secret to be generated
[in]	ct	pointer to input cipher text generated during encapsulation
[in]	sk	pointer to input private key

Returns: 0

On failure, ss will contain a pseudo-random value.

◆ lc_kyber_enc()

int lc_kyber_enc	(	struct lc_kyber_ct *	ct,
		struct lc_kyber_ss *	ss,
		const struct lc_kyber_pk *	pk )

Key encapsulation.

Generates cipher text and shared secret for given public key.

Parameters

[out]	ct	pointer to output cipher text to used for decapsulation
[out]	ss	pointer to output shared secret that will be also produced during decapsulation
[in]	pk	pointer to input public key

Returns 0 (success) or < 0 on error

◆ lc_kyber_enc_kdf()

int lc_kyber_enc_kdf	(	struct lc_kyber_ct *	ct,
		uint8_t *	ss,
		size_t	ss_len,
		const struct lc_kyber_pk *	pk )

Key encapsulation with KDF applied to shared secret.

Generates cipher text and shared secret for given public key. The shared secret is derived from the Kyber SS using the KDF derived from the round 3 definition of Kyber:

 SS <- KMAC256(K = Kyber-SS, X = Kyber-CT, L = requested SS length,
          S = "Kyber KEM SS")

Parameters

[out]	ct	pointer to output cipher text to used for decapsulation
[out]	ss	pointer to output shared secret that will be also produced during decapsulation
[in]	ss_len	length of shared secret to be generated
[in]	pk	pointer to input public key

Returns 0 (success) or < 0 on error

◆ lc_kyber_keypair()

int lc_kyber_keypair	(	struct lc_kyber_pk *	pk,
		struct lc_kyber_sk *	sk,
		struct lc_rng_ctx *	rng_ctx,
		enum lc_kyber_type	kyber_type )

Generates public and private key for IND-CCA2-secure Kyber key encapsulation mechanism.

Parameters

[out]	pk	pointer to already allocated output public key
[out]	sk	pointer to already allocated output private key
[in]	rng_ctx	pointer to seeded random number generator context
[in]	kyber_type	type of the Kyber key to generate

Returns: 0 (success) or < 0 on error

◆ lc_kyber_keypair_from_seed()

int lc_kyber_keypair_from_seed	(	struct lc_kyber_pk *	pk,
		struct lc_kyber_sk *	sk,
		const uint8_t *	seed,
		size_t	seedlen,
		enum lc_kyber_type	kyber_type )

Generates Kyber public and private key from a given seed.

The idea of the function is the allowance of FIPS 203 to maintain the seed used to generate a key pair in lieu of maintaining a private key or the key pair (which used much more memory). The seed must be treated equally sensitive as a private key.

The seed is generated by simply obtaining 64 bytes from a properly seeded DRNG, i.e. the same way as a symmetric key would be generated.

Compliant to the notation of FIPS 203 the following definition applies: seed = d || z

Parameters

[out]	pk	pointer to allocated output public key
[out]	sk	pointer to allocated output private key
[in]	seed	buffer with the seed data which must be exactly 64 bytes in size
[in]	seedlen	length of the seed buffer
[in]	kyber_type	type of the Kyber key to generate

Returns: 0 (success) or < 0 on error

◆ lc_kyber_pk_load()

int lc_kyber_pk_load	(	struct lc_kyber_pk *	pk,
		const uint8_t *	src_key,
		size_t	src_key_len )

Load a Kyber public key provided with a buffer into the leancrypto data structure.

Parameters

[out]	pk	Public key to be filled (the caller must have it allocated)
[in]	src_key	Buffer that holds the key to be imported
[in]	src_key_len	Buffer length that holds the key to be imported

Returns: 0 on success or < 0 on error

◆ lc_kyber_pk_ptr()

int lc_kyber_pk_ptr	(	uint8_t **	kyber_key,
		size_t *	kyber_key_len,
		struct lc_kyber_pk *	pk )

Obtain the reference to the Kyber key and its length.

Note: Only pointer references into the leancrypto data structure are returned which implies that any modification will modify the leancrypto key, too.

Parameters

[out]	kyber_key	Kyber key pointer
[out]	kyber_key_len	Length of the key buffer
[in]	pk	Kyber public key from which the references are obtained

Returns: 0 on success, != 0 on error

◆ lc_kyber_pk_size()

LC_PURE unsigned int lc_kyber_pk_size ( enum lc_kyber_type kyber_type )

Return the size of the Kyber public key.

Parameters

[in] kyber_type Kyber type for which the size is requested

Returns: requested size

◆ lc_kyber_pk_type()

enum lc_kyber_type lc_kyber_pk_type ( const struct lc_kyber_pk * pk )

Obtain Kyber type from public key.

Parameters

[in] pk Public key from which the type is to be obtained

Returns: key type

◆ lc_kyber_sk_load()

int lc_kyber_sk_load	(	struct lc_kyber_sk *	sk,
		const uint8_t *	src_key,
		size_t	src_key_len )

Load a Kyber secret key provided with a buffer into the leancrypto data structure.

Parameters

[out]	sk	Secret key to be filled (the caller must have it allocated)
[in]	src_key	Buffer that holds the key to be imported
[in]	src_key_len	Buffer length that holds the key to be imported

Returns: 0 on success or < 0 on error

◆ lc_kyber_sk_ptr()

int lc_kyber_sk_ptr	(	uint8_t **	kyber_key,
		size_t *	kyber_key_len,
		struct lc_kyber_sk *	sk )

Obtain the reference to the Kyber key and its length.

Note: Only pointer references into the leancrypto data structure are returned which implies that any modification will modify the leancrypto key, too.

Parameters

[out]	kyber_key	Kyber key pointer
[out]	kyber_key_len	Length of the key buffer
[in]	sk	Kyber secret key from which the references are obtained

Returns: 0 on success, != 0 on error

◆ lc_kyber_sk_size()

LC_PURE unsigned int lc_kyber_sk_size ( enum lc_kyber_type kyber_type )

Return the size of the Kyber secret key.

Parameters

[in] kyber_type Kyber type for which the size is requested

Returns: requested size

◆ lc_kyber_sk_type()

enum lc_kyber_type lc_kyber_sk_type ( const struct lc_kyber_sk * sk )

Obtain Kyber type from secret key.

Parameters

[in] sk Secret key from which the type is to be obtained

Returns: key type

◆ lc_kyber_ss_load()

int lc_kyber_ss_load	(	struct lc_kyber_ss *	ss,
		const uint8_t *	src_key,
		size_t	src_key_len )

Load a Kyber shared secret provided with a buffer into the leancrypto data structure.

Parameters

[out]	ss	Kyber shared secret to be filled (the caller must have it allocated)
[in]	src_key	Buffer that holds the shared secret to be imported
[in]	src_key_len	Buffer length that holds the shared secret to be imported

Returns: 0 on success or < 0 on error

◆ lc_kyber_ss_ptr()

int lc_kyber_ss_ptr	(	uint8_t **	kyber_ss,
		size_t *	kyber_ss_len,
		struct lc_kyber_ss *	ss )

Obtain the reference to the Kyber shared secret and its length.

Note: Only pointer references into the leancrypto data structure are returned which implies that any modification will modify the leancrypto shared secret, too.

Parameters

[out]	kyber_ss	Kyber shared secret pointer
[out]	kyber_ss_len	Length of the shared secret buffer
[in]	ss	Kyber shared secret from which the references are obtained

Returns: 0 on success, != 0 on error

◆ lc_kyber_ss_size()

LC_PURE unsigned int lc_kyber_ss_size ( enum lc_kyber_type kyber_type )

Return the size of the Kyber shared secret.

Parameters

[in] kyber_type Kyber type for which the size is requested

Returns: requested size

◆ lc_kyber_ss_type()

enum lc_kyber_type lc_kyber_ss_type ( const struct lc_kyber_ss * ss )

Obtain Kyber type from shared secret.

Parameters

[in] ss Shared secret key from which the type is to be obtained

Returns: key type

Functions

Detailed Description

Function Documentation

◆ lc_kyber_ct_load()

◆ lc_kyber_ct_ptr()

◆ lc_kyber_ct_size()

◆ lc_kyber_ct_type()

◆ lc_kyber_dec()

◆ lc_kyber_dec_kdf()

◆ lc_kyber_enc()

◆ lc_kyber_enc_kdf()

◆ lc_kyber_keypair()

◆ lc_kyber_keypair_from_seed()

◆ lc_kyber_pk_load()

◆ lc_kyber_pk_ptr()

◆ lc_kyber_pk_size()

◆ lc_kyber_pk_type()

◆ lc_kyber_sk_load()

◆ lc_kyber_sk_ptr()

◆ lc_kyber_sk_size()

◆ lc_kyber_sk_type()

◆ lc_kyber_ss_load()

◆ lc_kyber_ss_ptr()

◆ lc_kyber_ss_size()

◆ lc_kyber_ss_type()