Functions
enum lc_hqc_type	lc_hqc_sk_type (const struct lc_hqc_sk *sk)
	Obtain HQC type from secret key.
enum lc_hqc_type	lc_hqc_pk_type (const struct lc_hqc_pk *pk)
	Obtain HQC type from public key.
enum lc_hqc_type	lc_hqc_ct_type (const struct lc_hqc_ct *ct)
	Obtain HQC type from HQC ciphertext.
enum lc_hqc_type	lc_hqc_ss_type (const struct lc_hqc_ss *ss)
	Obtain HQC type from shared secret.
LC_PURE unsigned int	lc_hqc_sk_size (enum lc_hqc_type hqc_type)
	Return the size of the HQC secret key.
LC_PURE unsigned int	lc_hqc_pk_size (enum lc_hqc_type hqc_type)
	Return the size of the HQC public key.
LC_PURE unsigned int	lc_hqc_ct_size (enum lc_hqc_type hqc_type)
	Return the size of the HQC ciphertext.
LC_PURE unsigned int	lc_hqc_ss_size (enum lc_hqc_type hqc_type)
	Return the size of the HQC shared secret.
int	lc_hqc_sk_load (struct lc_hqc_sk sk, const uint8_t src_key, size_t src_key_len)
	Load a HQC secret key provided with a buffer into the leancrypto data structure.
int	lc_hqc_pk_load (struct lc_hqc_pk pk, const uint8_t src_key, size_t src_key_len)
	Load a HQC public key provided with a buffer into the leancrypto data structure.
int	lc_hqc_ct_load (struct lc_hqc_ct ct, const uint8_t src_key, size_t src_key_len)
	Load a HQC ciphertext key provided with a buffer into the leancrypto data structure.
int	lc_hqc_ss_load (struct lc_hqc_ss ss, const uint8_t src_key, size_t src_key_len)
	Load a HQC shared secret provided with a buffer into the leancrypto data structure.
int	lc_hqc_sk_ptr (uint8_t *hqc_key, size_t hqc_key_len, struct lc_hqc_sk *sk)
	Obtain the reference to the HQC key and its length.
int	lc_hqc_pk_ptr (uint8_t *hqc_key, size_t hqc_key_len, struct lc_hqc_pk *pk)
	Obtain the reference to the HQC key and its length.
int	lc_hqc_ct_ptr (uint8_t *hqc_ct, size_t hqc_ct_len, struct lc_hqc_ct *ct)
	Obtain the reference to the HQC ciphertext and its length.
int	lc_hqc_ss_ptr (uint8_t *hqc_ss, size_t hqc_ss_len, struct lc_hqc_ss *ss)
	Obtain the reference to the HQC shared secret and its length.
int	lc_hqc_keypair (struct lc_hqc_pk pk, struct lc_hqc_sk sk, struct lc_rng_ctx *rng_ctx, enum lc_hqc_type hqc_type)
	Generates public and private key for IND-CCA2-secure HQC key encapsulation mechanism.
int	lc_hqc_keypair_from_seed (struct lc_hqc_pk pk, struct lc_hqc_sk sk, const uint8_t *seed, size_t seedlen, enum lc_hqc_type hqc_type)
	Generates HQC public and private key from a given seed.
int	lc_hqc_enc (struct lc_hqc_ct ct, struct lc_hqc_ss ss, const struct lc_hqc_pk *pk)
	Key encapsulation.
int	lc_hqc_enc_kdf (struct lc_hqc_ct ct, uint8_t ss, size_t ss_len, const struct lc_hqc_pk *pk)
	Key encapsulation with KDF applied to shared secret.
int	lc_hqc_dec (struct lc_hqc_ss ss, const struct lc_hqc_ct ct, const struct lc_hqc_sk *sk)
	Key decapsulation.
int	lc_hqc_dec_kdf (uint8_t ss, size_t ss_len, const struct lc_hqc_ct ct, const struct lc_hqc_sk *sk)
	Key decapsulation with KDF applied to shared secret.

