ecdsa.h File Reference

Contains the public API for the Elliptic Curve Digital Signature Algorithm implementation over the NIST prime-field curves P-256, P-384, and P-521. More...

#include "qsccommon.h"

Go to the source code of this file.

Macros
#define	QSC_ECDSA_SIGNATURE_SIZE   132U
	The byte size of the signature array (r[66] || s[66]).
#define	QSC_ECDSA_PRIVATEKEY_SIZE   198U
	The byte size of the private key array (seed[66] || Qx[66] || Qy[66]).
#define	QSC_ECDSA_PUBLICKEY_SIZE   132U
	The byte size of the public key array (Qx[66] || Qy[66], big-endian).
#define	QSC_ECDSA_SEED_SIZE   66ULL
	The byte size of the random seed / private scalar input array.
#define	QSC_ECDSA_ALGNAME   "ECDSAP521"
	The formal algorithm name.
#define	QSC_ECDSA_SEC1_PUBLICKEY_SIZE   133U
	SEC 1 uncompressed EC point byte length for P-521.
#define	QSC_ECDSA_SPKI_DER_SIZE   158U
	SubjectPublicKeyInfo DER byte length for id-ecPublicKey + secp521r1.
#define	QSC_ECDSA_SIGNATURE_DER_MAX_SIZE   139U
	Maximum DER-encoded ECDSA signature size for P-521.

Functions
QSC_EXPORT_API void	qsc_ecdsa_publickey_to_sec1 (uint8_t *secpub, const uint8_t *publickey)
	Convert a raw public key (Qx || Qy) to SEC 1 uncompressed point form.
QSC_EXPORT_API int32_t	qsc_ecdsa_publickey_from_privatekey (uint8_t *publickey, const uint8_t *privatekey)
	Derive a P-256 public key from a raw private scalar.
QSC_EXPORT_API bool	qsc_ecdsa_publickey_from_sec1 (uint8_t *publickey, const uint8_t *secpub)
	Convert a SEC 1 uncompressed point to the library raw public-key form.
QSC_EXPORT_API bool	qsc_ecdsa_generate_seeded_keypair (uint8_t *publickey, uint8_t *privatekey, const uint8_t *seed)
	Generate a P-256 public/private key pair from a 32-byte seed.
QSC_EXPORT_API bool	qsc_ecdsa_generate_keypair (uint8_t *publickey, uint8_t *privatekey, bool(*rng_generate)(uint8_t *, size_t))
	Generate a P-256 public/private key pair using a caller-supplied RNG.
QSC_EXPORT_API bool	qsc_ecdsa_sign (uint8_t *signedmsg, size_t *smsglen, const uint8_t *message, size_t msglen, const uint8_t *privatekey)
	Sign a message with a P-256 private key.
QSC_EXPORT_API bool	qsc_ecdsa_sign_scalar (uint8_t *signedmsg, size_t *smsglen, const uint8_t *message, size_t msglen, const uint8_t *privatekey)
	Sign a message with a P-256 private key, used primarily for RFC KAT testing).
QSC_EXPORT_API bool	qsc_ecdsa_verify (uint8_t *message, size_t *msglen, const uint8_t *signedmsg, size_t smsglen, const uint8_t *publickey)
	Verify a P-256 ECDSA signature and recover the message.

Detailed Description

Contains the public API for the Elliptic Curve Digital Signature Algorithm implementation over the NIST prime-field curves P-256, P-384, and P-521.

Contains the primary public API for the ECDSA asymmetric signature scheme implementation.

This header defines the external interface to the QSC ECDSA implementation. The module supports one NIST prime-field parameter set selected at compile time. The supported parameter sets are P-256, P-384, and P-521, corresponding to the widely deployed secp256r1, secp384r1, and secp521r1 domain parameters. The active curve selection determines all encoded key, scalar, coordinate, and signature lengths through the QSC_ECDSA_*_SIZE constants defined in this header.

The implementation exposes functions for key-pair generation, public-key derivation from a private scalar, deterministic and randomized signing, signature verification, public-key encoding and decoding, and DER conversion of ECDSA signatures. Public keys are represented internally in raw affine form as the concatenation Qx || Qy, where each coordinate is a fixed-width big-endian integer whose width is determined by the active parameter set. Signatures are represented in raw form as r || s, where both values are fixed-width big-endian integers of the active subgroup order size.

The private-key container used by the high-level API is a serialized structure of the form seed || Qx || Qy. The seed field contains the curve-sized private scalar input in big-endian form. The public coordinates stored after the seed are the affine public key corresponding to that scalar. This format allows the module to retain the private scalar together with its associated public key in a compact fixed-size buffer. Functions that derive a public key directly from a private scalar expect the scalar alone, encoded as a curve-sized big-endian integer, rather than the full private-key container.

