NetCrypto 1.1.0

NetCrypto

Unified cryptographic primitives for the NetCid/NetDid library stack: EdDSA, ECDSA (NIST curves and secp256k1, including recoverable), BLS12-381, BBS selective-disclosure signatures, X25519/ECDH, KDFs, AEADs, hashing (including Keccak-256), a key model with multibase/multicodec encoding, signing and key-store abstractions, and JWK conversion.

NetCrypto is the single home for every cryptographic primitive in the stack, behind stable interfaces, so that no domain library (net-did, dataproofs-dotnet, credentials-dotnet, didcomm-dotnet) binds directly to a specific crypto backend.

dotnet add package NetCrypto

Stable release. NetCrypto is published as a stable 1.0.0 (GA) — no --prerelease flag is required. The public API is frozen: PublicAPI.Shipped.txt is the authoritative contract and PublicAPI.Unshipped.txt is empty. Semantic versioning applies — additive changes bump the minor version, breaking changes the major; any pre-GA 1.0.0-preview.* packages are superseded by 1.0.0. See CHANGELOG.md for the release history.

Target framework: net10.0. Depends on NetCid for multibase/multicodec encoding.

Quick start

using NetCrypto;

var keyGen = new DefaultKeyGenerator();
var crypto = new DefaultCryptoProvider();

var keyPair = keyGen.Generate(KeyType.Ed25519);
byte[] signature = crypto.Sign(keyPair.KeyType, keyPair.PrivateKey, data);
bool valid = crypto.Verify(keyPair.KeyType, keyPair.PublicKey, data, signature);

Console.WriteLine(keyPair.MultibasePublicKey); // z6Mk... (multicodec + base58btc)

With dependency injection (Microsoft.Extensions.DependencyInjection):

services.AddNetCrypto(); // TryAdd: your own ICryptoProvider/IBbsCryptoProvider/IKeyGenerator
                         // registrations made BEFORE this call win (the swap seam).

Learning the API: samples

The primary usage documentation is samples/README.md — ten standalone, runnable console programs covering 100% of the public API surface (enforced in CI by tools/ApiCoverageCheck). Start with NetCrypto.Samples.Keys and follow the reading order in the samples index.

Algorithm and specification conformance

Every primitive is tested against the test vectors of its governing specification.

BBS terminology. "BBS" is the CFRG name for the scheme historically called BBS+. Conformance is pinned to draft-10 via zkryptium 0.6; the BbsCiphersuite parameter (only Bls12381Sha256 in v1) and the FFI isolation contain future draft churn.

BBS header vs presentation header. Sign/Verify/DeriveProof/VerifyProof take an optional header (default empty): data the signer binds at sign time and that every derived proof commits — the holder cannot drop or alter it (e.g. the W3C bbs-2023 cryptosuite binds its mandatory-disclosure group here). It is distinct from the presentationHeader (ph) on DeriveProof/VerifyProof, which the holder chooses at derive time (typically the verifier's challenge).

Native BBS library and the supported "BBS-absent" mode

BBS is the only non-managed primitive: the zkryptium-ffi Rust crate (native/zkryptium-ffi/) is compiled per platform and shipped inside this single NuGet package under runtimes/{rid}/native/. A consumer that restores NetCrypto gets the BBS native payload transitively — no per-consumer native assets are needed.

Supported native platform matrix

On any of these RIDs IBbsCryptoProvider.IsAvailable returns true after a plain dotnet restore. The tag-triggered release workflow fails the build if any RID's native payload is missing from the produced .nupkg (the "Verify nupkg contains all five RIDs" step), publishes a SHA-256 checksum per binary, and then smoke-tests the packed package — installing it into a clean console app and running a BBS sign/verify round-trip — so the guarantee is verified against the actual published artifact, not the source tree.

All managed primitives work with no native library present (unlisted platforms, or environments that prohibit native code). This is a supported, CI-tested mode:

var bbs = new DefaultBbsCryptoProvider();
if (!bbs.IsAvailable)
{
    // Probe never throws. Any BBS operation would throw BbsUnavailableException
    // (InnerException carries the original native load error).
}

BBS key generation

The supported way to mint a BBS keypair is the standard key generator — the same one used for every other key type:

var keyPair = new DefaultKeyGenerator().Generate(KeyType.Bls12381G2); // or Bls12381G1
// keyPair.PrivateKey (32-byte BLS12-381 scalar), keyPair.PublicKey (96-byte G2 / 48-byte G1)
byte[] sig = new DefaultBbsCryptoProvider().Sign(keyPair.PrivateKey, messages);

Bls12381G2 (96-byte public key) is the variant the BBS provider signs/verifies with. Raw FFI keygen (bbs_keygen) is intentionally internal — there is no public raw-keygen helper, by design, to keep the public surface minimal and backend-agnostic. See samples/NetCrypto.Samples.Bbs for an end-to-end example.

The repository itself is source-only — every shipped binary is cross-compiled by the tag-triggered release workflow from pinned sources, with SHA-256 checksums published as release assets.

Architecture notes

• Single provider, swappable via DI (Posture 1). DefaultCryptoProvider implements ICryptoProvider for all key types; consumers with special requirements (e.g. a FIPS 140-3-validated module) replace the registration — AddNetCrypto() uses TryAdd, so a registration made before it wins. The designated evolution path is a per-KeyType provider registry behind the unchanged ICryptoProvider facade; no registry exists in v1.
• Backend isolation. No type from NSec, NBitcoin, Nethermind, or the FFI appears in any public signature (enforced by Microsoft.CodeAnalysis.PublicApiAnalyzers with a committed PublicAPI.Shipped.txt, plus a reflection test). Sanctioned exceptions: NetCid types and Microsoft.IdentityModel.Tokens.JsonWebKey.
• EC point validation. EcPointValidator.EnsureOnCurve(KeyType, x, y) is the public on-curve validation entry point — the invalid-curve-attack defense (RFC 7518 §6.2.2). Point decompression (DecompressEcPoint / DecompressSecp256k1Point) is an internal implementation detail and is not part of the public surface; validating a key never requires it.
• Boundaries. EVM v-encoding/RLP/transactions, JOSE/JWE/SD-JWT envelopes, Data Integrity proofs, ECDH-ES/1PU assembly, and concrete HSM/KMS stores are deliberately out of scope — they belong to the consumer layers.
• Security posture. None of the wrapped backends is independently audited or FIPS-validated; this is documented openly rather than implied otherwise.

Building from source

# Managed code + tests (BBS tests require the native library, see below)
dotnet build NetCrypto.sln
dotnet test NetCrypto.sln --filter "Category!=BbsAbsent"

# Native BBS library for your host platform (Rust toolchain pinned in rust-toolchain.toml)
cd native/zkryptium-ffi && cargo build --release
# Rebuild so the test/sample projects pick up the binary, then run everything:
cd ../.. && dotnet build NetCrypto.sln && dotnet test NetCrypto.sln --filter "Category!=BbsAbsent"

# Without the native library (supported BBS-absent mode):
dotnet test NetCrypto.sln --filter "Category!=NativeFFI"

License

Apache-2.0. See LICENSE.