Bodu.Security.Cryptography 1.2.0

Bodu.Security.Cryptography

API stability - Stable. The public API surface is committed; breaking changes are reserved for a major-version bump per SemVer.

Managed implementations of modern and legacy cryptographic primitives for .NET 8 and later. The library provides block ciphers, AEAD modes, hash and MAC functions, padding schemes, asymmetric key agreement and signatures (including the FIPS 203/204 post-quantum algorithms), and the supporting transform infrastructure to compose them. All algorithms are exposed through the standard SymmetricAlgorithm / HashAlgorithm / KeyedHashAlgorithm / AsymmetricAlgorithm contracts so they slot into existing BCL pipelines (including CryptoStream).

It also provides an RFC 6962 Merkle tree with inclusion and consistency proofs, built over any HashAlgorithm and able to hash a large input's leaves on every core.

Security posture and limitations

Read this before using the library for anything that matters.

• Not independently audited. These are managed, from-scratch implementations. They are pinned to published known-answer vectors for functional correctness, but they have not undergone an independent security audit. Treat them as suitable for development, interop with non-FIPS systems, research, and education - not as a drop-in for a hardened production provider.
• Not FIPS-validated. This is not a FIPS 140-2 / 140-3 cryptographic module. For FIPS-validated AES, SHA-2, RNG, and similar primitives use the platform-provided System.Security.Cryptography types and the underlying OS provider.
• Side-channel resistance is best-effort, not guaranteed. Constant-time behaviour is implemented where practical: tag and hash comparisons use CryptographicOperations.FixedTimeEquals and padding removal is branchless. GHASH and POLYVAL (behind GCM, GMAC and GCM-SIV) neither branch on nor index memory by the key or the data on any path, the portable fallback included. The software table-based algorithms - Blowfish, Twofish, Camellia, Tiger, Whirlpool and Snefru - still index tables by secret-dependent values. Managed code runs on a JIT and GC the library does not control, so timing/cache invariance cannot be guaranteed end-to-end regardless. For workloads with a real side-channel adversary, prefer the hardware-backed BCL primitives.
• AES delegates to the BCL. AesBlockCipher wraps the platform System.Security.Cryptography.Aes (hardware-accelerated, constant-time, FIPS-validated). Everything else in the package is a bespoke managed implementation.
• This is a toolbox, not a safe-by-default API. ECB, NoPadding, raw CBC, and unauthenticated stream ciphers are all first-class. Prefer an AEAD mode (GCM, EAX, OCB, or a nonce-misuse-resistant SIV / GCM-SIV) unless you have a specific reason not to, and read the per-type remarks for the failure modes.

The primitives provided here exist mainly to cover what the BCL does not ship (Blake2/Blake3, Ascon, Skein, Poly1305, SipHash, Threefish, Serpent, Camellia, Blowfish, Skipjack, OCB / EAX / SIV / GCM-SIV modes, X25519 / Ed25519, the post-quantum ML-KEM / ML-DSA on .NET 8, RFC 6962 Merkle trees, etc.).

Algorithm support matrix

Block ciphers

AEAD modes

Stream ciphers

The AEAD stream constructions pair a stream cipher with Poly1305: ChaCha20-Poly1305 (RFC 8439), XChaCha20-Poly1305, and XSalsa20-Poly1305 (NaCl secretbox). Each is single-use per message and verifies the tag with CryptographicOperations.FixedTimeEquals.

Asymmetric algorithms