The module supports conversion between the internal raw public-key format and SEC 1 uncompressed point encoding. In SEC 1 form, a public key is serialized as the uncompressed point tag 0x04 followed by the fixed-width big-endian x and y affine coordinates. The module also supports conversion between the internal raw public-key form and the X.509 SubjectPublicKeyInfo DER encoding for the selected curve. These conversion functions are intended for interoperability with certificate processing, public-key exchange, and other protocol layers that use standard ASN.1 encodings.

Signature conversion functions are provided for the ECDSA ASN.1 DER representation. The internal raw signature form is always fixed width and consists of the direct concatenation of r and s. The DER representation instead encodes r and s as signed ASN.1 INTEGER values wrapped in a SEQUENCE. Because DER INTEGER values may require a leading zero octet when the most significant bit would otherwise indicate a negative value, the encoded DER signature length is variable and depends on the specific signature values. The maximum DER size is therefore parameter-set dependent and is defined by QSC_ECDSA_SIGNATURE_DER_MAX_SIZE.

The implementation is intended for message authentication and public verification in systems that require standardized NIST elliptic-curve signatures. Verification functions recover the appended message from the signed-message format used by the QSC API, validate the signature, and return the recovered message on success. Signing functions produce the fixed-size raw signature followed by the original message, allowing the signed-message buffer to be processed as a single serialized object.

Deterministic signing support is included to enable reproducible signatures for known-answer testing and standards alignment. In deterministic mode, the ephemeral nonce is derived from the private scalar and message digest rather than obtained from an external random source. This behavior is required for compatibility with official RFC 6979 test vectors for the supported curves. Randomized signing is also supported through the standard high-level API when the implementation is configured to use an approved random generator. The exact digest and nonce-generation behavior is curve-dependent and must remain aligned with the active parameter-set implementation.

All externally visible byte arrays use big-endian encoding. All buffers passed to the API must be correctly sized for the active curve selection. The caller is responsible for supplying valid output buffers and, where required, a cryptographically secure random generator. Private-key material should be treated as sensitive and cleared from memory by the caller when no longer required. Public-key and signature validation is performed by the relevant decode and verify functions, but callers must still ensure that buffer lengths and calling conventions are consistent with the selected parameter set.

This header declares only the public interface and associated size constants. Curve-specific field arithmetic, scalar arithmetic, point operations, deterministic nonce generation, and internal validation routines are implemented in the corresponding ECDSA base modules for the selected parameter set.

This header defines the API for the ECDSA (Elliptic Curve Digital Signature Algorithm) asymmetric signature scheme, operating over the Ed25519 elliptic curve. It provides functions for generating key pairs (either randomly or via a seeded generator), signing messages, and verifying signatures.

Example:

// An example of key-pair creation, signing, and verification using ECDSA
#define MSGLEN 32
uint8_t pk[QSC_ECDSA_PUBLICKEY_SIZE];
uint8_t sk[QSC_ECDSA_SECRETKEY_SIZE];
uint8_t msg[32];
uint8_t smsg[QSC_ECDSA_SIGNATURE_SIZE + MSGLEN];
uint8_t rmsg[32];
 
uint32_t rmsglen = 0;
uint32_t smsglen = 0;
 
// Create the public and secret keys using a seeded generator
qsc_eddsa_generate_seeded_keypair(pk, sk, random_seed);
// Sign the message; the signature is prepended to the message
qsc_eddsa_sign(smsg, &smsglen, msg, MSGLEN, sk);
// Verify the signature and retrieve the message bytes
if (qsc_eddsa_verify(rmsg, &rmsglen, smsg, smsglen, pk) != true)
{
    // Authentication failed; handle error.
}

Remarks

This ECDSA implementation utilizes the Ed25519 elliptic curve along with its underlying field arithmetic over the prime field defined by 2^255 - 19. It supports standard digital signature operations including key pair generation, signing, and verification. The design emphasizes constant-time execution to mitigate timing attacks and is suitable for secure applications in modern cryptographic protocols.

Reference Links

• Official Ed25519 Documentation
• Curve25519 ECDH Specification
• Ed25519 Field Arithmetic Details

Function Documentation

qsc_ecdsa_generate_keypair()

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

Generate a P-256 public/private key pair using a caller-supplied RNG.

Fills a 32-byte seed from rng_generate, then calls qsc_ecdsa_generate_seeded_keypair. The seed is erased from stack memory before returning.

Warning

Arrays must be sized to QSC_ECDSA_PUBLICKEY_SIZE and QSC_ECDSA_PRIVATEKEY_SIZE respectively.

Parameters

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

Returns

[bool] Returns true on success.

qsc_ecdsa_generate_seeded_keypair()

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

Generate a P-256 public/private key pair from a 32-byte seed.

Derives the private scalar d = SHA-256(seed) mod n, computes the public key Q = d*G, and stores both. This function is deterministic: the same seed always produces the same key pair.

