NetCrypto 1.0.0-preview.2

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 --prerelease

NetCrypto is currently published as a preview (1.0.0-preview.*); the --prerelease flag (or an explicit prerelease version) is required until a stable 1.0.0 is cut.

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/ for: linux-x64, linux-arm64, osx-arm64, osx-x64, win-x64.

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).
}

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.
• 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.