ML-KEM / CRYSTALS-Kyber Hybrid Mechanism

Functions
enum lc_kyber_type	lc_kyber_x25519_sk_type (const struct lc_kyber_x25519_sk *sk)
	Obtain Kyber type from secret key.
enum lc_kyber_type	lc_kyber_x25519_pk_type (const struct lc_kyber_x25519_pk *pk)
	Obtain Kyber type from public key.
enum lc_kyber_type	lc_kyber_x25519_ct_type (const struct lc_kyber_x25519_ct *ct)
	Obtain Kyber type from Kyber ciphertext.
enum lc_kyber_type	lc_kyber_x25519_ss_type (const struct lc_kyber_x25519_ss *ss)
	Obtain Kyber type from shared secret.
LC_PURE unsigned int	lc_kyber_x25519_sk_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber secret key.
LC_PURE unsigned int	lc_kyber_x25519_pk_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber public key.
LC_PURE unsigned int	lc_kyber_x25519_ct_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber ciphertext.
LC_PURE unsigned int	lc_kyber_x25519_ss_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber shared secret.
int	lc_kyber_x25519_sk_ptr (uint8_t **kyber_key, size_t *kyber_key_len, uint8_t **x25519_key, size_t *x25519_key_len, struct lc_kyber_x25519_sk *sk)
	Obtain the reference to the Kyber key and its length.
int	lc_kyber_x25519_pk_ptr (uint8_t **kyber_key, size_t *kyber_key_len, uint8_t **x25519_key, size_t *x25519_key_len, struct lc_kyber_x25519_pk *pk)
	Obtain the reference to the Kyber key and its length.
int	lc_kyber_x25519_ct_ptr (uint8_t **kyber_ct, size_t *kyber_ct_len, uint8_t **x25519_key, size_t *x25519_key_len, struct lc_kyber_x25519_ct *ct)
	Obtain the reference to the Kyber ciphertext and its length.
int	lc_kyber_x25519_ss_ptr (uint8_t **kyber_ss, size_t *kyber_ss_len, uint8_t **x25519_ss, size_t *x25519_ss_len, struct lc_kyber_x25519_ss *ss)
	Obtain the reference to the Kyber shared secret and its length.
