chacha20blake3 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 884132d1f327e45e947d008367009753b1c014a8809a1330fb1cbc8cf014def6
+  data.tar.gz: c1ff6117acd18ead79c48d08a9bcb2f223dd4524e65b93268f06c9ca1ac16b37
+SHA512:
+  metadata.gz: 71187d3c2e6d86858938c3fe26476c60bdc1af777d4eee842794575d1823fb95514d73fe14282c1e38828b6b691e2d71ffbf5c570e6abb2cd0efc438a3e9a547
+  data.tar.gz: affa5cb7f8123f050a9f8cb38b83f1c11110e7730ee360b53287e81c12c8017a36ffcb68dc88113be539aeab23247626864023b27b39463b6ec48f8a20b8ad84

data/Cargo.lock

@@ -0,0 +1,402 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "arrayref"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76a2e8124351fda1ef8aaaa3bbd7ebbcb486bbcd4225aca0aa0d84bb2db8fecb"
+
+[[package]]
+name = "arrayvec"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50"
+dependencies = [
+ "zeroize",
+]
+
+[[package]]
+name = "bindgen"
+version = "0.72.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
+dependencies = [
+ "bitflags",
+ "cexpr",
+ "clang-sys",
+ "itertools",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "rustc-hash",
+ "shlex",
+ "syn",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
+
+[[package]]
+name = "blake3"
+version = "1.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4d2d5991425dfd0785aed03aedcf0b321d61975c9b5b3689c774a2610ae0b51e"
+dependencies = [
+ "arrayref",
+ "arrayvec",
+ "cc",
+ "cfg-if",
+ "constant_time_eq",
+ "cpufeatures",
+ "zeroize",
+]
+
+[[package]]
+name = "cc"
+version = "1.2.59"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7a4d3ec6524d28a329fc53654bbadc9bdd7b0431f5d65f1a56ffb28a1ee5283"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cexpr"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
+dependencies = [
+ "nom",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "chacha"
+version = "0.1.0"
+source = "git+https://github.com/skerkour/chacha20-blake3?rev=9942bf34c77b03896bb1733079256076ca823e58#9942bf34c77b03896bb1733079256076ca823e58"
+dependencies = [
+ "zeroize",
+]
+
+[[package]]
+name = "chacha20-blake3"
+version = "0.9.11"
+source = "git+https://github.com/skerkour/chacha20-blake3?rev=9942bf34c77b03896bb1733079256076ca823e58#9942bf34c77b03896bb1733079256076ca823e58"
+dependencies = [
+ "blake3",
+ "chacha",
+ "constant_time_eq",
+ "zeroize",
+]
+
+[[package]]
+name = "chacha20blake3"
+version = "0.1.0"
+dependencies = [
+ "blake3",
+ "chacha20-blake3",
+ "getrandom",
+ "magnus",
+ "rb-sys",
+]
+
+[[package]]
+name = "clang-sys"
+version = "1.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b023947811758c97c59bf9d1c188fd619ad4718dcaa767947df1cadb14f39f4"
+dependencies = [
+ "glob",
+ "libc",
+ "libloading",
+]
+
+[[package]]
+name = "constant_time_eq"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d52eff69cd5e647efe296129160853a42795992097e8af39800e1060caeea9b"
+
+[[package]]
+name = "cpufeatures"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "glob"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
+
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
+[[package]]
+name = "libc"
+version = "0.2.184"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48f5d2a454e16a5ea0f4ced81bd44e4cfc7bd3a507b61887c99fd3538b28e4af"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "magnus"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b36a5b126bbe97eb0d02d07acfeb327036c6319fd816139a49824a83b7f9012"
+dependencies = [
+ "magnus-macros",
+ "rb-sys",
+ "rb-sys-env",
+ "seq-macro",
+]
+
+[[package]]
+name = "magnus-macros"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47607461fd8e1513cb4f2076c197d8092d921a1ea75bd08af97398f593751892"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rb-sys"
+version = "0.9.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "284799e73e899fe946fd77c7211b83bff61a1356e039ade7a2516a779e3212d0"
+dependencies = [
+ "rb-sys-build",
+]
+
+[[package]]
+name = "rb-sys-build"
+version = "0.9.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "855fc1ad8943d12c89ef12f9147f1cc531f5bf19fb744112fdd317bb6ee7b5c5"
+dependencies = [
+ "bindgen",
+ "lazy_static",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "shell-words",
+ "syn",
+]
+
+[[package]]
+name = "rb-sys-env"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
+
+[[package]]
+name = "regex"
+version = "1.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e10754a14b9137dd7b1e3e5b0493cc9171fdd105e0ab477f51b72e7f3ac0e276"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
+
+[[package]]
+name = "seq-macro"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
+
+[[package]]
+name = "shell-words"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "zeroize"
+version = "1.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
+dependencies = [
+ "zeroize_derive",
+]
+
+[[package]]
+name = "zeroize_derive"
+version = "1.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85a5b4158499876c763cb03bc4e49185d3cccbabb15b33c627f7884f43db852e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]

data/Cargo.toml

@@ -0,0 +1,9 @@
+[workspace]
+members  = ["ext/chacha20blake3"]
+resolver = "2"
+
+[profile.release]
+opt-level     = 3
+lto           = true
+codegen-units = 1
+panic         = "abort"

data/README.md

@@ -0,0 +1,284 @@
+# ChaCha20Blake3
+
+[![CI](https://github.com/paddor/chacha20blake3/actions/workflows/ci.yml/badge.svg)](https://github.com/paddor/chacha20blake3/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/chacha20blake3?color=e9573f)](https://rubygems.org/gems/chacha20blake3)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+> **Warning:** This gem is not maintained by cryptographers. The author is not a
+> cryptographer. It has not been independently audited. For production use where
+> proven, audited libraries matter, consider [RbNaCl](https://github.com/RubyCrypto/rbnacl)
+> (XChaCha20-Poly1305) or another gem from [RubyCrypto](https://github.com/RubyCrypto).
+>
+> This gem exists because no Ruby binding for ChaCha20-BLAKE3 existed yet. If
+> RbNaCl adds ChaCha20-BLAKE3 support, or this gem is transferred to
+> [RubyCrypto](https://github.com/RubyCrypto), this warning will be removed.
+
+Fast, paranoia-grade authenticated encryption for Ruby -- no NIST primitives, no hardware AES requirement.
+
+This gem wraps the [`chacha20-blake3`](https://github.com/skerkour/chacha20-blake3) Rust crate via a native Rust extension ([magnus](https://github.com/matsadler/magnus)). The underlying cipher combines:
+
+- **ChaCha20** stream cipher (DJB, RFC 8439)
+- **BLAKE3** as the authentication MAC
+
+SIMD-accelerated on every major architecture:
+| Platform | Acceleration |
+|----------|-------------|
+| x86-64   | AVX2, AVX-512 |
+| ARM64    | NEON, SVE |
+| Generic  | Pure Rust fallback |
+
+No AES-NI, no hardware crypto instructions, no NIST curves. Pure DJB crypto all the way down.
+
+## Why ChaCha20 + BLAKE3?
+
+- **No NIST influence** - avoids AES (backdoor concerns), P-256/P-384 (nothing-up-my-sleeve suspicion), SHA-2 (NSA design)
+- **Hardware-agnostic** - fast on any CPU, not just ones with AES-NI
+- **Embedded-friendly** - small code size, no hardware requirements
+- **Modern MAC** - BLAKE3 is faster than Poly1305 on larger payloads and provides 256-bit tags vs 128-bit
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "chacha20blake3"
+```
+
+Or install directly:
+
+```sh
+gem install chacha20blake3
+```
+
+Building from source requires a Rust toolchain (`rustup.rs`).
+
+## Quick Start
+
+```ruby
+require "chacha20blake3"
+
+# Generate a random key and nonce
+key   = ChaCha20Blake3.generate_key    # 32 bytes, CSPRNG
+nonce = ChaCha20Blake3.generate_nonce  # 24 bytes, CSPRNG
+
+cipher = ChaCha20Blake3::Cipher.new(key)
+
+# Encrypt - returns ciphertext with tag appended (last 32 bytes)
+ciphertext = cipher.encrypt(nonce, "Hello, world!")
+
+# Decrypt - raises ChaCha20Blake3::DecryptionError on authentication failure
+plaintext = cipher.decrypt(nonce, ciphertext)
+# => "Hello, world!" (Encoding::BINARY)
+```
+
+### With Associated Data (AAD)
+
+AAD is authenticated but not encrypted. Use it to bind ciphertext to context
+(e.g., a session ID, record ID, version header):
+
+```ruby
+aad = "user_id=42,version=1"
+
+ct = cipher.encrypt(nonce, plaintext, aad: aad)
+pt = cipher.decrypt(nonce, ct, aad: aad)
+
+# Wrong AAD raises DecryptionError
+cipher.decrypt(nonce, ct, aad: "tampered")  # => raises!
+```
+
+### Detached Tag
+
+Store the 32-byte authentication tag separately from the ciphertext:
+
+```ruby
+ct, tag = cipher.encrypt_detached(nonce, plaintext, aad: aad)
+
+# ct and tag can be stored/transmitted separately
+pt = cipher.decrypt_detached(nonce, ct, tag, aad: aad)
+```
+
+## API Reference
+
+### Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `ChaCha20Blake3::KEY_SIZE`   | `32` | Key length in bytes |
+| `ChaCha20Blake3::NONCE_SIZE` | `24` | Nonce length in bytes |
+| `ChaCha20Blake3::TAG_SIZE`   | `32` | Authentication tag length in bytes |
+
+### Module Methods
+
+#### `ChaCha20Blake3.generate_key -> String`
+Returns 32 cryptographically random bytes (BINARY encoding). Uses the OS CSPRNG (`getrandom(2)` on Linux, `BCryptGenRandom` on Windows).
+
+#### `ChaCha20Blake3.generate_nonce -> String`
+Returns 24 cryptographically random bytes (BINARY encoding).
+
+#### `ChaCha20Blake3.generate_key_and_nonce -> [key, nonce]`
+Convenience wrapper returning `[generate_key, generate_nonce]`.
+
+### `ChaCha20Blake3::Cipher`
+
+#### `.new(key) -> Cipher`
+Creates a cipher with the given 32-byte key (BINARY String). Raises `ArgumentError` if the key is not exactly 32 bytes.
+
+#### `#encrypt(nonce, plaintext, aad: "") -> String`
+Encrypts `plaintext` and returns a BINARY String containing the ciphertext followed by the 32-byte authentication tag. `nonce` must be exactly 24 bytes.
+
+Output length: `plaintext.bytesize + 32`
+
+#### `#decrypt(nonce, ciphertext, aad: "") -> String`
+Decrypts and authenticates `ciphertext` (which must include the 32-byte tag). Returns the plaintext as a BINARY String, or raises `ChaCha20Blake3::DecryptionError` if authentication fails.
+
+#### `#encrypt_detached(nonce, plaintext, aad: "") -> [ciphertext, tag]`
+Encrypts `plaintext`, returning ciphertext and the 32-byte tag as separate BINARY Strings.
+
+#### `#decrypt_detached(nonce, ciphertext, tag, aad: "") -> String`
+Decrypts and authenticates using a separately-provided 32-byte tag. Raises `ChaCha20Blake3::DecryptionError` on failure.
+
+### Thread Safety
+
+Both `Cipher` and `Stream` instances are safe to share across threads (and
+Ractors).
+
+`Cipher` is stateless (it only holds the key), so concurrent calls are safe
+by nature. The caller is responsible for never reusing a nonce.
+
+`Stream` holds an internal counter that determines the next nonce. All
+operations hold a mutex for the duration of encrypt/decrypt, ensuring that no
+two threads can encrypt with the same nonce. This is a security invariant,
+not just a correctness one: nonce reuse in a stream cipher is catastrophic
+(see below).
+
+### `ChaCha20Blake3::DecryptionError < StandardError`
+Raised when authentication verification fails during decryption. **Never** use this as a timing oracle - the verification is constant-time.
+
+## Security Notes
+
+### ⚠️ Don't Roll Your Own Protocol
+
+This gem is a raw AEAD cipher, not a secure protocol. If you need encrypted
+messaging, file encryption, or transport security, use a proven protocol
+library (libsodium's secretstream, Noise Framework, TLS) instead of
+combining primitives yourself.
+
+### Nonce Reuse Is Catastrophic
+
+**A (key, nonce) pair must NEVER be used to encrypt two different messages.**
+
+Nonce reuse in a stream cipher destroys confidentiality: an attacker who sees two ciphertexts encrypted with the same (key, nonce) can XOR them together, cancelling the keystream and recovering the XOR of the two plaintexts. If either plaintext has known structure (and it usually does), both are recoverable.
+
+Safe nonce strategies:
+- Use `generate_nonce` for each message (24-byte nonces make accidental collision astronomically unlikely)
+- Use a counter-based nonce with a single long-lived key
+- Derive a fresh key per session with a KDF
+
+### Key Management
+
+Keys must be treated as secrets. Use `SecureRandom.bytes(32)` or `ChaCha20Blake3.generate_key` for key generation. Never derive keys from passwords without a proper KDF (Argon2, scrypt, PBKDF2).
+
+### Tag Size
+
+The 32-byte (256-bit) tag provides 128-bit security against forgery (birthday bound). This is double the tag size of AES-GCM (128-bit tag, 64-bit forgery security) and XChaCha20-Poly1305 (128-bit tag, 64-bit forgery security).
+
+### What This Is Not
+
+- Not a key agreement protocol - use X25519 or Noise for key exchange
+- Not a password hashing function - use Argon2 for password storage
+- Not a digital signature scheme - use Ed25519 for signatures
+
+## Performance
+
+This gem peaks at ~1.27 GB/s encrypt on a 2019 MacBook Pro (i7-9750H, Linux
+VM, AVX2). The upstream Rust crate achieves 3+ GB/s on modern hardware (AMD
+EPYC 9R45) without the Ruby FFI overhead.
+
+Compared to ChaCha20-Poly1305 and AES-256-GCM via Ruby's OpenSSL bindings
+(same machine):
+
+Encrypt:
+```
+Size         CC20-B3      CC20-P1305      AES-GCM
+---------------------------------------------------
+64 B           62.0 MB/s     26.2 MB/s     27.8 MB/s
+256 B         192.5 MB/s    101.0 MB/s    114.2 MB/s
+1 KB          394.1 MB/s    287.0 MB/s    320.2 MB/s
+4 KB          639.7 MB/s    713.1 MB/s    797.5 MB/s
+64 KB          1.17 GB/s     1.30 GB/s     1.92 GB/s
+256 KB         1.22 GB/s     1.37 GB/s     1.95 GB/s
+1 MB           1.18 GB/s     1.42 GB/s     2.06 GB/s
+```
+
+Decrypt:
+```
+Size         CC20-B3      CC20-P1305      AES-GCM
+---------------------------------------------------
+64 B           62.3 MB/s     28.2 MB/s     30.0 MB/s
+256 B         191.2 MB/s    108.9 MB/s    119.2 MB/s
+1 KB          394.3 MB/s    301.3 MB/s    324.7 MB/s
+4 KB          648.4 MB/s    716.6 MB/s    876.0 MB/s
+64 KB          1.16 GB/s     1.27 GB/s     1.88 GB/s
+256 KB         1.19 GB/s     1.35 GB/s     2.00 GB/s
+1 MB           1.22 GB/s     1.36 GB/s     2.06 GB/s
+```
+
+ChaCha20-BLAKE3 is ~2x faster on small messages (lower per-call overhead).
+AES-256-GCM pulls ahead on large messages on CPUs with AES-NI. On CPUs
+without AES-NI, ChaCha20-BLAKE3 wins across the board. The tradeoff for
+slightly lower bulk throughput is a 256-bit authentication tag (128-bit
+forgery security) vs 128-bit tags in Poly1305 and GCM (64-bit forgery
+security).
+
+See [benchmarks/README.md](benchmarks/README.md) for the full 64 B - 64 MiB
+results.
+
+### Ruby binding overhead
+
+The Ruby bindings use 2 memory copies per operation (down from 3 in a naive
+implementation) due to unavoidable data copies across the FFI boundary:
+
+1. **Ruby string -> Rust Vec** - Ruby's GC can relocate string buffers at any
+   time, so the plaintext must be copied into Rust-owned memory before
+   encryption begins. This copy cannot be eliminated safely.
+2. **Encrypt/decrypt in place** - the bindings call `encrypt_in_place_detached`
+   directly on the Rust Vec, avoiding the extra allocation that the upstream
+   convenience `encrypt()` function would make internally.
+3. **Rust Vec -> Ruby string** - after encryption (or successful MAC
+   verification on decrypt), the output Ruby string is allocated at the exact
+   final size (`str_buf_new`), then filled with a single `cat()` call.
+
+The remaining bottleneck at large sizes (>2 MiB) is L3 cache eviction, not
+the FFI overhead.
+
+Run the included benchmarks:
+
+```sh
+bundle exec rake bench
+```
+
+## Building from Source
+
+```sh
+# Install Rust (if needed)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# Install gem dependencies
+bundle install
+
+# Compile the native extension
+bundle exec rake compile
+
+# Run tests
+bundle exec rake test
+
+# Run Rust unit tests
+bundle exec rake cargo_test
+
+# Lint
+bundle exec rake clippy
+```
+
+## License
+
+MIT