ecdh.h File Reference

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

#include "common.h"

Go to the source code of this file.

Macros
#define	QSC_ECDH_PRIVATEKEY_SIZE   32ULL
	The byte size of the secret private-key array.
#define	QSC_ECDH_PUBLICKEY_SIZE   32ULL
	The byte size of the public-key array.
#define	QSC_ECDH_SHAREDSECRET_SIZE   32ULL
	The byte size of the shared secret-key array.
#define	QSC_ECDH_SEED_SIZE   32ULL
	The byte size of the seed array.
#define	QSC_ECDH_ALGNAME   "ECDH"
	The formal algorithm name.

Functions
QSC_EXPORT_API bool	qsc_ecdh_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.
QSC_EXPORT_API void	qsc_ecdh_generate_keypair (uint8_t *publickey, uint8_t *privatekey, bool(*rng_generate)(uint8_t *, size_t))
	Generates public and private keys for the ECDH key encapsulation mechanism.
QSC_EXPORT_API void	qsc_ecdh_generate_seeded_keypair (uint8_t *publickey, uint8_t *privatekey, const uint8_t *seed)
	Generates public and private keys for the ECDH key encapsulation mechanism using a seed.

Detailed Description

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

This header defines the API for the ECDH 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 ECDH
uint8_t pk[QSC_ECDH_PUBLICKEY_SIZE];
uint8_t sk[QSC_ECDH_PRIVATEKEY_SIZE];
uint8_t sec[QSC_ECDH_SHAREDSECRET_SIZE];
 
// Generate the key pair using a seeded generator
qsc_ecdh_generate_seeded_keypair(pk, sk, random_seed);
 
// Derive the shared secret using the private key and an external public key
if (qsc_ecdh_key_exchange(sec, sk, external_public_key) == false)
{
    // Key exchange failed; handle error...
}

Remarks

This ECDH 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:

• Official ECurve25519 ECDH Specificationd25519 Documentation
• Ed25519 Field Operations

Function Documentation

qsc_ecdh_generate_keypair()

QSC_EXPORT_API void qsc_ecdh_generate_keypair	(	uint8_t *	publickey,
		uint8_t *	privatekey,
		bool(*	rng_generate )(uint8_t *, size_t) )

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

Warning

Arrays must be sized to QSC_ECDH_PUBLICKEY_SIZE and QSC_ECDH_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.

qsc_ecdh_generate_seeded_keypair()

QSC_EXPORT_API void qsc_ecdh_generate_seeded_keypair	(	uint8_t *	publickey,
		uint8_t *	privatekey,
		const uint8_t *	seed )

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

Warning

Arrays must be sized to QSC_ECDH_PUBLICKEY_SIZE and QSC_ECDH_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.

qsc_ecdh_key_exchange()

QSC_EXPORT_API bool qsc_ecdh_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_ECDH_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.