ML-KEM / CRYSTALS-Kyber Hybrid Mechanism

Functions
static enum lc_kyber_type	lc_kyber_x25519_sk_type (const struct lc_kyber_x25519_sk *sk)
	Obtain Kyber type from secret key.
static enum lc_kyber_type	lc_kyber_x25519_pk_type (const struct lc_kyber_x25519_pk *pk)
	Obtain Kyber type from public key.
static enum lc_kyber_type	lc_kyber_x25519_ct_type (const struct lc_kyber_x25519_ct *ct)
	Obtain Kyber type from Kyber ciphertext.
static enum lc_kyber_type	lc_kyber_x25519_ss_type (const struct lc_kyber_x25519_ss *ss)
	Obtain Kyber type from shared secret.
static LC_PURE unsigned int	lc_kyber_x25519_sk_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber secret key.
static LC_PURE unsigned int	lc_kyber_x25519_pk_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber public key.
static LC_PURE unsigned int	lc_kyber_x25519_ct_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber ciphertext.
static LC_PURE unsigned int	lc_kyber_x25519_ss_size (enum lc_kyber_type kyber_type)
	Return the size of the Kyber shared secret.
static 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.
static 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.
static 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.
static 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.
static 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.
static 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.
static 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.
static 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.
static 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.
static 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.
static 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.
static 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.
static 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.
static int	lc_kyber_x25519_ies_enc (const struct lc_kyber_x25519_pk *pk, struct lc_kyber_x25519_ct *ct, const uint8_t *plaintext, uint8_t *ciphertext, size_t datalen, const uint8_t *aad, size_t aadlen, uint8_t *tag, size_t taglen, struct lc_aead_ctx *aead)
	KyberIES encryption oneshot.
static int	lc_kyber_x25519_ies_enc_init (struct lc_aead_ctx *aead, const struct lc_kyber_x25519_pk *pk, struct lc_kyber_x25519_ct *ct, const uint8_t *aad, size_t aadlen)
	KyberIES encryption stream operation initialization.
static int	lc_kyber_x25519_ies_enc_update (struct lc_aead_ctx *aead, const uint8_t *plaintext, uint8_t *ciphertext, size_t datalen)
	KyberIES encryption stream operation add more data.
static int	lc_kyber_x25519_ies_enc_final (struct lc_aead_ctx *aead, uint8_t *tag, size_t taglen)
	KyberIES encryption stream operation finalization / integrity test.
static int	lc_kyber_x25519_ies_dec (const struct lc_kyber_x25519_sk *sk, const struct lc_kyber_x25519_ct *ct, const uint8_t *ciphertext, uint8_t *plaintext, size_t datalen, const uint8_t *aad, size_t aadlen, const uint8_t *tag, size_t taglen, struct lc_aead_ctx *aead)
	KyberIES decryption oneshot.
static int	lc_kyber_x25519_ies_dec_init (struct lc_aead_ctx *aead, const struct lc_kyber_x25519_sk *sk, const struct lc_kyber_x25519_ct *ct, const uint8_t *aad, size_t aadlen)
	KyberIES decryption stream operation initialization.
static int	lc_kyber_x25519_ies_dec_update (struct lc_aead_ctx *aead, const uint8_t *ciphertext, uint8_t *plaintext, size_t datalen)
	KyberIES decryption stream operation add more data.
static int	lc_kyber_x25519_ies_dec_final (struct lc_aead_ctx *aead, const uint8_t *tag, size_t taglen)
	KyberIES decryption stream operation finalization / integrity test.

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.

Function Documentation

lc_kex_x25519_ake_initiator_init()

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

inlinestatic

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

Definition at line 3063 of file lc_kyber.h.

lc_kex_x25519_ake_initiator_ss()

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

inlinestatic

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

Definition at line 3217 of file lc_kyber.h.

lc_kex_x25519_ake_responder_ss()

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

inlinestatic

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

Definition at line 3137 of file lc_kyber.h.

lc_kex_x25519_uake_initiator_init()

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

inlinestatic

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

Definition at line 2864 of file lc_kyber.h.

lc_kex_x25519_uake_initiator_ss()

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

inlinestatic

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

Definition at line 3002 of file lc_kyber.h.

lc_kex_x25519_uake_responder_ss()

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

inlinestatic

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

Definition at line 2934 of file lc_kyber.h.

