Table of Contents

Bodu.Security.Cryptography guides

Recipe-style walk-throughs for Bodu.Security.Cryptography, organized by the type hierarchy of the library: foundations → standard ciphers → tweakable ciphers → stream ciphers → AEAD → cryptographic hashes → keyed hashes → ASCON.

Part of the Hashing & Cryptography topic.

If you have not yet installed the package or want the high-level shape of the library, start with the Bodu.Security.Cryptography introduction and the getting-started page. Not sure which primitive to use? Start with Choosing a primitive - decision tables for hashes, MACs, AEAD, KDFs, asymmetric algorithms, and block ciphers beside their BCL counterparts - or the introduction's shape of the library section, which maps the five families and explains how they differ.

For the auto-generated API reference, see the Bodu.Security.Cryptography namespace page. For non-cryptographic checksums and fingerprints, see the Bodu.IO.Hashing guides.

Namespace map

Namespace What lives here Guide section
Bodu.Security.Cryptography All cryptographic primitives - block ciphers, mode transforms, padding strategies, hash algorithms, AEAD constructions, helpers. All sections below
Bodu.Security.Cryptography.Extensions Ergonomic one-shot, async, and verify helpers over SymmetricAlgorithm, TweakableSymmetricAlgorithm, IBlockCipher + AEAD transforms, HashAlgorithm, and ICryptoTransform. Streams and async; the per-algorithm guides

Choosing and combining

Choosing a primitive

Decision tables - hashes, MACs, AEAD, KDFs, asymmetric algorithms, block ciphers - with sizes and defaults verified in source, and when the BCL is the better answer.

Interoperating with System.Security.Cryptography

HashAlgorithm one-shots and TransformBlock, CryptoStream, the AES-GCM wire-compatibility proof with AesGcm, PEM / PKCS#8 / SPKI for X25519 and Ed25519, HashAlgorithmName, and constant-time comparison.

Modes, transforms, and factories

The CipherModeKind support matrix - what BlockMode can build, what exists only as a direct transform, what is AEAD - plus BlockCipherTransform, IBlockCipher, the padding factories (block size in bits), and the dual padding properties.

Streams and async

Encrypt(Stream, Stream) / EncryptAsync, AppendDataAsync / VerifyHashAsync, MerkleTree.ComputeRootOfBlocksAsync - buffer sizes, cancellation, and pooled-memory behaviour.

Nonces, salts, tags, and secrets

Nonce, Salt, SecretBytes, HashValue, AuthenticationTag, SignatureValue - construction, constant-time equality, zeroization, and where each is accepted (detached AEAD, scrypt).

Security guarantees and limitations

Audit status, constant-time claims per primitive, zeroization on dispose, SIMD determinism and the DisableSimd switch, the exception contract, single-use rules, and thread safety.

Extending the library

A custom BlockHashAlgorithm, a custom IBlockCipher behind BlockCipherTransform, the hash-algorithm factories, and the contract-test bases that prove your type against the built-in contract.

Foundations

Encryption basics

The mental model: BlockMode vs .NET's Mode, how Key / IV / Tweak / Padding combine, generating random key material, and disposing safely.

Cipher block modes

ECB, CBC, CFB, OFB, CTR, CTS, and XTS - one worked round-trip per mode, with the IV rules, the encrypt-vs-decrypt-primitive table, and when each is appropriate.

Padding

PKCS7, ANSI X.923, ISO 10126, ISO/IEC 7816-4, Zeros, None - how each one pads, when it round-trips cleanly, and the padding-oracle caveat.

Composing primitives

The two patterns side by side - manual IBlockCipher + BlockCipherModeFactory + PaddingFactory, and the equivalent through the SymmetricAlgorithm wrappers.

AES-family block ciphers

AES, Twofish, Camellia, Serpent-128 - the four 128-bit-block ciphers compared, with selection guidance and BCL-vs-Bodu trade-offs.

Hardware acceleration & SIMD opt-out

Which primitives ship an AVX-512 fast path (BLAKE2/3, Threefish, CubeHash), when it engages, and the Bodu.Security.Cryptography.DisableSimd switch to force the scalar path.

Symmetric ciphers - Standard

Cipher Block Key Guide
Skipjack 64 bits (8 B) 80 bits (10 B) Using Skipjack
Blowfish 64 bits (8 B) 32-448 bits, 8-bit steps Using Blowfish
Camellia 128 bits (16 B) 128 / 192 / 256 bits AES-family block ciphers
Twofish 128 bits (16 B) 128 / 192 / 256 bits AES-family block ciphers
Serpent128 128 bits (16 B) 128 / 192 / 256 bits Using Serpent · AES-family block ciphers
AesBlockCipher 128 bits (16 B) 128 / 192 / 256 bits AES-family block ciphers (raw IBlockCipher over the BCL Aes)

Symmetric ciphers - Tweakable