Detailed Description

HQC API concept

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

lc_hqc.h: This API is the generic API allowing the caller to select which HQC type (HQC-256, -192 or -128) 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_hqc_*_load API calls. All remaining APIs take the information about the HQC 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_hqc_256.h: Direct access to HQC-256.
lc_hqc_192.h: Direct access to HQC-192.
lc_hqc_128.h: Direct access to HQC-128.

Function Documentation

◆ lc_hqc_ct_load()

int lc_hqc_ct_load	(	struct lc_hqc_ct *	ct,
		const uint8_t *	src_key,
		size_t	src_key_len )

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

Parameters

[out]	ct	HQC 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_hqc_ct_ptr()

int lc_hqc_ct_ptr	(	uint8_t **	hqc_ct,
		size_t *	hqc_ct_len,
		struct lc_hqc_ct *	ct )

Obtain the reference to the HQC 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]	hqc_ct	HQC ciphertext pointer
[out]	hqc_ct_len	Length of the ciphertext buffer
[in]	ct	HQC ciphertext from which the references are obtained

Returns: 0 on success, != 0 on error

◆ lc_hqc_ct_size()

LC_PURE unsigned int lc_hqc_ct_size ( enum lc_hqc_type hqc_type )

Return the size of the HQC ciphertext.

Parameters

[in] hqc_type HQC type for which the size is requested

Returns: requested size

◆ lc_hqc_ct_type()

enum lc_hqc_type lc_hqc_ct_type ( const struct lc_hqc_ct * ct )

Obtain HQC type from HQC ciphertext.

Parameters

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

Returns: key type

◆ lc_hqc_dec()