Warning

Arrays must be sized to QSC_ECDSA_PUBLICKEY_SIZE and QSC_ECDSA_PRIVATEKEY_SIZE respectively.

Parameters

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

Returns

[bool] Returns true on success.

qsc_ecdsa_publickey_from_privatekey()

QSC_EXPORT_API int32_t qsc_ecdsa_publickey_from_privatekey	(	uint8_t *	publickey,
		const uint8_t *	privatekey )

Derive a P-256 public key from a raw private scalar.

This function derives the affine public point Q = dG from a 32-byte big-endian private scalar and serializes the result as the raw public-key form Qx || Qy.

The private scalar must be in the range [1, n - 1], where n is the order of the P-256 base point.

Parameters

publickey	[uint8_t*] Output buffer receiving the 64-byte public key.
privatekey	[const uint8_t*] Input 32-byte private scalar.

Returns

[int32_t] Returns 0 on success, or a negative error code on failure.

qsc_ecdsa_publickey_from_sec1()

QSC_EXPORT_API bool qsc_ecdsa_publickey_from_sec1	(	uint8_t *	publickey,
		const uint8_t *	secpub )

Convert a SEC 1 uncompressed point to the library raw public-key form.

Parameters

publickey	[uint8_t*] Output raw public key of 64 bytes.
secpub	[const uint8_t*] Input SEC 1 public key of 65 bytes.

Returns

[bool] Returns true on success.

qsc_ecdsa_publickey_to_sec1()

QSC_EXPORT_API void qsc_ecdsa_publickey_to_sec1	(	uint8_t *	secpub,
		const uint8_t *	publickey )

Convert a raw public key (Qx || Qy) to SEC 1 uncompressed point form.

Parameters

secpub	[uint8_t*] Output buffer of 65 bytes.
publickey	[const uint8_t*] Input raw public key of 64 bytes.

qsc_ecdsa_sign()

QSC_EXPORT_API bool qsc_ecdsa_sign	(	uint8_t *	signedmsg,
		size_t *	smsglen,
		const uint8_t *	message,
		size_t	msglen,
		const uint8_t *	privatekey )

Sign a message with a P-256 private key.

Computes a deterministic ECDSA signature (RFC 6979, HMAC-SHA256) over the SHA-256 digest of the message, then writes the 64-byte signature followed by the message into signedmsg. On success *smsglen = msglen + 64.

Warning

signedmsg must be at least msglen + QSC_ECDSA_SIGNATURE_SIZE bytes.

Parameters

signedmsg	[uint8_t*] Pointer to the signed-message output array.
smsglen	[size_t*] Pointer to the signed-message length output.
message	[const uint8_t*] Pointer to the message to sign.
msglen	[size_t] Message length in bytes.
privatekey	[const uint8_t*] Pointer to the 96-byte private key array.

Returns

[bool] Returns true on success.

qsc_ecdsa_sign_scalar()

QSC_EXPORT_API bool qsc_ecdsa_sign_scalar	(	uint8_t *	signedmsg,
		size_t *	smsglen,
		const uint8_t *	message,
		size_t	msglen,
		const uint8_t *	privatekey )

Sign a message with a P-256 private key, used primarily for RFC KAT testing).

Computes a deterministic ECDSA signature using the private key scalar d, (RFC KATs) then writes the 64-byte signature followed by the message into signedmsg. On success *smsglen = msglen + 64.

Warning

signedmsg must be at least msglen + QSC_ECDSA_SIGNATURE_SIZE bytes.

Parameters

signedmsg	[uint8_t*] Pointer to the signed-message output array.
smsglen	[size_t*] Pointer to the signed-message length output.
message	[const uint8_t*] Pointer to the message to sign.
msglen	[size_t] Message length in bytes.
privatekey	[const uint8_t*] Pointer to the 96-byte private key array.

Returns

[bool] Returns true on success.

qsc_ecdsa_verify()

QSC_EXPORT_API bool qsc_ecdsa_verify	(	uint8_t *	message,
		size_t *	msglen,
		const uint8_t *	signedmsg,
		size_t	smsglen,
		const uint8_t *	publickey )

Verify a P-256 ECDSA signature and recover the message.

Parses the 64-byte signature prepended to signedmsg, validates r and s are in [1, n-1], verifies that the public key lies on the curve, and checks the ECDSA equation. On success the message bytes are copied into message and *msglen is set. On failure message is zeroed and *msglen is set to 0.

Parameters

message	[uint8_t*] Pointer to the recovered message output array.
msglen	[size_t*] Pointer to the recovered message length.
signedmsg	[const uint8_t*] Pointer to the signed-message input array.
smsglen	[size_t] Total signed-message length (signature + message).
publickey	[const uint8_t*] Pointer to the 64-byte public verification-key array.

Returns

[bool] Returns true if the signature is valid, false otherwise.