eddh.h File Reference

Contains the primary public API for the Edwards Elliptic Curve Diffie-Hellman key exchange. More...

#include "qsccommon.h"

Go to the source code of this file.

Macros
#define	QSC_EDDH_PUBLICKEY_SIZE   32U
	The EDDH public-key size in bytes.
#define	QSC_EDDH_PRIVATEKEY_SIZE   32U
	The EDDH private-key size in bytes.
#define	QSC_EDDH_SHAREDSECRET_SIZE   32U
#define	QSC_EDDH_SEED_SIZE   32U
	The byte size of the seed array.
#define	QSC_EDDH_ALGNAME   "EDDH-P25519"
	The formal algorithm name.

Functions
QSC_EXPORT_API void	qsc_eddh_public_from_private (uint8_t *publickey, const uint8_t *privatekey)
	Derives an X25519 public key from an existing private key.
QSC_EXPORT_API bool	qsc_eddh_generate_keypair (uint8_t *publickey, uint8_t *privatekey, bool(*rng_generate)(uint8_t *, size_t))
	Generates public and private keys for the EDDH key encapsulation mechanism.
QSC_EXPORT_API bool	qsc_eddh_generate_seeded_keypair (uint8_t *publickey, uint8_t *privatekey, const uint8_t *seed)
	Generates public and private keys for the EDDH key encapsulation mechanism using a seed.
QSC_EXPORT_API bool	qsc_eddh_key_exchange (uint8_t *secret, const uint8_t *privatekey, const uint8_t *publickey)
	Decapsulates the shared secret for a given cipher-text using a private-key.

Detailed Description

Contains the primary public API for the Edwards Elliptic Curve Diffie-Hellman key exchange.

This header defines the API for the EDDH key encapsulation mechanism using the Curve25519/Ed25519 elliptic curve. It provides functions for generating key pairs (either randomly or seeded) and for performing the key exchange operation (decapsulation) to derive a shared secret.

The implementation is based on established protocols for elliptic curve cryptography and leverages the underlying field arithmetic and curve operations of the Ed25519 signature scheme. It is designed for secure key encapsulation in cryptographic protocols and has been optimized for performance and constant-time execution to mitigate side-channel attacks.

Example:

// An example of key-pair creation and shared secret derivation using EDDH
uint8_t pk[QSC_EDDH_PUBLICKEY_SIZE];
uint8_t sk[QSC_EDDH_PRIVATEKEY_SIZE];
uint8_t sec[QSC_EDDH_SHAREDSECRET_SIZE];
 
// Generate the key pair using a seeded generator
qsc_eddh_generate_seeded_keypair(pk, sk, random_seed);
 
// Derive the shared secret using the private key and an external public key
if (qsc_eddh_key_exchange(sec, sk, external_public_key) == false)
{
    // Key exchange failed; handle error...
}

Remarks

This EDDH implementation uses the Curve25519/Ed25519 elliptic curve for performing key exchange operations. It is intended for secure key encapsulation and is suitable for cryptographic protocols requiring robust, constant-time elliptic curve operations.

Reference Links:

• Adapted from libsodium source by Frank Denis
• Official ECurve25519 EDDH Specificationd25519 Documentation
• Ed25519 Field Operations

Function Documentation

qsc_eddh_generate_keypair()

QSC_EXPORT_API bool qsc_eddh_generate_keypair	(	uint8_t *	publickey,
		uint8_t *	privatekey,
		bool(*	rng_generate )(uint8_t *, size_t) )

Generates public and private keys for the EDDH key encapsulation mechanism.

Warning

Arrays must be sized to QSC_EDDH_PUBLICKEY_SIZE and QSC_EDDH_PRIVATEKEY_SIZE.

Parameters

publickey	[uint8_t*] Pointer to the output public-key array.
privatekey	[uint8_t*] Pointer to the output private-key array.
rng_generate	[bool (*)(uint8_t*, size_t)] Pointer to the random generator function.

Returns

[bool] Returns true on success.

qsc_eddh_generate_seeded_keypair()

QSC_EXPORT_API bool qsc_eddh_generate_seeded_keypair	(	uint8_t *	publickey,
		uint8_t *	privatekey,
		const uint8_t *	seed )

Generates public and private keys for the EDDH key encapsulation mechanism using a seed.

Warning

Arrays must be sized to QSC_EDDH_PUBLICKEY_SIZE and QSC_EDDH_PRIVATEKEY_SIZE.

Parameters

publickey	[uint8_t*] Pointer to the output public-key array.
privatekey	[uint8_t*] Pointer to the output private-key array.
seed	[const uint8_t*] Pointer to the random seed.

Returns

[bool] Returns true on success.

qsc_eddh_key_exchange()

QSC_EXPORT_API bool qsc_eddh_key_exchange	(	uint8_t *	secret,
		const uint8_t *	privatekey,
		const uint8_t *	publickey )

Decapsulates the shared secret for a given cipher-text using a private-key.

Warning

The shared secret array must be sized to QSC_EDDH_SHAREDSECRET_SIZE.

Parameters

secret	[uint8_t*] Pointer to the shared secret key array.
privatekey	[const uint8_t*] Pointer to the private-key array.
publickey	[const uint8_t*] Pointer to the public-key array.

Returns

[bool] Returns true on success.

qsc_eddh_public_from_private()

QSC_EXPORT_API void qsc_eddh_public_from_private	(	uint8_t *	publickey,
		const uint8_t *	privatekey )

Derives an X25519 public key from an existing private key.

The private key is interpreted as 32 raw bytes. Scalar clamping is applied internally during public key derivation, as specified by RFC 7748.

This function is intended for use when importing or reconstructing keys from external representations such as PKCS#8 or application-defined storage.

Warning

Arrays must be sized to QSC_EDDH_PUBLICKEY_SIZE and QSC_EDDH_PRIVATEKEY_SIZE.

Parameters

publickey	[uint8_t*] Pointer to the output public-key array.
privatekey:[const	uint8_t*] Pointer to the input private-key array.