An elliptic curve offering 128 bits of security and designed for use with the elliptic curve Diffie–Hellman (ECDH) key agreement scheme. It is one of the fastest ECC curves and is not covered by any known patents.
Get Started
$ dotnet add package Curve25519.NetCoreReadme
Curve25519.NetCore
Curve25519.NetCore is a .NET implementation of Curve25519 (X25519) focused on elliptic-curve Diffie-Hellman (ECDH) key agreement.
It provides a compact API for:
- Generating random, clamped private keys
- Deriving public keys
- Computing shared secrets with peer public keys
The library targets modern .NET and follows RFC 7748 guidance by rejecting all-zero shared secrets.
Table of contents
- Requirements
- Installation
- Quick start
- API reference
- Validation and test vectors
- Best practices
- Development
- Security notes
- License
Requirements
- .NET 8 SDK for building/testing this repository.
- Project target framework: .NET 8.
- Dependency:
SecureRandom.NetCore(v2.x) for random private key generation.
Installation
NuGet Package Manager (CLI)
dotnet add package Curve25519.NetCore
Package Manager Console
Install-Package Curve25519.NetCore
NuGet Gallery
Quick start
using System;
using System.Linq;
using Curve25519.NetCore;
var curve25519 = new Curve25519();
// Alice key pair
var alicePrivate = curve25519.CreateRandomPrivateKey();
var alicePublic = curve25519.GetPublicKey(alicePrivate);
// Bob key pair
var bobPrivate = curve25519.CreateRandomPrivateKey();
var bobPublic = curve25519.GetPublicKey(bobPrivate);
// Shared secret derivation
var aliceShared = curve25519.GetSharedSecret(alicePrivate, bobPublic);
var bobShared = curve25519.GetSharedSecret(bobPrivate, alicePublic);
var equal = aliceShared.SequenceEqual(bobShared);
Console.WriteLine($"Shared secrets match: {equal}");
GetSharedSecret(...)returns raw shared secret bytes. In protocol design, derive final session keys from this output using an appropriate KDF.
API reference
Curve25519
Constants
public const int KeySize = 32;
Key generation and clamping
byte[] CreateRandomPrivateKey()
byte[] ClampPrivateKey(byte[] rawKey)
void ClampPrivateKeyInline(byte[] key)
- Private key length must be exactly 32 bytes.
- Clamping is required for valid X25519 private scalars.
CreateRandomPrivateKey()generates 32 random bytes and clamps them before returning.
Public key and agreement methods
byte[] GetPublicKey(byte[] privateKey)
byte[] GetSigningKey(byte[] privateKey)
byte[] GetSharedSecret(byte[] privateKey, byte[] peerPublicKey)
GetPublicKey(...)derives a 32-byte public key.GetSharedSecret(...)performs X25519 with length validation.- An all-zero derived shared secret is rejected with a
CryptographicException.
Validation and test vectors
The test project includes RFC 7748 vector validation and agreement checks, covering:
- Public key generation from known private keys
- Shared secret derivation consistency
- RFC 7748 interoperability values
Run the test suite:
dotnet test Curve25519.NetCore.sln
Best practices
-
Treat private keys as sensitive
- Store and transport private keys securely.
- Keep private key material in memory for as short a time as possible.
-
Always validate key sizes at boundaries
- The API enforces 32-byte key inputs; keep this invariant throughout your application.
-
Use a KDF on shared secrets
- Do not use raw ECDH output directly as a symmetric key in production protocols.
-
Reject invalid agreement outputs
- This library rejects all-zero secrets per RFC 7748 recommendations.
-
Avoid sharing mutable key arrays across threads
- Prefer immutable handling/copies when passing keys between components.
Development
Build
dotnet build Curve25519.NetCore.sln
Test
dotnet test Curve25519.NetCore.sln
Security notes
- The library validates key lengths before cryptographic operations.
- Generated private keys are clamped before use.
- Shared secrets evaluating to all-zero are rejected according to RFC 7748, Section 6.1.
- As with all cryptographic code, review integration choices (KDF, identity/authentication, key lifecycle) against your threat model.
License
MIT. See LICENSE.