Bodu.Security.Cryptography 0.5.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. 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).

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. Work is ongoing to remove secret-dependent branches and table lookups from GHASH and the software table-based ciphers (Blowfish, Twofish, Camellia, Tiger, Whirlpool, Snefru). 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, 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.

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.

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

Blake2b, Blake2s, Blake3, Threefish256 / Threefish512 / Threefish1024, and CubeHash ship an AVX-512 vectorised path alongside a scalar reference implementation, and dispatch to it automatically when the host CPU supports it. The two produce bit-identical output.

Set the process-wide feature switch Bodu.Security.Cryptography.DisableSimd to true to force the scalar path — 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 (BLAKE2/3 and Threefish are ARX and constant-time in both forms); the switch is not a security control. See the hardware-acceleration guide for details.

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.