int lc_hqc_dec	(	struct lc_hqc_ss *	ss,
		const struct lc_hqc_ct *	ct,
		const struct lc_hqc_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_hqc_dec_kdf()

int lc_hqc_dec_kdf	(	uint8_t *	ss,
		size_t	ss_len,
		const struct lc_hqc_ct *	ct,
		const struct lc_hqc_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 HQC SS using the KDF derived from the round 3 definition of HQC:

SS <- KMAC256(K = HQC-SS, X = HQC-CT, L = requested SS length,

S = "HQC 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_hqc_enc()

int lc_hqc_enc	(	struct lc_hqc_ct *	ct,
		struct lc_hqc_ss *	ss,
		const struct lc_hqc_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_hqc_enc_kdf()

int lc_hqc_enc_kdf	(	struct lc_hqc_ct *	ct,
		uint8_t *	ss,
		size_t	ss_len,
		const struct lc_hqc_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 HQC SS using the KDF derived from the round 3 definition of HQC:

SS <- KMAC256(K = HQC-SS, X = HQC-CT, L = requested SS length,

S = "HQC 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_hqc_keypair()

int lc_hqc_keypair	(	struct lc_hqc_pk *	pk,
		struct lc_hqc_sk *	sk,
		struct lc_rng_ctx *	rng_ctx,
		enum lc_hqc_type	hqc_type )

Generates public and private key for IND-CCA2-secure HQC 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]	hqc_type	type of the HQC key to generate

Returns: 0 (success) or < 0 on error

◆ lc_hqc_keypair_from_seed()

int lc_hqc_keypair_from_seed	(	struct lc_hqc_pk *	pk,
		struct lc_hqc_sk *	sk,
		const uint8_t *	seed,
		size_t	seedlen,
		enum lc_hqc_type	hqc_type )

Generates HQC 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]	hqc_type	type of the HQC key to generate

Returns: 0 (success) or < 0 on error

◆ lc_hqc_pk_load()

int lc_hqc_pk_load	(	struct lc_hqc_pk *	pk,
		const uint8_t *	src_key,
		size_t	src_key_len )

Load a HQC 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_hqc_pk_ptr()

int lc_hqc_pk_ptr	(	uint8_t **	hqc_key,
		size_t *	hqc_key_len,
		struct lc_hqc_pk *	pk )

Obtain the reference to the HQC 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]	hqc_key	HQC key pointer
[out]	hqc_key_len	Length of the key buffer
[in]	pk	HQC public key from which the references are obtained

Returns: 0 on success, != 0 on error

◆ lc_hqc_pk_size()

LC_PURE unsigned int lc_hqc_pk_size ( enum lc_hqc_type hqc_type )

Return the size of the HQC public key.

Parameters

[in] hqc_type HQC type for which the size is requested

Returns: requested size

◆ lc_hqc_pk_type()

enum lc_hqc_type lc_hqc_pk_type ( const struct lc_hqc_pk * pk )

Obtain HQC type from public key.

Parameters

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

Returns: key type

◆ lc_hqc_sk_load()

int lc_hqc_sk_load	(	struct lc_hqc_sk *	sk,
		const uint8_t *	src_key,
		size_t	src_key_len )

Load a HQC 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_hqc_sk_ptr()

int lc_hqc_sk_ptr	(	uint8_t **	hqc_key,
		size_t *	hqc_key_len,
		struct lc_hqc_sk *	sk )

Obtain the reference to the HQC 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]	hqc_key	HQC key pointer
[out]	hqc_key_len	Length of the key buffer
[in]	sk	HQC secret key from which the references are obtained

Returns: 0 on success, != 0 on error

◆ lc_hqc_sk_size()

LC_PURE unsigned int lc_hqc_sk_size ( enum lc_hqc_type hqc_type )

Return the size of the HQC secret key.

Parameters

[in] hqc_type HQC type for which the size is requested

Returns: requested size

◆ lc_hqc_sk_type()

enum lc_hqc_type lc_hqc_sk_type ( const struct lc_hqc_sk * sk )

Obtain HQC type from secret key.

Parameters

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

Returns: key type

◆ lc_hqc_ss_load()

int lc_hqc_ss_load	(	struct lc_hqc_ss *	ss,
		const uint8_t *	src_key,
		size_t	src_key_len )

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

Parameters

[out]	ss	HQC 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_hqc_ss_ptr()

int lc_hqc_ss_ptr	(	uint8_t **	hqc_ss,
		size_t *	hqc_ss_len,
		struct lc_hqc_ss *	ss )

Obtain the reference to the HQC 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]	hqc_ss	HQC shared secret pointer
[out]	hqc_ss_len	Length of the shared secret buffer
[in]	ss	HQC shared secret from which the references are obtained

Returns: 0 on success, != 0 on error

◆ lc_hqc_ss_size()

LC_PURE unsigned int lc_hqc_ss_size ( enum lc_hqc_type hqc_type )

Return the size of the HQC shared secret.

Parameters

[in] hqc_type HQC type for which the size is requested

Returns: requested size

◆ lc_hqc_ss_type()

enum lc_hqc_type lc_hqc_ss_type ( const struct lc_hqc_ss * ss )

Obtain HQC 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_hqc_ct_load()

◆ lc_hqc_ct_ptr()

◆ lc_hqc_ct_size()

◆ lc_hqc_ct_type()

◆ lc_hqc_dec()

◆ lc_hqc_dec_kdf()

◆ lc_hqc_enc()

◆ lc_hqc_enc_kdf()

◆ lc_hqc_keypair()

◆ lc_hqc_keypair_from_seed()

◆ lc_hqc_pk_load()

◆ lc_hqc_pk_ptr()

◆ lc_hqc_pk_size()

◆ lc_hqc_pk_type()

◆ lc_hqc_sk_load()

◆ lc_hqc_sk_ptr()

◆ lc_hqc_sk_size()

◆ lc_hqc_sk_type()

◆ lc_hqc_ss_load()

◆ lc_hqc_ss_ptr()

◆ lc_hqc_ss_size()

◆ lc_hqc_ss_type()