lc_kyber_x25519_ct_ptr()

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

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
[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

Definition at line 2571 of file lc_kyber.h.

lc_kyber_x25519_ct_size()

static LC_PURE unsigned int lc_kyber_x25519_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 2203 of file lc_kyber.h.

lc_kyber_x25519_ct_type()

static enum lc_kyber_type lc_kyber_x25519_ct_type ( const struct lc_kyber_x25519_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 2096 of file lc_kyber.h.

lc_kyber_x25519_dec_kdf()

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

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

Definition at line 2811 of file lc_kyber.h.

lc_kyber_x25519_enc_kdf()

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

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

Definition at line 2752 of file lc_kyber.h.

lc_kyber_x25519_ies_dec()

static int lc_kyber_x25519_ies_dec ( const struct lc_kyber_x25519_sk * sk, const struct lc_kyber_x25519_ct * ct, const uint8_t * ciphertext, uint8_t * plaintext, size_t datalen, const uint8_t * aad, size_t aadlen, const uint8_t * tag, size_t taglen, struct lc_aead_ctx * aead )

inlinestatic

KyberIES decryption oneshot.

The implementation supports an in-place data decryption where the plaintext and ciphertext buffer pointers refer to the same memory location.

The function entirely operates on stack memory.

Parameters

[in]	sk	Kyber secret key of data owner
[in]	ct	Kyber ciphertext received from the encryption operation
[in]	ciphertext	Ciphertext data to be encrypted
[out]	plaintext	Buffer of equal size as ciphertext that will be filled with the decryption result
[in]	datalen	Length of the ciphertext buffer
[in]	aad	Additional authenticate data to be processed - this is data which is not encrypted, but considered as part of the authentication.
[in]	aadlen	Length of the AAD buffer
[in]	tag	Buffer with the authentication tag
[in]	taglen	Length of the tag buffer
[in]	aead	Allocated AEAD algorithm - the caller only needs to provide an allocated but otherwise unused instance of an AEAD algorithm. This allows the caller to define the AEAD algorithm type. The caller must zeroize and release the context after completion.

Returns

0 on success, < 0 on error (-EBADMSG on integrity error)

Definition at line 3492 of file lc_kyber.h.

lc_kyber_x25519_ies_dec_final()

static int lc_kyber_x25519_ies_dec_final ( struct lc_aead_ctx * aead, const uint8_t * tag, size_t taglen )

inlinestatic

KyberIES decryption stream operation finalization / integrity test.

The implementation supports an in-place data decryption where the plaintext and ciphertext buffer pointers refer to the same memory location.

The function entirely operates on stack memory.

Parameters

[in]	aead	Allocated AEAD algorithm - the caller only needs to provide an allocated but otherwise unused instance of an AEAD algorithm. This allows the caller to define the AEAD algorithm type. The caller must zeroize and release the context after completion.
[in]	tag	Buffer with the authentication tag
[in]	taglen	Length of the tag buffer

Returns

0 on success, < 0 on error (-EBADMSG on integrity error)

Definition at line 3645 of file lc_kyber.h.

lc_kyber_x25519_ies_dec_init()

static int lc_kyber_x25519_ies_dec_init ( struct lc_aead_ctx * aead, const struct lc_kyber_x25519_sk * sk, const struct lc_kyber_x25519_ct * ct, const uint8_t * aad, size_t aadlen )

inlinestatic

KyberIES decryption stream operation initialization.

The implementation supports an in-place data decryption where the plaintext and ciphertext buffer pointers refer to the same memory location.

The function entirely operates on stack memory.

The aead context is initialized such that it can be used with lc_kyber_x25519_ies_dec_[update|final].

Parameters

[out]	aead	Allocated AEAD algorithm - the caller only needs to provide an allocated but otherwise unused instance of an AEAD algorithm. This allows the caller to define the AEAD algorithm type. The caller must zeroize and release the context after completion.
[in]	sk	Kyber secret key of data owner
[in]	ct	Kyber ciphertext received from the encryption operation
[in]	aad	Additional authenticate data to be processed - this is data which is not encrypted, but considered as part of the authentication.
[in]	aadlen	Length of the AAD buffer

Returns

0 on success, < 0 on error

Definition at line 3562 of file lc_kyber.h.

lc_kyber_x25519_ies_dec_update()

static int lc_kyber_x25519_ies_dec_update ( struct lc_aead_ctx * aead, const uint8_t * ciphertext, uint8_t * plaintext, size_t datalen )

inlinestatic

KyberIES decryption stream operation add more data.

The implementation supports an in-place data decryption where the plaintext and ciphertext buffer pointers refer to the same memory location.

The function entirely operates on stack memory.

Parameters

[in]	aead	Allocated AEAD algorithm - the caller only needs to provide an allocated but otherwise unused instance of an AEAD algorithm. This allows the caller to define the AEAD algorithm type. The caller must zeroize and release the context after completion.
[in]	ciphertext	Ciphertext data to be encrypted
[out]	plaintext	Buffer of equal size as ciphertext that will be filled with the decryption result
[in]	datalen	Length of the ciphertext buffer

Returns

0 on success, < 0 on error

Definition at line 3618 of file lc_kyber.h.

lc_kyber_x25519_ies_enc()

static int lc_kyber_x25519_ies_enc ( const struct lc_kyber_x25519_pk * pk, struct lc_kyber_x25519_ct * ct, const uint8_t * plaintext, uint8_t * ciphertext, size_t datalen, const uint8_t * aad, size_t aadlen, uint8_t * tag, size_t taglen, struct lc_aead_ctx * aead )

inlinestatic

KyberIES encryption oneshot.

The implementation supports an in-place data encryption where the plaintext and ciphertext buffer pointers refer to the same memory location.

The function entirely operates on stack memory.

Parameters

[in]	pk	Kyber public key of data owner
[out]	ct	Kyber ciphertext to be sent to the decryption operation
[in]	plaintext	Plaintext data to be encrypted
[out]	ciphertext	Buffer of equal size as plaintext that will be filled with the encryption result
[in]	datalen	Length of the plaintext buffer
[in]	aad	Additional authenticate data to be processed - this is data which is not encrypted, but considered as part of the authentication.
[in]	aadlen	Length of the AAD buffer
[out]	tag	Buffer that will be filled with the authentication tag
[in]	taglen	Length of the tag buffer
[in]	aead	Allocated AEAD algorithm - the caller only needs to provide an allocated but otherwise unused instance of an AEAD algorithm. This allows the caller to define the AEAD algorithm type. The caller must zeroize and release the context after completion.

Returns

0 on success, < 0 on error

Definition at line 3299 of file lc_kyber.h.

lc_kyber_x25519_ies_enc_final()

static int lc_kyber_x25519_ies_enc_final ( struct lc_aead_ctx * aead, uint8_t * tag, size_t taglen )

inlinestatic

KyberIES encryption stream operation finalization / integrity test.

The implementation supports an in-place data encryption where the plaintext and ciphertext buffer pointers refer to the same memory location.

The function entirely operates on stack memory.

Parameters

[in]	aead	Allocated AEAD algorithm - the caller only needs to provide an allocated but otherwise unused instance of an AEAD algorithm. This allows the caller to define the AEAD algorithm type. The caller must zeroize and release the context after completion.
[out]	tag	Buffer that will be filled with the authentication tag
[in]	taglen	Length of the tag buffer

Returns

0 on success, < 0 on error

Definition at line 3457 of file lc_kyber.h.

lc_kyber_x25519_ies_enc_init()

static int lc_kyber_x25519_ies_enc_init ( struct lc_aead_ctx * aead, const struct lc_kyber_x25519_pk * pk, struct lc_kyber_x25519_ct * ct, const uint8_t * aad, size_t aadlen )

inlinestatic

KyberIES encryption stream operation initialization.

The implementation supports an in-place data encryption where the plaintext and ciphertext buffer pointers refer to the same memory location.

The function entirely operates on stack memory.

The aead context is initialized such that it can be used with lc_kyber_x25519_ies_enc_[update|final].

Parameters

[out]	aead	Allocated AEAD algorithm - the caller only needs to provide an allocated but otherwise unused instance of an AEAD algorithm. This allows the caller to define the AEAD algorithm type. The caller must zeroize and release the context after completion.
[in]	pk	Kyber public key of data owner
[out]	ct	Kyber ciphertext to be sent to the decryption operation
[in]	aad	Additional authenticate data to be processed - this is data which is not encrypted, but considered as part of the authentication.
[in]	aadlen	Length of the AAD buffer

Returns

0 on success, < 0 on error

Definition at line 3373 of file lc_kyber.h.

lc_kyber_x25519_ies_enc_update()

static int lc_kyber_x25519_ies_enc_update ( struct lc_aead_ctx * aead, const uint8_t * plaintext, uint8_t * ciphertext, size_t datalen )

inlinestatic

KyberIES encryption stream operation add more data.

The implementation supports an in-place data encryption where the plaintext and ciphertext buffer pointers refer to the same memory location.

The function entirely operates on stack memory.

Parameters

[in]	aead	Allocated AEAD algorithm - the caller only needs to provide an allocated but otherwise unused instance of an AEAD algorithm. This allows the caller to define the AEAD algorithm type. The caller must zeroize and release the context after completion.
[in]	plaintext	Plaintext data to be encrypted
[out]	ciphertext	Buffer of equal size as plaintext that will be filled with the encryption result
[in]	datalen	Length of the plaintext buffer

Definition at line 3430 of file lc_kyber.h.

lc_kyber_x25519_keypair()

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

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 2686 of file lc_kyber.h.

lc_kyber_x25519_pk_ptr()

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

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
[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

Definition at line 2511 of file lc_kyber.h.

lc_kyber_x25519_pk_size()

static LC_PURE unsigned int lc_kyber_x25519_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 2166 of file lc_kyber.h.

lc_kyber_x25519_pk_type()

static enum lc_kyber_type lc_kyber_x25519_pk_type ( const struct lc_kyber_x25519_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 2080 of file lc_kyber.h.

lc_kyber_x25519_sk_ptr()

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

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
[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

Definition at line 2452 of file lc_kyber.h.

lc_kyber_x25519_sk_size()

static LC_PURE unsigned int lc_kyber_x25519_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 2129 of file lc_kyber.h.

lc_kyber_x25519_sk_type()

static enum lc_kyber_type lc_kyber_x25519_sk_type ( const struct lc_kyber_x25519_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 2064 of file lc_kyber.h.

lc_kyber_x25519_ss_ptr()

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

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
[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

Definition at line 2631 of file lc_kyber.h.

lc_kyber_x25519_ss_size()

static LC_PURE unsigned int lc_kyber_x25519_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 2240 of file lc_kyber.h.

lc_kyber_x25519_ss_type()

static enum lc_kyber_type lc_kyber_x25519_ss_type ( const struct lc_kyber_x25519_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 2112 of file lc_kyber.h.