ecdh.h File Reference

Contains the primary public API for Elliptic Curve Diffie-Hellman (ECDH) using NIST prime curves. More...

#include "qsccommon.h"

Go to the source code of this file.

Macros
#define	QSC_ECDH_PUBLICKEY_SIZE   64U
	The ECDH public-key size in bytes.
#define	QSC_ECDH_PRIVATEKEY_SIZE   32U
	The ECDH private-key size in bytes.
#define	QSC_ECDH_SHAREDSECRET_SIZE   32U
#define	QSC_ECDH_SEED_SIZE   32U
	The byte size of the seed array.
#define	QSC_ECDH_ALGNAME   "ECDH-P256"
	The formal algorithm name.

Functions
QSC_EXPORT_API void	qsc_ecdh_public_from_private (uint8_t *publickey, const uint8_t *privatekey)
	Derives a public key from an existing private key.
QSC_EXPORT_API bool	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 bool	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.
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.

Detailed Description

Contains the primary public API for Elliptic Curve Diffie-Hellman (ECDH) using NIST prime curves.

This header defines the API for the Elliptic Curve Diffie-Hellman (ECDH) key agreement mechanism over the NIST prime field curves P-256, P-384, and P-521. The implementation supports generation of elliptic curve key pairs (random or seeded) and computation of a shared secret using a peer's public key.

The construction follows the ECDH primitive defined in NIST SP 800-56A and is compatible with the domain parameters specified in FIPS 186-4 / FIPS 186-5. The implementation reuses the underlying field arithmetic and point operations provided by the corresponding NIST ECDSA implementations (P-256, P-384, P-521).

Scalar multiplication is performed in constant time to mitigate timing and side-channel attacks. Public key validation and coordinate checks are expected to conform to the requirements defined in NIST SP 800-56A.

Supported Curves:

• NIST P-256 (secp256r1)
• NIST P-384 (secp384r1)
• NIST P-521 (secp521r1)

Example:

// Example: ECDH key pair generation and shared secret derivation
uint8_t pk[QSC_ECDH_PUBLICKEY_SIZE];
uint8_t sk[QSC_ECDH_PRIVATEKEY_SIZE];
uint8_t sec[QSC_ECDH_SHAREDSECRET_SIZE];
 
// Generate a key pair using a seeded generator
qsc_ecdh_generate_seeded_keypair(pk, sk, random_seed);
 
// Derive a shared secret using the private key and a peer public key
if (qsc_ecdh_key_exchange(sec, sk, external_public_key) == false)
{
    // Key exchange failed; handle error
}

Remarks

This implementation performs standard ECDH as defined by NIST. The shared secret output is the raw x-coordinate of the resulting elliptic curve point and should be processed through a key derivation function (e.g., SHAKE, HKDF, or KMAC) before use in symmetric cryptographic contexts.

Reference Links:

• NIST SP 800-56A Rev. 3: https://csrc.nist.gov/publications/detail/sp/800-56a/rev-3/final
• FIPS 186-5 (Digital Signature Standard - DSS): https://csrc.nist.gov/publications/detail/fips/186/5/final
• SEC 2: Recommended Elliptic Curve Domain Parameters: https://www.secg.org/sec2-v2.pdf
• RFC 5480 (ECC SubjectPublicKeyInfo Format): https://datatracker.ietf.org/doc/html/rfc5480
• RFC 8446 (TLS 1.3 - Supported Groups / ECDH usage): https://datatracker.ietf.org/doc/html/rfc8446

Function Documentation

qsc_ecdh_generate_keypair()

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

Returns

[bool] Returns true on success.

qsc_ecdh_generate_seeded_keypair()

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

Returns

[bool] Returns true on success.

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.

qsc_ecdh_public_from_private()

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

Derives a 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_ECDH_PUBLICKEY_SIZE and QSC_ECDH_PRIVATEKEY_SIZE.

Parameters

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