int	lc_kyber_x25519_keypair (struct lc_kyber_x25519_pk *pk, struct lc_kyber_x25519_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_x25519_enc_kdf (struct lc_kyber_x25519_ct *ct, uint8_t *ss, size_t ss_len, const struct lc_kyber_x25519_pk *pk)
	Key encapsulation with KDF applied to shared secret.
int	lc_kyber_x25519_dec_kdf (uint8_t *ss, size_t ss_len, const struct lc_kyber_x25519_ct *ct, const struct lc_kyber_x25519_sk *sk)
	Key decapsulation with KDF applied to shared secret.
int	lc_kex_x25519_uake_initiator_init (struct lc_kyber_x25519_pk *pk_e_i, struct lc_kyber_x25519_ct *ct_e_i, struct lc_kyber_x25519_ss *tk, struct lc_kyber_x25519_sk *sk_e, const struct lc_kyber_x25519_pk *pk_r)
	Initialize unilaterally authenticated key exchange.
int	lc_kex_x25519_uake_responder_ss (struct lc_kyber_x25519_ct *ct_e_r, uint8_t *shared_secret, size_t shared_secret_len, const uint8_t *kdf_nonce, size_t kdf_nonce_len, const struct lc_kyber_x25519_pk *pk_e_i, const struct lc_kyber_x25519_ct *ct_e_i, const struct lc_kyber_x25519_sk *sk_r)
	Initiator's shared secret generation.
int	lc_kex_x25519_uake_initiator_ss (uint8_t *shared_secret, size_t shared_secret_len, const uint8_t *kdf_nonce, size_t kdf_nonce_len, const struct lc_kyber_x25519_ct *ct_e_r, const struct lc_kyber_x25519_ss *tk, const struct lc_kyber_x25519_sk *sk_e)
	Responder's shared secret generation.
int	lc_kex_x25519_ake_initiator_init (struct lc_kyber_x25519_pk *pk_e_i, struct lc_kyber_x25519_ct *ct_e_i, struct lc_kyber_x25519_ss *tk, struct lc_kyber_x25519_sk *sk_e, const struct lc_kyber_x25519_pk *pk_r)
	Initialize authenticated key exchange.
int	lc_kex_x25519_ake_responder_ss (struct lc_kyber_x25519_ct *ct_e_r_1, struct lc_kyber_x25519_ct *ct_e_r_2, uint8_t *shared_secret, size_t shared_secret_len, const uint8_t *kdf_nonce, size_t kdf_nonce_len, const struct lc_kyber_x25519_pk *pk_e_i, const struct lc_kyber_x25519_ct *ct_e_i, const struct lc_kyber_x25519_sk *sk_r, const struct lc_kyber_x25519_pk *pk_i)
	Initiator's shared secret generation.
int	lc_kex_x25519_ake_initiator_ss (uint8_t *shared_secret, size_t shared_secret_len, const uint8_t *kdf_nonce, size_t kdf_nonce_len, const struct lc_kyber_x25519_ct *ct_e_r_1, const struct lc_kyber_x25519_ct *ct_e_r_2, const struct lc_kyber_x25519_ss *tk, const struct lc_kyber_x25519_sk *sk_e, const struct lc_kyber_x25519_sk *sk_i)
	Responder's shared secret generation.
enum lc_kyber_type	lc_kyber_x448_sk_type (const struct lc_kyber_x448_sk *sk)
	Obtain Kyber type from secret key.
enum lc_kyber_type	lc_kyber_x448_pk_type (const struct lc_kyber_x448_pk *pk)
	Obtain Kyber type from public key.
enum lc_kyber_type	lc_kyber_x448_ct_type (const struct lc_kyber_x448_ct *ct)
	Obtain Kyber type from Kyber ciphertext.
enum lc_kyber_type	lc_kyber_x448_ss_type (const struct lc_kyber_x448_ss *ss)
	Obtain Kyber type from shared secret.
LC_PURE unsigned int	lc_kyber_x448_sk_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber secret key.
LC_PURE unsigned int	lc_kyber_x448_pk_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber public key.
LC_PURE unsigned int	lc_kyber_x448_ct_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber ciphertext.
LC_PURE unsigned int	lc_kyber_x448_ss_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber shared secret.
int	lc_kyber_x448_sk_ptr (uint8_t **kyber_key, size_t *kyber_key_len, uint8_t **x448_key, size_t *x448_key_len, struct lc_kyber_x448_sk *sk)
	Obtain the reference to the Kyber key and its length.
int	lc_kyber_x448_pk_ptr (uint8_t **kyber_key, size_t *kyber_key_len, uint8_t **x448_key, size_t *x448_key_len, struct lc_kyber_x448_pk *pk)
	Obtain the reference to the Kyber key and its length.
int	lc_kyber_x448_ct_ptr (uint8_t **kyber_ct, size_t *kyber_ct_len, uint8_t **x448_key, size_t *x448_key_len, struct lc_kyber_x448_ct *ct)
	Obtain the reference to the Kyber ciphertext and its length.
int	lc_kyber_x448_ss_ptr (uint8_t **kyber_ss, size_t *kyber_ss_len, uint8_t **x448_ss, size_t *x448_ss_len, struct lc_kyber_x448_ss *ss)
	Obtain the reference to the Kyber shared secret and its length.
int	lc_kyber_x448_keypair (struct lc_kyber_x448_pk *pk, struct lc_kyber_x448_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_x448_enc_kdf (struct lc_kyber_x448_ct *ct, uint8_t *ss, size_t ss_len, const struct lc_kyber_x448_pk *pk)
	Key encapsulation with KDF applied to shared secret.
int	lc_kyber_x448_dec_kdf (uint8_t *ss, size_t ss_len, const struct lc_kyber_x448_ct *ct, const struct lc_kyber_x448_sk *sk)
	Key decapsulation with KDF applied to shared secret.
int	lc_kex_x448_uake_initiator_init (struct lc_kyber_x448_pk *pk_e_i, struct lc_kyber_x448_ct *ct_e_i, struct lc_kyber_x448_ss *tk, struct lc_kyber_x448_sk *sk_e, const struct lc_kyber_x448_pk *pk_r)
	Initialize unilaterally authenticated key exchange.
int	lc_kex_x448_uake_responder_ss (struct lc_kyber_x448_ct *ct_e_r, uint8_t *shared_secret, size_t shared_secret_len, const uint8_t *kdf_nonce, size_t kdf_nonce_len, const struct lc_kyber_x448_pk *pk_e_i, const struct lc_kyber_x448_ct *ct_e_i, const struct lc_kyber_x448_sk *sk_r)
	Initiator's shared secret generation.
int	lc_kex_x448_uake_initiator_ss (uint8_t *shared_secret, size_t shared_secret_len, const uint8_t *kdf_nonce, size_t kdf_nonce_len, const struct lc_kyber_x448_ct *ct_e_r, const struct lc_kyber_x448_ss *tk, const struct lc_kyber_x448_sk *sk_e)
	Responder's shared secret generation.
int	lc_kex_x448_ake_initiator_init (struct lc_kyber_x448_pk *pk_e_i, struct lc_kyber_x448_ct *ct_e_i, struct lc_kyber_x448_ss *tk, struct lc_kyber_x448_sk *sk_e, const struct lc_kyber_x448_pk *pk_r)
	Initialize authenticated key exchange.
int	lc_kex_x448_ake_responder_ss (struct lc_kyber_x448_ct *ct_e_r_1, struct lc_kyber_x448_ct *ct_e_r_2, uint8_t *shared_secret, size_t shared_secret_len, const uint8_t *kdf_nonce, size_t kdf_nonce_len, const struct lc_kyber_x448_pk *pk_e_i, const struct lc_kyber_x448_ct *ct_e_i, const struct lc_kyber_x448_sk *sk_r, const struct lc_kyber_x448_pk *pk_i)
	Initiator's shared secret generation.
int	lc_kex_x448_ake_initiator_ss (uint8_t *shared_secret, size_t shared_secret_len, const uint8_t *kdf_nonce, size_t kdf_nonce_len, const struct lc_kyber_x448_ct *ct_e_r_1, const struct lc_kyber_x448_ct *ct_e_r_2, const struct lc_kyber_x448_ss *tk, const struct lc_kyber_x448_sk *sk_e, const struct lc_kyber_x448_sk *sk_i)
	Responder's shared secret generation.

Detailed Description

The hybrid KEM implements Kyber KEM together with the X25519 elliptic curve KEX. The use is identical as the Kyber KEM. The only difference is that the transmitted pk and ct has a different content.

The API offered for the hybrid Kyber support can be used as a drop-in replacement. The exception are the API calls to get the pointers to the key members, Kyber ciphertext or shared secret data.

See also the separate Hybrid Kyber documentation providing a mathematical specification.

The hybrid KEM implements Kyber KEM together with the X448 elliptic curve KEX. The use is identical as the Kyber KEM. The only difference is that the transmitted pk and ct has a different content.

The API offered for the hybrid Kyber support can be used as a drop-in replacement. The exception are the API calls to get the pointers to the key members, Kyber ciphertext or shared secret data.

See also the separate Hybrid Kyber documentation providing a mathematical specification.

Note

The APIs for ML-KEM X25519 and X448 are identical. You can switch between both by simply applying a global search and replace of 25519 <-> 448.

Function Documentation

lc_kex_x25519_ake_initiator_init()

int lc_kex_x25519_ake_initiator_init	(	struct lc_kyber_x25519_pk *	pk_e_i,
		struct lc_kyber_x25519_ct *	ct_e_i,
		struct lc_kyber_x25519_ss *	tk,
		struct lc_kyber_x25519_sk *	sk_e,
		const struct lc_kyber_x25519_pk *	pk_r )

Initialize authenticated key exchange.

Parameters

[out]	pk_e_i	initiator's ephemeral public key to be sent to the responder
[out]	ct_e_i	initiator's ephemeral cipher text to be sent to the responder
[out]	tk	KEM shared secret data to be used for the initiator's shared secret generation
[out]	sk_e	initiator's ephemeral secret key to be used for the initiator's shared secret generation
[in]	pk_r	responder's public key

Returns

0 (success) or < 0 on error

lc_kex_x25519_ake_initiator_ss()

int lc_kex_x25519_ake_initiator_ss	(	uint8_t *	shared_secret,
		size_t	shared_secret_len,
		const uint8_t *	kdf_nonce,
		size_t	kdf_nonce_len,
		const struct lc_kyber_x25519_ct *	ct_e_r_1,
		const struct lc_kyber_x25519_ct *	ct_e_r_2,
		const struct lc_kyber_x25519_ss *	tk,
		const struct lc_kyber_x25519_sk *	sk_e,
		const struct lc_kyber_x25519_sk *	sk_i )

Responder's shared secret generation.

Parameters

[out]	shared_secret	Shared secret between initiator and responder
[in]	shared_secret_len	Requested size of the shared secret
[in]	kdf_nonce	An optional nonce that is concatenated at the end of the Kyber KEX-generated data to be inserted into the KDF. If not required, use NULL.
[in]	kdf_nonce_len	Length of the kdf_nonce.
[in]	ct_e_r_1	responder's ephemeral cipher text
[in]	ct_e_r_2	responder's ephemeral cipher text
[in]	tk	KEM shared secret data that was generated during the initator's initialization
[in]	sk_e	initator's ephemeral secret that was generated during the initator's initialization
[in]	sk_i	initator's secret key

Returns

0 (success) or < 0 on error

lc_kex_x25519_ake_responder_ss()

int lc_kex_x25519_ake_responder_ss	(	struct lc_kyber_x25519_ct *	ct_e_r_1,
		struct lc_kyber_x25519_ct *	ct_e_r_2,
		uint8_t *	shared_secret,
		size_t	shared_secret_len,
		const uint8_t *	kdf_nonce,
		size_t	kdf_nonce_len,
		const struct lc_kyber_x25519_pk *	pk_e_i,
		const struct lc_kyber_x25519_ct *	ct_e_i,
		const struct lc_kyber_x25519_sk *	sk_r,
		const struct lc_kyber_x25519_pk *	pk_i )

Initiator's shared secret generation.

Parameters

[out]	ct_e_r_1	responder's ephemeral cipher text to be sent to the initator
[out]	ct_e_r_2	responder's ephemeral cipher text to be sent to the initator
[out]	shared_secret	Shared secret between initiator and responder
[in]	shared_secret_len	Requested size of the shared secret
[in]	kdf_nonce	An optional nonce that is concatenated at the end of the Kyber KEX-generated data to be inserted into the KDF. If not required, use NULL.
[in]	kdf_nonce_len	Length of the kdf_nonce.
[in]	pk_e_i	initator's ephemeral public key
[in]	ct_e_i	initator's ephemeral cipher text
[in]	sk_r	responder's secret key
[in]	pk_i	initator's public key

Returns

0 (success) or < 0 on error

lc_kex_x25519_uake_initiator_init()

int lc_kex_x25519_uake_initiator_init	(	struct lc_kyber_x25519_pk *	pk_e_i,
		struct lc_kyber_x25519_ct *	ct_e_i,
		struct lc_kyber_x25519_ss *	tk,
		struct lc_kyber_x25519_sk *	sk_e,
		const struct lc_kyber_x25519_pk *	pk_r )

Initialize unilaterally authenticated key exchange.

Parameters

[out]	pk_e_i	initiator's ephemeral public key to be sent to the responder
[out]	ct_e_i	initiator's ephemeral cipher text to be sent to the responder
[out]	tk	KEM shared secret data to be used for the initiator's shared secret generation
[out]	sk_e	initiator's ephemeral secret key to be used for the initiator's shared secret generation
[in]	pk_r	responder's public key

Returns

0 (success) or < 0 on error

lc_kex_x25519_uake_initiator_ss()

int lc_kex_x25519_uake_initiator_ss	(	uint8_t *	shared_secret,
		size_t	shared_secret_len,
		const uint8_t *	kdf_nonce,
		size_t	kdf_nonce_len,
		const struct lc_kyber_x25519_ct *	ct_e_r,
		const struct lc_kyber_x25519_ss *	tk,
		const struct lc_kyber_x25519_sk *	sk_e )

Responder's shared secret generation.

Parameters

[out]	shared_secret	Shared secret between initiator and responder
[in]	shared_secret_len	Requested size of the shared secret
[in]	kdf_nonce	An optional nonce that is concatenated at the end of the Kyber KEX-generated data to be inserted into the KDF. If not required, use NULL.
[in]	kdf_nonce_len	Length of the kdf_nonce.
[in]	ct_e_r	responder's ephemeral cipher text
[in]	tk	KEM shared secret data that was generated during the initiator's initialization
[in]	sk_e	initiator's ephemeral secret that was generated during the initiator's initialization

Returns

0 (success) or < 0 on error

lc_kex_x25519_uake_responder_ss()

int lc_kex_x25519_uake_responder_ss	(	struct lc_kyber_x25519_ct *	ct_e_r,
		uint8_t *	shared_secret,
		size_t	shared_secret_len,
		const uint8_t *	kdf_nonce,
		size_t	kdf_nonce_len,
		const struct lc_kyber_x25519_pk *	pk_e_i,
		const struct lc_kyber_x25519_ct *	ct_e_i,
		const struct lc_kyber_x25519_sk *	sk_r )

Initiator's shared secret generation.

Parameters

[out]	ct_e_r	responder's ephemeral cipher text to be sent to the initiator
[out]	shared_secret	Shared secret between initiator and responder
[in]	shared_secret_len	Requested size of the shared secret
[in]	kdf_nonce	An optional nonce that is concatenated at the end of the Kyber KEX-generated data to be inserted into the KDF. If not required, use NULL.
[in]	kdf_nonce_len	Length of the kdf_nonce.
[in]	pk_e_i	initiator's ephemeral public key
[in]	ct_e_i	initiator's ephemeral cipher text
[in]	sk_r	responder's secret key

Returns

0 (success) or < 0 on error

lc_kex_x448_ake_initiator_init()

int lc_kex_x448_ake_initiator_init	(	struct lc_kyber_x448_pk *	pk_e_i,
		struct lc_kyber_x448_ct *	ct_e_i,
		struct lc_kyber_x448_ss *	tk,
		struct lc_kyber_x448_sk *	sk_e,
		const struct lc_kyber_x448_pk *	pk_r )

Initialize authenticated key exchange.

Parameters

[out]	pk_e_i	initiator's ephemeral public key to be sent to the responder
[out]	ct_e_i	initiator's ephemeral cipher text to be sent to the responder
[out]	tk	KEM shared secret data to be used for the initiator's shared secret generation
[out]	sk_e	initiator's ephemeral secret key to be used for the initiator's shared secret generation
[in]	pk_r	responder's public key

Returns

0 (success) or < 0 on error

lc_kex_x448_ake_initiator_ss()

int lc_kex_x448_ake_initiator_ss	(	uint8_t *	shared_secret,
		size_t	shared_secret_len,
		const uint8_t *	kdf_nonce,
		size_t	kdf_nonce_len,
		const struct lc_kyber_x448_ct *	ct_e_r_1,
		const struct lc_kyber_x448_ct *	ct_e_r_2,
		const struct lc_kyber_x448_ss *	tk,
		const struct lc_kyber_x448_sk *	sk_e,
		const struct lc_kyber_x448_sk *	sk_i )

Responder's shared secret generation.

Parameters

[out]	shared_secret	Shared secret between initiator and responder
[in]	shared_secret_len	Requested size of the shared secret
[in]	kdf_nonce	An optional nonce that is concatenated at the end of the Kyber KEX-generated data to be inserted into the KDF. If not required, use NULL.
[in]	kdf_nonce_len	Length of the kdf_nonce.
[in]	ct_e_r_1	responder's ephemeral cipher text
[in]	ct_e_r_2	responder's ephemeral cipher text
[in]	tk	KEM shared secret data that was generated during the initator's initialization
[in]	sk_e	initator's ephemeral secret that was generated during the initator's initialization
[in]	sk_i	initator's secret key

Returns

0 (success) or < 0 on error

lc_kex_x448_ake_responder_ss()

int lc_kex_x448_ake_responder_ss	(	struct lc_kyber_x448_ct *	ct_e_r_1,
		struct lc_kyber_x448_ct *	ct_e_r_2,
		uint8_t *	shared_secret,
		size_t	shared_secret_len,
		const uint8_t *	kdf_nonce,
		size_t	kdf_nonce_len,
		const struct lc_kyber_x448_pk *	pk_e_i,
		const struct lc_kyber_x448_ct *	ct_e_i,
		const struct lc_kyber_x448_sk *	sk_r,
		const struct lc_kyber_x448_pk *	pk_i )

Initiator's shared secret generation.

Parameters

[out]	ct_e_r_1	responder's ephemeral cipher text to be sent to the initator
[out]	ct_e_r_2	responder's ephemeral cipher text to be sent to the initator
[out]	shared_secret	Shared secret between initiator and responder
[in]	shared_secret_len	Requested size of the shared secret
[in]	kdf_nonce	An optional nonce that is concatenated at the end of the Kyber KEX-generated data to be inserted into the KDF. If not required, use NULL.
[in]	kdf_nonce_len	Length of the kdf_nonce.
[in]	pk_e_i	initator's ephemeral public key
[in]	ct_e_i	initator's ephemeral cipher text
[in]	sk_r	responder's secret key
[in]	pk_i	initator's public key

Returns

0 (success) or < 0 on error

lc_kex_x448_uake_initiator_init()

int lc_kex_x448_uake_initiator_init	(	struct lc_kyber_x448_pk *	pk_e_i,
		struct lc_kyber_x448_ct *	ct_e_i,
		struct lc_kyber_x448_ss *	tk,
		struct lc_kyber_x448_sk *	sk_e,
		const struct lc_kyber_x448_pk *	pk_r )

Initialize unilaterally authenticated key exchange.

Parameters

[out]	pk_e_i	initiator's ephemeral public key to be sent to the responder
[out]	ct_e_i	initiator's ephemeral cipher text to be sent to the responder
[out]	tk	KEM shared secret data to be used for the initiator's shared secret generation
[out]	sk_e	initiator's ephemeral secret key to be used for the initiator's shared secret generation
[in]	pk_r	responder's public key

Returns

0 (success) or < 0 on error

lc_kex_x448_uake_initiator_ss()

int lc_kex_x448_uake_initiator_ss	(	uint8_t *	shared_secret,
		size_t	shared_secret_len,
		const uint8_t *	kdf_nonce,
		size_t	kdf_nonce_len,
		const struct lc_kyber_x448_ct *	ct_e_r,
		const struct lc_kyber_x448_ss *	tk,
		const struct lc_kyber_x448_sk *	sk_e )

Responder's shared secret generation.

Parameters

[out]	shared_secret	Shared secret between initiator and responder
[in]	shared_secret_len	Requested size of the shared secret
[in]	kdf_nonce	An optional nonce that is concatenated at the end of the Kyber KEX-generated data to be inserted into the KDF. If not required, use NULL.
[in]	kdf_nonce_len	Length of the kdf_nonce.
[in]	ct_e_r	responder's ephemeral cipher text
[in]	tk	KEM shared secret data that was generated during the initiator's initialization
[in]	sk_e	initiator's ephemeral secret that was generated during the initiator's initialization

Returns

0 (success) or < 0 on error

lc_kex_x448_uake_responder_ss()

int lc_kex_x448_uake_responder_ss	(	struct lc_kyber_x448_ct *	ct_e_r,
		uint8_t *	shared_secret,
		size_t	shared_secret_len,
		const uint8_t *	kdf_nonce,
		size_t	kdf_nonce_len,
		const struct lc_kyber_x448_pk *	pk_e_i,
		const struct lc_kyber_x448_ct *	ct_e_i,
		const struct lc_kyber_x448_sk *	sk_r )

Initiator's shared secret generation.

Parameters

[out]	ct_e_r	responder's ephemeral cipher text to be sent to the initiator
[out]	shared_secret	Shared secret between initiator and responder
[in]	shared_secret_len	Requested size of the shared secret
[in]	kdf_nonce	An optional nonce that is concatenated at the end of the Kyber KEX-generated data to be inserted into the KDF. If not required, use NULL.
[in]	kdf_nonce_len	Length of the kdf_nonce.
[in]	pk_e_i	initiator's ephemeral public key
[in]	ct_e_i	initiator's ephemeral cipher text
[in]	sk_r	responder's secret key

Returns

0 (success) or < 0 on error

lc_kyber_x25519_ct_ptr()

int lc_kyber_x25519_ct_ptr	(	uint8_t **	kyber_ct,
		size_t *	kyber_ct_len,
		uint8_t **	x25519_key,
		size_t *	x25519_key_len,
		struct lc_kyber_x25519_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
[out]	x25519_key	X25519 ephermeral public key pointer
[out]	x25519_key_len	X25519 of the key buffer
[in]	ct	Hybrid ciphertext from which the references are obtained

Returns

0 on success, != 0 on error

lc_kyber_x25519_ct_size()

LC_PURE unsigned int lc_kyber_x25519_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_x25519_ct_type()

enum lc_kyber_type lc_kyber_x25519_ct_type

(

const struct lc_kyber_x25519_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_x25519_dec_kdf()

int lc_kyber_x25519_dec_kdf	(	uint8_t *	ss,
		size_t	ss_len,
		const struct lc_kyber_x25519_ct *	ct,
		const struct lc_kyber_x25519_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 || X25519-SS, X = Kyber-CT,
          L = requested SS length, S = "Kyber KEM Double 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_x25519_enc_kdf()

int lc_kyber_x25519_enc_kdf	(	struct lc_kyber_x25519_ct *	ct,
		uint8_t *	ss,
		size_t	ss_len,
		const struct lc_kyber_x25519_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 || X25519-SS, X = Kyber-CT,
              L = requested SS length, S = "Kyber KEM Double SS")

Note

The concatenatino of Kyber-SS || ECC-SS complies with SP800-56C rev 2 chapter 2 defining the hybrid shared secret of the form Z' = Z || T where Z is the "standard shared secret" from Kyber followed by the auxiliary shared secret T that has been generated by some other method.

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

int lc_kyber_x25519_keypair	(	struct lc_kyber_x25519_pk *	pk,
		struct lc_kyber_x25519_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_x25519_pk_ptr()

int lc_kyber_x25519_pk_ptr	(	uint8_t **	kyber_key,
		size_t *	kyber_key_len,
		uint8_t **	x25519_key,
		size_t *	x25519_key_len,
		struct lc_kyber_x25519_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
[out]	x25519_key	X25519 key pointer
[out]	x25519_key_len	X25519 of the key buffer
[in]	pk	Hybrid public key from which the references are obtained

Returns

0 on success, != 0 on error

lc_kyber_x25519_pk_size()

LC_PURE unsigned int lc_kyber_x25519_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_x25519_pk_type()

enum lc_kyber_type lc_kyber_x25519_pk_type

(

const struct lc_kyber_x25519_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_x25519_sk_ptr()

int lc_kyber_x25519_sk_ptr	(	uint8_t **	kyber_key,
		size_t *	kyber_key_len,
		uint8_t **	x25519_key,
		size_t *	x25519_key_len,
		struct lc_kyber_x25519_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
[out]	x25519_key	X25519 key pointer
[out]	x25519_key_len	X25519 of the key buffer
[in]	sk	Hybrid secret key from which the references are obtained

Returns

0 on success, != 0 on error

lc_kyber_x25519_sk_size()

LC_PURE unsigned int lc_kyber_x25519_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_x25519_sk_type()

enum lc_kyber_type lc_kyber_x25519_sk_type

(

const struct lc_kyber_x25519_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_x25519_ss_ptr()

int lc_kyber_x25519_ss_ptr	(	uint8_t **	kyber_ss,
		size_t *	kyber_ss_len,
		uint8_t **	x25519_ss,
		size_t *	x25519_ss_len,
		struct lc_kyber_x25519_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
[out]	x25519_ss	X25519 shared secret pointer
[out]	x25519_ss_len	X25519 of the shared secret buffer
[in]	ss	Hybrid shared secret from which the references are obtained

Returns

0 on success, != 0 on error

lc_kyber_x25519_ss_size()

LC_PURE unsigned int lc_kyber_x25519_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_x25519_ss_type()

enum lc_kyber_type lc_kyber_x25519_ss_type

(

const struct lc_kyber_x25519_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

lc_kyber_x448_ct_ptr()

int lc_kyber_x448_ct_ptr	(	uint8_t **	kyber_ct,
		size_t *	kyber_ct_len,
		uint8_t **	x448_key,
		size_t *	x448_key_len,
		struct lc_kyber_x448_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
[out]	x448_key	X448 ephermeral public key pointer
[out]	x448_key_len	X448 of the key buffer
[in]	ct	Hybrid ciphertext from which the references are obtained

Returns

0 on success, != 0 on error

lc_kyber_x448_ct_size()

LC_PURE unsigned int lc_kyber_x448_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_x448_ct_type()

enum lc_kyber_type lc_kyber_x448_ct_type

(

const struct lc_kyber_x448_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_x448_dec_kdf()

int lc_kyber_x448_dec_kdf	(	uint8_t *	ss,
		size_t	ss_len,
		const struct lc_kyber_x448_ct *	ct,
		const struct lc_kyber_x448_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 || X448-SS, X = Kyber-CT,
          L = requested SS length, S = "Kyber KEM Double 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_x448_enc_kdf()

int lc_kyber_x448_enc_kdf	(	struct lc_kyber_x448_ct *	ct,
		uint8_t *	ss,
		size_t	ss_len,
		const struct lc_kyber_x448_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 || X448-SS, X = Kyber-CT,
              L = requested SS length, S = "Kyber KEM Double SS")

Note

The concatenatino of Kyber-SS || ECC-SS complies with SP800-56C rev 2 chapter 2 defining the hybrid shared secret of the form Z' = Z || T where Z is the "standard shared secret" from Kyber followed by the auxiliary shared secret T that has been generated by some other method.

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

int lc_kyber_x448_keypair	(	struct lc_kyber_x448_pk *	pk,
		struct lc_kyber_x448_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_x448_pk_ptr()

int lc_kyber_x448_pk_ptr	(	uint8_t **	kyber_key,
		size_t *	kyber_key_len,
		uint8_t **	x448_key,
		size_t *	x448_key_len,
		struct lc_kyber_x448_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
[out]	x448_key	X448 key pointer
[out]	x448_key_len	X448 of the key buffer
[in]	pk	Hybrid public key from which the references are obtained

Returns

0 on success, != 0 on error

lc_kyber_x448_pk_size()

LC_PURE unsigned int lc_kyber_x448_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_x448_pk_type()

enum lc_kyber_type lc_kyber_x448_pk_type

(

const struct lc_kyber_x448_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_x448_sk_ptr()

int lc_kyber_x448_sk_ptr	(	uint8_t **	kyber_key,
		size_t *	kyber_key_len,
		uint8_t **	x448_key,
		size_t *	x448_key_len,
		struct lc_kyber_x448_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
[out]	x448_key	X448 key pointer
[out]	x448_key_len	X448 of the key buffer
[in]	sk	Hybrid secret key from which the references are obtained

Returns

0 on success, != 0 on error

lc_kyber_x448_sk_size()

LC_PURE unsigned int lc_kyber_x448_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_x448_sk_type()

enum lc_kyber_type lc_kyber_x448_sk_type

(

const struct lc_kyber_x448_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_x448_ss_ptr()

int lc_kyber_x448_ss_ptr	(	uint8_t **	kyber_ss,
		size_t *	kyber_ss_len,
		uint8_t **	x448_ss,
		size_t *	x448_ss_len,
		struct lc_kyber_x448_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
[out]	x448_ss	X448 shared secret pointer
[out]	x448_ss_len	X448 of the shared secret buffer
[in]	ss	Hybrid shared secret from which the references are obtained

Returns

0 on success, != 0 on error

lc_kyber_x448_ss_size()

LC_PURE unsigned int lc_kyber_x448_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_x448_ss_type()

enum lc_kyber_type lc_kyber_x448_ss_type

(

const struct lc_kyber_x448_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