Cipher Block Key Tweak Guide
Threefish256 256 bits (32 B) 256 bits (32 B) 128 bits (16 B) Using Threefish-256
Threefish512 512 bits (64 B) 512 bits (64 B) 128 bits (16 B) Using Threefish-512
Threefish1024 1024 bits (128 B) 1024 bits (128 B) 128 bits (16 B) Using Threefish-1024
Serpent256 / Serpent512 / Serpent1024 256 / 512 / 1024 bits matching key 128 bits Using Serpent - non-standard, experimental wide-block constructions

Symmetric ciphers - Stream

Raw, confidentiality-only XOR keystream ciphers - no authentication; pair with a MAC or prefer AEAD. See Using stream ciphers.

Cipher Key Nonce / IV Notes
ChaCha20 256 bits (32 B) 96 bits (12 B) RFC 8439; the modern default.
XChaCha20 256 bits (32 B) 192 bits (24 B) Extended nonce - safe to choose at random.
Salsa20 128 / 256 bits 64 bits (8 B) eSTREAM; 64-bit nonce needs a counter.
XSalsa20 256 bits (32 B) 192 bits (24 B) Extended-nonce Salsa20 (NaCl).
Rabbit 128 bits (16 B) 64 bits (8 B) RFC 4503; evolving-state (no seekable counter).
Hc128 128 bits (16 B) 128 bits (16 B) eSTREAM; expensive table-based setup.

Symmetric ciphers - AEAD

AEAD modes

GCM, CCM, OCB3, EAX, SIV, GCM-SIV - authenticated encryption with associated data using AesBlockCipher + the mode transforms, via the one-shot extension methods.

Authenticated stream ciphers

XChaCha20Poly1305, the NaCl secretbox XSalsa20Poly1305 (with the libsodium layout converters), and XSalsa20Poly1305Aead over Poly1305AeadTransform / IStreamAeadTransform; single-use, in-place, and detached-tag patterns.

Cryptographic hashes

Hashing overview

Cross-cutting overview of keyed hashes (SipHash, Poly1305), cryptographic digests (Tiger, CubeHash, Snefru), and Merkle trees.

Using Tiger

128 / 160 / 192-bit cryptographic digest optimized for 64-bit platforms; two padding variants (Tiger / Tiger2).

Using CubeHash

SHA-3 finalist with tunable rounds and block size.

Using Snefru

Snefru-128 / Snefru-256 - legacy cryptographic digest; interoperability use only.

Merkle trees and proofs

The RFC 6962 tree over any inner HashAlgorithm - roots over entries, blocks, or a write-time accumulator; inclusion and consistency proofs; length-bound roots; parallel leaf hashing.

The remaining digests have their own walk-throughs too - BLAKE2 / BLAKE3, Skein, Whirlpool, and SHAKE - or consult the API reference directly.

Keyed hashes (MAC)

Using SipHash

SipHash-64 and SipHash-128 - keyed PRF designed for hash-flooding-resistant hash tables.

Using Poly1305

One-time authenticator (RFC 8439); pair with ChaCha20 or AES-CTR.

ASCON family

ASCON overview

All five NIST SP 800-232 types - Hash256, HashA256, XOF128, CXOF128, AEAD128 - with selection guidance.

ASCON hashing

AsconHash256 (12-round, max margin) and AsconHashA256 (8-round, higher throughput).

ASCON extendable output (XOF)

AsconXof128 and AsconCxof128 - squeeze any number of bytes; CXOF accepts a domain customization string.

ASCON authenticated encryption (AEAD)

AsconAead128 - sponge-based AEAD with no separate block cipher dependency.

Key derivation

Using HKDF

Hkdf (RFC 5869) - extract-and-expand key derivation for high-entropy inputs such as a shared secret or KEM output.

Using Argon2

Argon2id / Argon2i / Argon2d (RFC 9106) - memory-hard password hashing and key derivation, with PHC encoded-hash Hash / Verify.

Using scrypt

Scrypt (RFC 7914) - the established memory-hard password KDF, with PHC encoded-hash Hash / Verify.

One-time passwords

Using HOTP and TOTP

Hotp (RFC 4226) and Totp (RFC 6238) - the counter- and time-based one-time-password codes used for two-factor authentication, with constant-time verification and clock-drift windows.

Asymmetric algorithms

Asymmetric algorithms overview

The four families over AsymmetricAlgorithm - key agreement, signatures, and post-quantum KEM / signatures - with selection guidance and the shared key import / export shape.

Key agreement with X25519

X25519 (RFC 7748) - Diffie-Hellman over Curve25519 for deriving a shared secret between two parties.

Signatures with Ed25519

Ed25519 (RFC 8032) - deterministic EdDSA signing and verification over Curve25519.

ML-KEM post-quantum key encapsulation

MLKem512 / MLKem768 / MLKem1024 (FIPS 203) - lattice-based key encapsulation resistant to quantum attack.

ML-DSA post-quantum signatures

MLDsa44 / MLDsa65 / MLDsa87 (FIPS 204) - lattice-based digital signatures resistant to quantum attack.

Hybrid public key encryption with HPKE

Hpke (RFC 9180) - encrypt to a public key by composing the X25519 KEM, HKDF, and an AEAD; single-shot and session APIs across all four modes.

Where to go next