All asymmetric types derive from System.Security.Cryptography.AsymmetricAlgorithm and support only the raw byte encodings of their defining specification (PKCS#8 / SubjectPublicKeyInfo DER import/export is not implemented). Private key material is zeroed on dispose and exports return defensive copies.

Hybrid public-key encryption (HPKE)

Hpke implements RFC 9180 in all four modes - Base, PSK, Auth and AuthPSK - with the DHKEM(X25519, HKDF-SHA256) KEM, HKDF-SHA256, HKDF-SHA384 or HKDF-SHA512, and AES-128-GCM, AES-256-GCM, ChaCha20-Poly1305 or export-only as the AEAD. Hpke.Seal and Hpke.Open handle a single message; HpkeSender and HpkeReceiver hold a context for a sequence of messages and derive exporter secrets with Export. A context checks its message counter before doing any cryptographic work, so it refuses the message that would reuse a nonce rather than sealing it. The suite is pinned to the RFC 9180 test vectors; see the HPKE guide.

Block cipher modes (unauthenticated)

Padding schemes

PKCS#7, ANSI X9.23, ISO 7816-4, ISO 10126, zero-padding, and None. All are exercised by the block-cipher transform tests with positive and negative cases.

Hash and MAC

Non-cryptographic hashes and checksums - FNV-1a, Adler-32, CRC-3 through CRC-64, and Fletcher-16/32/64 - live in the sibling Bodu.IO.Hashing package.

Key derivation and password hashing

Argon2 and scrypt can divide a derivation across threads (see Multithreading), and both keep their working memory in pooled native memory: set the Bodu.Security.Cryptography.Argon2.DisableMatrixReuse switch to release it after every call instead. See the Argon2, scrypt and HKDF guides.

Merkle trees

MerkleTree computes the RFC 6962 (Certificate Transparency) Merkle Tree Hash over an ordered list of entries, or over the fixed-size blocks of a stream or buffer, and produces and verifies the proofs that go with it. It works over any HashAlgorithm - new MerkleTree(SHA256.Create) - and assumes no particular digest length.

• Parallel leaf hashing. Hashing the leaves is nearly all of a block computation's work. new MerkleTree(SHA256.Create, maxDegreeOfParallelism: -1) hashes them in batches on every core, with one HashAlgorithm per worker, and folds them in order on the calling thread. A parallel instance produces the same roots and proofs as a sequential one; the default, 1, keeps everything on the calling thread.
• Fan-out. The default fanOut of 2 is RFC 6962's binary tree. A wider fan-out builds a shallower k-ary tree as an explicit non-RFC mode: its roots work, and the proof members throw NotSupportedException.
• Sharing and verification. An instance is immutable and safe to share across threads, provided the factory returns a new HashAlgorithm on each call, as SHA256.Create does. Verification returns false for a malformed proof rather than throwing. VerifyInclusion trusts the tree size it is given; when that size comes from the party being checked, publish a length-bound root and verify with VerifyInclusionBound or VerifyBlockInclusion, which fail closed.

using System.Security.Cryptography;
using Bodu.Security.Cryptography;

var tree = new MerkleTree(SHA256.Create, maxDegreeOfParallelism: -1);

// The root and every leaf hash of a file in 1 MiB blocks, the leaves hashed on every core.
using var file = File.OpenRead("archive.bin");
MerkleBlockComputation blocks = tree.ComputeBlocked(file, blockSize: 1 << 20);

// Prove that block 3 is in the file, then check the proof.
byte[][] path = tree.AuthenticationPath(blocks.LeafHashes, leafIndex: 3);
bool included = tree.VerifyInclusionOfLeafHash(
    blocks.Root, treeSize: blocks.LeafHashes.Count, leafIndex: 3,
    leafHash: blocks.LeafHashes[3],
    path: path.Select(step => (ReadOnlyMemory<byte>)step).ToArray());

See the Merkle tree guide; the Merkle tree sample runs each of these as a scenario.

One-time passwords

Static, span-based, and built on the BCL one-shot HMAC (OtpHashAlgorithm selects SHA-1/256/512). Verification is constant-time. Secrets are raw bytes - decode a Base32 otpauth:// secret with Bodu.Text.Encoding.Base32 first. See the HOTP/TOTP guide.

Lifecycle and disposal guarantees

• AEAD transforms (IAeadBlockCipherModeTransform) are single-use per message. Each implementation tracks _completed, _aadProcessed, _disposed, rejects double-Encrypt/Decrypt with InvalidOperationException, rejects post-disposal access with ObjectDisposedException, compares tags with CryptographicOperations.FixedTimeEquals, and clears the plaintext destination on tag-verification failure.
• BlockCipherTransform owns and disposes the underlying IBlockCipher. Single-use; rejects TransformBlock after TransformFinalBlock. See the class XML remarks for the full ownership contract.
• Poly1305 is a one-time MAC; the same instance throws CryptographicException on a second ComputeHash unless Key is explicitly reassigned. Disposing clears _acc, _r, _s, and _key.
• Blake3 clears each uint[] on the chunk-CV stack on Dispose so per-subtree chaining values do not survive in heap memory.
• GCM rejects message lengths that would force its 32-bit inc32 counter to wrap past 0xFFFFFFFF while another block remains to be processed.

Hardware acceleration

These primitives dispatch to vector, carry-less-multiply or wide-multiply instructions where the processor has them, and to a portable implementation where it does not. Every path produces bit-identical output: the test suite holds each kernel to its portable counterpart and to the published vectors, and CI runs it on both x64 and ARM64.

The 16-wide ChaCha20, Salsa20 and BLAKE3 kernels, and the 8-wide Poly1305 kernel, run where .NET accelerates 512-bit vectors (Vector512.IsHardwareAccelerated); other AVX-512 processors run the next narrower kernels.

On ARM64, BLAKE2b, BLAKE2s, scrypt and BLAKE3 over a single block run their portable kernels, which ran faster than their AdvSimd kernels on a Neoverse N2 under .NET 8 and .NET 10, and faster or about as fast on an Apple M1 under .NET 10. Those kernels hold one state across a vector's lanes, which pays on x64 but not against ARM64's thirty-one general registers and one-instruction rotations. Argon2's rows, and then its columns, are independent of each other, so on ARM64 it works one row or column in vector registers and the next in general registers at once: 1.24 to 1.28 times as fast as its portable kernel on a Neoverse N2, and 1.3 to 1.6 times as fast as its AdvSimd kernel on an Apple M1.

Set the process-wide feature switch Bodu.Security.Cryptography.DisableSimd to true to force the portable path in place of every vector and carry-less-multiply kernel above (AES and the 64-bit multiplies are unaffected) - useful for reproducibility, differential testing, or audit. It is read once, before first use of any accelerated primitive, so set it via runtimeconfig.json / a <RuntimeHostConfigurationOption> item or an early AppContext.SetSwitch(...). The paths are equivalent (the ARX designs such as BLAKE2/3, ChaCha20 and Threefish are constant-time in both forms); the switch is not a security control. See the hardware-acceleration guide for details.

Multithreading

Four types can spread a single operation across threads. Each takes a maxDegreeOfParallelism bound when constructed and exposes it as MaxDegreeOfParallelism: 1 keeps the work on the calling thread, -1 allows up to one thread per processor, and a larger value caps the threads. The output never depends on the bound.

Argon2.Verify and Scrypt.Verify take the same bound. The defaults are 1 where a busy service would only pay for the hand-offs (or, for scrypt, the extra memory); raise the bound to process one large input faster. Argon2 defaults to -1 because its lanes share one memory matrix, so threads do not multiply its memory the way scrypt's units do.

Reusable infrastructure

Testing

Tests live in test/ and are organised as MSTest partial classes mirroring src/. Run tiers via the runsettings files at the solution root:

dotnet test Bodu.Security.Cryptography/test/Bodu.Security.Cryptography.Test.csproj --settings smoke.runsettings
dotnet test Bodu.Security.Cryptography/test/Bodu.Security.Cryptography.Test.csproj --settings bvt.runsettings
dotnet test Bodu.Security.Cryptography/test/Bodu.Security.Cryptography.Test.csproj --settings regression.runsettings

The shared AeadBlockCipherModeTests<TTest, TTransform> base contains the lifecycle / reuse / failed-tag-poisoning suite that every AEAD mode inherits. The HashAlgorithmTests<TTest, TAlgorithm, TVariant> base (and its BlockHashAlgorithmTests / KeyedBlockHashAlgorithmTests specialisations) provides spec-driven KAT, boundary, and disposal coverage for every hash and MAC. Block ciphers extend BlockCipherTests<TTest, TCipher, TVariant>, and every stream cipher inherits SymmetricStreamAlgorithmTests<TTest, TAlgorithm> for key/nonce sizing, lifecycle, transform-reuse, overlap, and disposal coverage. The asymmetric families inherit a parallel contract hierarchy: AsymmetricAlgorithmTests<TTest, TAlgorithm> carries the shared construction, key-size, raw import/export, and disposal contract, and its operation bases KeyAgreementAlgorithmTests (X25519), SignatureAlgorithmTests (Ed25519 and, via MLDsaContractTests, ML-DSA), and KemAlgorithmTests (via MLKemContractTests, ML-KEM) add the derive/sign/encapsulate contracts. The asymmetric known-answer corpora (RFC 7748/8032 vectors as in-memory KAT rows, plus curated Wycheproof x25519/ed25519 subsets and NIST ACVP ML-KEM / ML-DSA vectors embedded with provenance headers) run in the BVT and Regression tiers.