Functions
static enum lc_kyber_type	lc_kyber_sk_type (const struct lc_kyber_sk *sk)
	Obtain Kyber type from secret key.

static enum lc_kyber_type	lc_kyber_pk_type (const struct lc_kyber_pk *pk)
	Obtain Kyber type from public key.

static enum lc_kyber_type	lc_kyber_ct_type (const struct lc_kyber_ct *ct)
	Obtain Kyber type from Kyber ciphertext.

static enum lc_kyber_type	lc_kyber_ss_type (const struct lc_kyber_ss *ss)
	Obtain Kyber type from shared secret.

static LC_PURE unsigned int	lc_kyber_sk_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber secret key.

static LC_PURE unsigned int	lc_kyber_pk_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber public key.

static LC_PURE unsigned int	lc_kyber_ct_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber ciphertext.

static LC_PURE unsigned int	lc_kyber_ss_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber shared secret.

static 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.

static 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.

static 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.

static 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.

static 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.

static 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.

static 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.

static 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.

static 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.

static 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.

static int	lc_kyber_enc (struct lc_kyber_ct ct, struct lc_kyber_ss ss, const struct lc_kyber_pk *pk)
	Key encapsulation.

static 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.

static int	lc_kyber_dec (struct lc_kyber_ss ss, const struct lc_kyber_ct ct, const struct lc_kyber_sk *sk)
	Key decapsulation.

static 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

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

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

inlinestatic

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

Definition at line 457 of file lc_kyber.h.

◆ lc_kyber_ct_ptr()

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

inlinestatic

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

Definition at line 646 of file lc_kyber.h.

◆ lc_kyber_ct_size()

static LC_PURE unsigned int lc_kyber_ct_size ( enum lc_kyber_type kyber_type )

inlinestatic

Return the size of the Kyber ciphertext.

Parameters

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

Returns: requested size

Definition at line 291 of file lc_kyber.h.

◆ lc_kyber_ct_type()

static enum lc_kyber_type lc_kyber_ct_type ( const struct lc_kyber_ct * ct )

inlinestatic

Obtain Kyber type from Kyber ciphertext.

Parameters

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

Returns: key type

Definition at line 188 of file lc_kyber.h.

◆ lc_kyber_dec()

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

inlinestatic

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.

Definition at line 970 of file lc_kyber.h.

◆ lc_kyber_dec_kdf()

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

inlinestatic

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.

Definition at line 1029 of file lc_kyber.h.

◆ lc_kyber_enc()

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

inlinestatic

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

Definition at line 859 of file lc_kyber.h.

◆ lc_kyber_enc_kdf()

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

inlinestatic

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

Definition at line 918 of file lc_kyber.h.

◆ lc_kyber_keypair()

static 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 )

inlinestatic

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

Definition at line 740 of file lc_kyber.h.

◆ lc_kyber_keypair_from_seed()

static 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 )

inlinestatic

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.

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

Definition at line 803 of file lc_kyber.h.

◆ lc_kyber_pk_load()

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

inlinestatic

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

Definition at line 410 of file lc_kyber.h.

◆ lc_kyber_pk_ptr()

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

inlinestatic

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

Definition at line 598 of file lc_kyber.h.

◆ lc_kyber_pk_size()

static LC_PURE unsigned int lc_kyber_pk_size ( enum lc_kyber_type kyber_type )

inlinestatic

Return the size of the Kyber public key.

Parameters

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

Returns: requested size

Definition at line 255 of file lc_kyber.h.

◆ lc_kyber_pk_type()

static enum lc_kyber_type lc_kyber_pk_type ( const struct lc_kyber_pk * pk )

inlinestatic

Obtain Kyber type from public key.

Parameters

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

Returns: key type

Definition at line 173 of file lc_kyber.h.

◆ lc_kyber_sk_load()

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

inlinestatic

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

Definition at line 365 of file lc_kyber.h.

◆ lc_kyber_sk_ptr()

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

inlinestatic

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

Definition at line 551 of file lc_kyber.h.

◆ lc_kyber_sk_size()

static LC_PURE unsigned int lc_kyber_sk_size ( enum lc_kyber_type kyber_type )

inlinestatic

Return the size of the Kyber secret key.

Parameters

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

Returns: requested size

Definition at line 219 of file lc_kyber.h.

◆ lc_kyber_sk_type()

static enum lc_kyber_type lc_kyber_sk_type ( const struct lc_kyber_sk * sk )

inlinestatic

Obtain Kyber type from secret key.

Parameters

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

Returns: key type

Definition at line 158 of file lc_kyber.h.

◆ lc_kyber_ss_load()

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

inlinestatic

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

Definition at line 504 of file lc_kyber.h.

◆ lc_kyber_ss_ptr()

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

inlinestatic

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

Definition at line 694 of file lc_kyber.h.

◆ lc_kyber_ss_size()

static LC_PURE unsigned int lc_kyber_ss_size ( enum lc_kyber_type kyber_type )

inlinestatic

Return the size of the Kyber shared secret.

Parameters

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

Returns: requested size

Definition at line 327 of file lc_kyber.h.

◆ lc_kyber_ss_type()

static enum lc_kyber_type lc_kyber_ss_type ( const struct lc_kyber_ss * ss )

inlinestatic

Obtain Kyber type from shared secret.

Parameters

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

Returns: key type

Definition at line 203 of file lc_kyber.h.

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