itb

README

No beginning. No end. Ouroboros.
Designed to protect critical data from future superintelligence.

ITB — Information-Theoretic Barrier with Ambiguity-Based Security

Security notice. ITB is an experimental symmetric cipher construction without prior peer review, independent cryptanalysis, or formal certification. The construction's security properties have not been verified by independent cryptographers or mathematicians.

PRF-grade hash functions are required. No warranty is provided.

A parameterized symmetric cipher construction library for Go that makes hash output unobservable under passive observation through two independent barrier mechanisms: noise absorption (CSPRNG random container makes hash output unobservable) and encoding ambiguity (secret rotation creates 7^P unverifiable configurations surviving CCA). Triple-seed isolation ensures compromise of any domain provides zero information about the others.

Ambiguity-Based Security: uncertainty about the correct configuration grows exponentially with data size, inverting Shannon's classical relationship. Above ~1.2 KB (no CCA) or ~2.5 KB (CCA) for 1024-bit keys, encoding ambiguity exceeds the key space. At 64 KB: 2^26,414 equally valid configurations — no computational model can enumerate them.

How the barrier works — accessible explanation

Triple Ouroboros — 7-seed variant with 3× security

Why known-plaintext and advanced attacks do not break the barrier

Empirical Red-Team validation — 12 hash primitives (including CRC128, FNV-1a lo-lane and MD5 for positive control) × 2×2 configuration matrix (Single + Triple Ouroboros × BF=1 + BF=32). Multiple empirical phases — structural / FFT / Markov, per-pixel candidate distinguisher, startPixel enumeration, ChainHash SAT-cost analysis + hash-agnostic bias audit, Direct Crib KPA SAT-cost analysis, nonce-reuse demasker with 96-cell Partial KPA matrix, 1008-cell related-seed differential, rotation-invariant edge case - all PRF-grade primitives held under the tested conditions.

Discord - invite to chat with developer.

Scientific paper (Preprint) — A. Kuvshinov, "A Symmetric Cipher Construction with Ambiguity-Based Security"

Hash direct external dependencies beyond ABI contracts and fallbacks with standard PRF primitives (BLAKE2/3, ChaCha20, AES-CMAC, SipHash-2-4, Areion-SoEM); the chain-absorb hot path is hand-written ZMM AVX-512 ASM.

Status

ITB is approaching stable release. The core API and the Go C ABI are frozen; subsequent work is bug fixes, documentation updates, and additional binding rollouts. No new cipher modes / constructions / API surfaces are planned for the open-source release.

Library

Native	Status	Features	Tests	Release	Packages
Go Native	Frozen	Fully completed	All passing	13 May 2026	TBD
C ABI (cmd/cshared)	Frozen	Fully completed	All passing	13 May 2026	TBD

Bindings

Tier 1 - Native & Thin

Binding	Backend	Status	Features	Tests	Release	Packages	Docs
C	Direct	Frozen	Fully completed	33/33 PASS	13 May 2026	TBD	README.md
C++	C	Frozen	Fully completed	44/44 PASS	13 May 2026	TBD	README.md
Fortran	Direct	Frozen	Fully completed	33/33 PASS	13 May 2026	TBD	README.md
Ada	Direct	Frozen	Fully completed	33/33 PASS	13 May 2026	TBD	README.md
D	Direct	Frozen	Fully completed	33/33 PASS	13 May 2026	TBD	README.md
Rust	Direct	Frozen	Fully completed	25/25 PASS	13 May 2026	TBD	README.md
C#	Direct	Frozen	Fully completed	368/368 PASS	13 May 2026	TBD	README.md
Python	Direct	Frozen	Fully completed	285/285 PASS	13 May 2026	TBD	README.md
Node.js	Direct	Frozen	Fully completed	288/288 PASS	13 May 2026	TBD	README.md
Java	Direct	None	In development	0/0	TBD	TBD	TBD
Scala	Java	None	In development	0/0	TBD	TBD	TBD
Kotlin	Java	None	In development	0/0	TBD	TBD	TBD
Swift	C	None	In development	0/0	TBD	TBD	TBD
Zig	C	None	In development	0/0	TBD	TBD	TBD

Tier 2 - Relay

Binding	Relay	Status	Features	Tests	Release	Packages	Docs
Erlang	C	None	In development	0/0	TBD	TBD	TBD
Elixir	BEAM	None	In development	0/0	TBD	TBD	TBD
Gleam	BEAM	None	In development	0/0	TBD	TBD	TBD
LFE	BEAM	None	In development	0/0	TBD	TBD	TBD
Groovy	Java	None	In development	0/0	TBD	TBD	TBD
Clojure	Java	None	In development	0/0	TBD	TBD	TBD
F#	C#	None	In development	0/0	TBD	TBD	TBD
VB.NET	C#	None	In development	0/0	TBD	TBD	TBD
PowerShell	C#	None	In development	0/0	TBD	TBD	TBD
Crystal	C	None	In development	0/0	TBD	TBD	TBD
Dart	C	None	In development	0/0	TBD	TBD	TBD
Haskell	C	None	In development	0/0	TBD	TBD	TBD
Julia	C	None	In development	0/0	TBD	TBD	TBD
Lua	C	None	In development	0/0	TBD	TBD	TBD
Nim	C	None	In development	0/0	TBD	TBD	TBD
OCaml	C	None	In development	0/0	TBD	TBD	TBD
PHP	C	None	In development	0/0	TBD	TBD	TBD
R	C	None	In development	0/0	TBD	TBD	TBD
Ruby	C	None	In development	0/0	TBD	TBD	TBD

Cross-platform verified. Encrypt / Decrypt round-trip validated between x86_64 (Intel / AMD) and AArch64 (Graviton 4).

Cross-binding interop verified. All 10 implementations (Go Core + 9 bindings) produce byte-identical wire format and decrypt every other implementation's output.

Full matrix:

• 10 × 10 (Go Core + 9 bindings) = 100 pairs
• 16 modes (8 base + 8 outer cipher wraps AES-128-CTR)
• 3 sizes (1 B / 1 MiB / 64 MiB)
• 4000 cells PASS

All features fully implemented. Where a binding's surface diverges from the Go Native library (e.g. no io.Reader / io.Writer adapter for Non-AEAD streaming — only User-Driven Loop), the asymmetry is intentional and follows per-language idiom rather than incomplete coverage.

Maintenance path. Subsequent open-source work covers bug fixes, documentation, and additional bindings only. Custom closed encryption constructions and downstream software stacks are available on commercial request.

Why ITB: Inverted Approach to Cryptography

Traditional symmetric ciphers (AES, ChaCha20) place all security burden on the mathematical strength of their core primitive. The keystream is XOR'd directly with plaintext — any weakness in the primitive is immediately exploitable because the attacker observes the primitive's output.

ITB inverts this approach. Instead of relying solely on the primitive's strength, the construction interposes a random container (generated from crypto/rand) between the hash output and the observer. The hash output is consumed by modifying random bytes that the attacker never sees — the original container values are never transmitted. This creates an information-theoretic barrier: no computational power can extract information that does not exist in the observation.

Why the math is simple. The construction uses only elementary operations: XOR, bitwise AND, modulo, bit shifts. There are no Galois fields, no S-boxes, no polynomial multiplication. This is not a weakness — it is a consequence of the design. The security comes from the architecture (random container, triple-seed isolation, per-bit XOR, noise embedding), not from the complexity of the math. Each architectural layer addresses a specific attack vector:

• Random container — hash output unobservable under passive observation (COA, KPA)
• Per-bit XOR (1:1) — 56 independent mask bits per pixel, every observation consistent with any plaintext
• Triple-seed isolation — CCA leaks only noiseSeed (3 bits/pixel, MAC + Reveal only); dataSeed and startSeed remain independent
• Noise bit embedding — no bit position is deterministically data from the public format

Why triple-seed is necessary. Without three independent seeds, a leak in one domain cascades: CCA reveals noise positions → same seed gives rotation and XOR → full configuration recovered. Triple-seed isolation ensures each leak is contained: CCA → only noiseSeed, cache side-channel → only startSeed, dataSeed → zero software-observable exposure. This is the minimum configuration where every leak is architecturally isolated.

Why the Barrier and PRF are Complementary. In traditional ciphers, the attacker directly observes the primitive's output (keystream XOR plaintext). Any weakness in the primitive is immediately exploitable. In ITB, the hash output is absorbed by a random container modification — the attacker sees modified random bytes, not hash outputs. Under the random-container model, every observed byte value is compatible with every possible hash output. PRF closes the candidate-verification step; barrier and architectural layers (triple-seed isolation, encoding ambiguity; plus byte-splitting under Partial KPA) deny the point of application — 3-factor combination under PRF assumption (4-factor under Partial KPA). Neither is sufficient alone: architectural layers cannot resist an invertible hash, and without the barrier the attacker observes the keystream directly (as in AES-CTR, ChaCha20), making any PRF weakness immediately exploitable. See Proof 4a.

Why quantum structural attacks are conjectured mitigated. Quantum algorithms like Simon (periodicity), BHT (collisions), and quantum differential/linear analysis require observable structural relations between inputs and outputs. The random container makes these relations unobservable — the attacker cannot build the algebraic structures that quantum algorithms exploit. Additionally, ITB's MAC oracle (when present) is inherently classical: it accepts concrete bytes over a network, not quantum superposition queries (Q2 model inapplicable). This is an architectural observation that has not been independently verified.

Important. ITB is an experimental construction without peer review or independent cryptanalysis. The information-theoretic barrier is a software-level property, reinforced by two independent barrier mechanisms: noise absorption from CSPRNG, and encoding ambiguity (56^P without CCA, 7^P under CCA) from triple-seed isolation. Architectural layers deny the point of application: independent startSeed and 8-noisePos ambiguity from independent noiseSeed under Full KPA, plus gcd(7,8)=1 byte-splitting under Partial KPA. Full KPA defense is 3-factor under PRF assumption (4-factor under Partial KPA) — see Proof 4a. It provides no guarantees against hardware-level attacks. All security claims are under the random-container model and have not been independently verified.

Installation

go get github.com/everanium/itb@latest

Building

ITB ships with two pixel-processing backends selected automatically at compile time:

Mode	Command	Pixel Processing	Requirements
CGO (default)	-buildmode=c-shared	C with SIMD auto-vectorization	C compiler (GCC/Clang) + AVX-512
No ITB ASM (CGO)	-buildmode=c-shared -tags=noitbasm	C with SIMD auto-vectorization, ITB chain-absorb / Lock Soup / Areion permutation ASM disabled — upstream stdlib ASM (zeebo/blake3, golang.org/x/crypto, jedisct1/go-aes) stays engaged	C compiler (GCC/Clang)

On AVX-512 hosts, hand-written ZMM-batched chain-absorb ASM kernels accelerate the per-pixel hash hot path 2×-7× over the per-call -tags=noitbasm fallback across all nine PRF-grade primitives (Areion-SoEM-256/512, BLAKE2b-256/512, BLAKE2s, BLAKE3, AES-CMAC, SipHash-2-4, ChaCha20) — see BENCH.md / BENCH3.md for measured numbers on Intel Rocket Lake and AMD EPYC 9655P (Zen 5). CGO mode (default) layers a C per-pixel kernel on top of the hash dispatch; building with CGO_ENABLED=0 swaps that for a portable Go pixel pipeline while the Go-assembly ZMM chain-absorb hash kernels stay engaged when AVX-512 is present. Per-pixel kernel uses three runtime-dispatched tiers:

• Tier A — AVX-512F + AVX-512BW + AVX-512VL + GFNI + AVX-512VBMI: 8-pixel ZMM batch. Phase 1 (extract 8×56 bits) fuses VPERMB + VPSRLQ + VPMULTISHIFTQB into 5 ZMM ops. Phase 4 (per-pixel rotate) and Phase 5 (per-pixel noise-bit insert) lower to single VGF2P8AFFINEQB ZMM ops. Insane Interlocked Mode (SetLockSoup(1)) on Single Ouroboros lowers its per-chunk bit-permutation to a native AVX-512 VBMI VPERMB + VPMOVM2B + VPTESTMB ASM kernel, with a Pure Go bit-shift gather fallback on hosts without AVX-512 VBMI. Active on Intel Rocket Lake / Tiger Lake / Sapphire Rapids+ and AMD Zen 4 / Zen 5.
• Tier B — AVX2 + GFNI: 4-pixel YMM batch. Same five-phase shape, halved width. Phase 3-5 use VPXOR / VGF2P8AFFINEQB / VPAND / VPOR on YMM. Active on Intel Coffee Lake+ and AMD Zen 3+ (covers Alder Lake E-cores and similar AVX-512-disabled deployments). Insane Interlocked Mode (SetLockSoup(1)) lowers its per-chunk bit-permutation to a native BMI2 PEXTL/PDEPL ASM kernel, with a Pure Go fallback on hosts without BMI2.
• Tier C — Fallback: 4-pixel batched scalar loop, same memory layout as Tier B with no SIMD intrinsics. Runs on every host GCC supports — IFUNC is not used, so macOS Mach-O and Windows COFF builds reach this path through the same runtime branch as Linux/FreeBSD ELF. ARM64 (NEON) intrinsics are not yet implemented and currently route through this tier; GCC -O3 still auto-vectorizes byte-parallel phases to NEON in a limited form.

CGO speedup also covers L1-cache-friendly micro-batching (512 pixels per C call), parallel noise/data hash computation through BatchHashFunc factories, sync.Pool for hash array reuse, and __builtin_prefetch 8 pixels ahead of the current iteration.

Platform	Per-pixel kernel	Areion-SoEM batched dispatch
amd64 + AVX-512+GFNI+VBMI (Intel Rocket Lake / Tiger Lake+, AMD Zen 4+)	Tier A (ZMM, 8-pixel batch)	AVX-512+VAES ASM, 4-lane batch + SoEM two-half ILP interleaving (internal/areionasm/areion_amd64.s)
amd64 + AVX2+GFNI (AMD Zen 3+, Coffee Lake+)	Tier B (YMM, 4-pixel batch)	AVX2+VAES ASM, 4-lane per-half permute (no SoEM ILP — AVX-512-only)
amd64 without VAES / older	Tier C — Fallback	Go fallback via aes.Round4HW
arm64 + ARM Crypto Extension (Graviton 2+, Apple M1+, Neoverse N1+/V1+/V2+)	Tier C — Fallback	ARM Crypto Extension AArch64 ASM, 4-lane parallel AESE/AESMC (internal/areionasm/areion_arm64.s)
other GCC targets (RISC-V, PowerPC, MIPS, …)	Tier C — Fallback	Go fallback via aes.Round4HW
CGO_ENABLED=0	Pure Go (process_generic.go)	Go fallback

Hash computation remains in Go in both modes (pluggable hash functions); the C pixel kernel is platform-portable through __attribute__((target(...))) per-helper feature gates rather than IFUNC, so non-Linux/non-FreeBSD targets degrade gracefully.

Usage

# Build shared library
git clone https://github.com/everanium/itb && cd itb

# CGO backend (default)
cd cmd/cshared && go build -buildmode=c-shared -o ../../dist/linux-amd64/libitb.so .

# CGO backend (most portable, audit-grade deterministic)
cd cmd/cshared && go build -buildmode=c-shared -tags=noitbasm -o ../../dist/linux-amd64/libitb.so .

Memory

Two process-wide knobs constrain Go runtime arena pacing. Both readable at libitb load time via env vars:

• ITB_GOMEMLIMIT=512MiB — soft memory limit in bytes; supports B / KiB / MiB / GiB / TiB suffixes.
• ITB_GOGC=20 — GC trigger percentage; default 100, lower triggers GC more aggressively.

Programmatic setters override env-set values at any time. Pass -1 to either setter to query the current value without changing it.

itb.SetMemoryLimit(512 << 20)
itb.SetGCPercent(20)

Tests

# CGO backend (default)
go test -timeout=3600s -race ./...

# CGO backend (most portable, audit-grade deterministic)
go test -tags=noitbasm -timeout=3600s -race ./...

# Pure Go
CGO_ENABLED=0 go test -timeout=3600s . ./easy ./hashes ./macs ./internal/...
CGO_ENABLED=0 go test -tags=noitbasm -timeout=3600s . ./easy ./hashes ./macs ./internal/...

Benchmarks

# CGO backend (default)
go test -bench='Benchmark*' -run='^$' -benchtime=5s -count=1 .

# CGO backend (most portable, audit-grade deterministic)
go test -tags=noitbasm -bench='Benchmark*' -run='^$' -benchtime=5s -count=1 .

# Pure Go backend
CGO_ENABLED=0 go test -bench='Benchmark*' -run='^$' -benchtime=5s -count=1 .
CGO_ENABLED=0 go test -tags=noitbasm -bench='Benchmark*' -run='^$' -benchtime=5s -count=1 .

Coverage

go test -coverprofile=coverage.out $(go list ./... | grep -vE 'tools/eitb|cmd/cshared$')

Performance

Full benchmark results across all ITB key sizes (512, 1024, 2048 bit), hash functions, and CPUs: BENCH.md Triple Ouroboros benchmarks (7-seed, 3× security): BENCH3.md

Throughput scales with data size due to goroutine parallelism across CPU cores. CGO mode uses three runtime-dispatched per-pixel kernel tiers (AVX-512+GFNI+VBMI 8-pixel ZMM, AVX2+GFNI 4-pixel YMM, Tier C scalar) plus AVX-512 ZMM-batched chain-absorb hash kernels for every PRF-grade primitive (hashes/internal/<primitive>asm plus internal/areionasm for Areion-SoEM). CGO_ENABLED=0 alone swaps only the C pixel kernel for the portable Go pipeline; the ZMM-batched hash ASM and upstream stdlib ASM stay engaged via Go assembly, so end-to-end throughput stays close to the CGO default on AVX-512 hosts. The full scalar fallback is not usable with ITB (-tags=purego, where every upstream module honours the convention) is ~20×–100× slower when the ZMM hash kernels fall back to per-call scalar references — every primitive picks up a measurable ZMM uplift, but the relative gap is widest on the BLAKE / ARX primitives (heavier per-call closure overhead amortised across four lanes) and narrowest on AES-CMAC / SipHash-2-4, whose scalar paths already run AES-NI-accelerated through crypto/aes and the hand-tuned dchest/siphash assembly so the batched arm has less headroom to recover. The middle ground is -tags=noitbasm — disables the ITB chain-absorb wrapper while leaving upstream hash ASM engaged; throughput tracks the OLDBENCH single-Func numbers on hosts without AVX-512+VL where the 4-lane batched wrapper would be dead weight. Decrypt does not require crypto/rand and scales further on high-core-count CPUs.

Parallelism Control

itb.SetMaxWorkers(4) // limit to 4 CPU cores for pixel processing

By default, ITB uses all available CPU cores. On shared servers, use SetMaxWorkers to limit CPU usage. Pass 0 to use all CPUs (default). Valid range: 0–256. Thread-safe (atomic). Query with itb.GetMaxWorkers().

Nonce Configuration

itb.SetNonceBits(256) // 256-bit nonce (~2^128 birthday bound)

Default nonce is 128 bits (birthday collision at ~2^64 messages). For higher collision resistance, use SetNonceBits. Valid values: 128, 256, 512. Panics on invalid input. Both sender and receiver must use the same nonce size. Query with itb.GetNonceBits().

Barrier Fill (CSPRNG Margin)

itb.SetBarrierFill(4) // side += 4 instead of default side += 1

Controls the CSPRNG fill margin added to the container side dimension. The construction guarantees that every container has strictly more pixel capacity than the payload requires — the excess capacity is filled with crypto/rand data encrypted by dataSeed. This CSPRNG residue is indistinguishable from encrypted plaintext and provides information-theoretic ambiguity within the data channel (Proof 10).

Valid values: 1, 2, 4, 8, 16, 32. Default: 1. Panics on invalid input. Thread-safe (atomic). Query with itb.GetBarrierFill().

Why this matters after CCA. Under CCA (MAC + Reveal), the attacker identifies and removes noise bits (12.5% of container), bypassing mechanism 1 (noise absorption). But CSPRNG fill bytes remain in the data bit positions — encrypted identically to plaintext by dataSeed (rotation + XOR). COBS decoding stops at the 0x00 null terminator and never reaches the fill region, so the fill content is never constrained by the plaintext structure. The attacker cannot distinguish encrypted plaintext from encrypted CSPRNG fill without the correct dataSeed. Although CCA reveals noise bit positions (bypassing the noise-position uncertainty of mechanism 1), CSPRNG residue in data positions provides independent information-theoretic ambiguity that persists regardless of CCA.

The rotation barrier (7^P from Proof 4) remains complemented by this reduced information-theoretic barrier from CSPRNG fill. Three layers operate in every scenario:

Layer	Core ITB	After CCA (MAC + Reveal)
Noise absorption (mechanism 1)	Full (8 noise bits/pixel)	Partial — noise bits removed, CSPRNG fill in data positions survives
Encoding ambiguity (mechanism 2)	56^P	7^P (rotation only)
Brute-force cost	P × 2^(2×keyBits)	P × 2^keyBits

Asymmetric property. The receiver does not need the same SetBarrierFill value as the sender. Encrypt writes the container dimensions (W×H) into the header; Decrypt reads W×H from the header and processes whatever pixels are present. A larger fill margin on the sender side increases CSPRNG residue without requiring any configuration change on the receiver. This confirms the configurable nature of the information-theoretic barrier — the sender can independently tune the CSPRNG fill margin.

Hash Function Selection

ITB accepts pluggable hash functions at three widths. Requirements: the hash must process all input bytes with non-invertible, non-affine, avalanche mixing that survives the ChainHash XOR-chain. PRF required. Under PRF assumption, Full KPA resistance is 3-factor: PRF non-invertibility, independent startSeed, and per-pixel 1:1 ambiguity — all combine conjunctively. gcd(7,8)=1 byte-splitting is a 4th factor effective only under Partial KPA. Note: complete PRF inversion would collapse the architectural layers via seed recovery; the multi-factor property protects against partial PRF weakness, not total failure.

All nine primitives are PRF-grade and accept ITB key sizes up to 2048 bits (itb.MaxKeyBits); the per-width minimum is 512 bits and the bit count must be a multiple of the hash's native state width (128 / 256 / 512). The Public Pair API column lists the hashes.<Primitive>Pair() factory which returns the (single, batched) closure pair; the batched arm wires the ZMM-batched chain-absorb dispatch through Seed.BatchHash automatically.

Hash	Type	ASM Acceleration	Public Pair API	Upstream Library
Areion-SoEM-256	HashFunc256	VAES + AVX-512 ZMM (4-lane chain-absorb) · VAES + AVX-2 YMM fallback · AES-NI scalar	hashes.Areion256Pair()	github.com/jedisct1/go-aes
Areion-SoEM-512	HashFunc512	VAES + AVX-512 ZMM (4-lane chain-absorb) · VAES + AVX-2 YMM fallback · AES-NI scalar	hashes.Areion512Pair()	github.com/jedisct1/go-aes
SipHash-2-4	HashFunc128	AVX-512 ZMM ARX (VPADDQ / VPXORQ / VPROLQ, 4-lane)	hashes.SipHash24Pair()	github.com/dchest/siphash
AES-CMAC	HashFunc128	VAES + AVX-512 ZMM (4-lane CBC-MAC) · AES-NI scalar	hashes.AESCMACPair()	crypto/aes (stdlib)
BLAKE2b-512	HashFunc512	AVX-512 ZMM ARX (VPADDQ / VPXORQ / VPRORQ, 4-lane)	hashes.BLAKE2b512Pair()	golang.org/x/crypto/blake2b
BLAKE2b-256	HashFunc256	AVX-512 ZMM ARX (VPADDQ / VPXORQ / VPRORQ, 4-lane)	hashes.BLAKE2b256Pair()	golang.org/x/crypto/blake2b
BLAKE2s	HashFunc256	AVX-512 ZMM ARX (VPADDD / VPXORD / VPRORD, 4-lane)	hashes.BLAKE2s256Pair()	golang.org/x/crypto/blake2s
BLAKE3	HashFunc256	AVX-512 ZMM ARX (VPADDD / VPXORD / VPRORD, 4-lane keyed-mode)	hashes.BLAKE3256Pair()	github.com/zeebo/blake3
ChaCha20	HashFunc256	AVX-512 ZMM ARX (VPADDD / VPXORD / VPROLD, 4-lane)	hashes.ChaCha20256Pair()	golang.org/x/crypto/chacha20

Choosing the Right Hash Width

The effective key size is determined by the seed input width of the hash function — not its output width. This is a critical distinction:

Effective max key = min(keyBits, seedInputWidth × numRounds)

Why Wider Hash = Faster with Wider MITM Bottleneck

With a 512-bit key (8 components), ChainHash processes components in groups matching the hash width:

Hash width	Components/round	Rounds	Hash calls/pixel
128-bit	2	4	4
256-bit	4	2	2
512-bit	8	1	1

All 8 components are consumed in every case — no key material is skipped. A 256-bit hash simply processes 4 components per call instead of 1.

Faster: each hash call has overhead (state initialization, finalization). For heavy hash functions (BLAKE3: ~300ns/call, BLAKE2b: ~200ns/call), fewer calls = proportionally faster.

Wider MITM bottleneck: the wider intermediate state makes meet-in-the-middle attacks harder. With 256-bit state, an attacker must enumerate 2^256 possible intermediate values (vs 2^128 for a 128-bit hash). Additionally, fewer chain rounds means fewer potential split points for the attacker.

Bottom line: prefer the widest available PRF variant — it's both faster and provides a wider MITM bottleneck.

ASIC Scalability

FPGA proof-of-concept is planned using open-source Verilog IP cores for SipHash and ChaCha20 DRBG, with a custom ITB pixel pipeline. Target: full encrypt/decrypt roundtrip on a single FPGA chip.

ITB's elementary operations (XOR, bitwise AND, modulo, bit shift, rotate) are trivial to implement in hardware. The construction's per-pixel parallelism (each pixel is independent) enables linear scalability through parallel processing units.

Pixel processing in ASIC:

• All operations are combinational logic: XOR gates, barrel shifters, adders
• No S-box ROM, no lookup tables, no GF(2^8) multiplier required
• Each pixel can be processed by an independent hardware unit
• 8 channels per pixel can be processed in parallel (8-wide datapath)
• No DPA attack surface — register-only operations in silicon

Hash engine:

• ARX-based PRF hash functions (BLAKE3) are pipeline-friendly in hardware
• Multiple hash engines can run in parallel (one per pixel pipeline)
• No S-box in silicon — no DPA attack surface at the hardware level

Primary engineering challenge — PRNG throughput:

• Container generation (crypto/rand) is the throughput bottleneck in software (~735 MB/s on modern CPUs)
• In ASIC, a custom ChaCha20-based DRBG (ARX, DPA-free) seeded from a certified TRNG IP core generates random container fill, not cryptographic keys
• Seeds (triple-seed) are external pre-shared inputs, not generated by the DRBG — they are loaded into ASIC secure registers via external key exchange
• A single ChaCha20 DRBG core at ~4 GB/s may be sufficient — the pixel processing pipeline (2 hash calls per pixel) becomes the bottleneck before DRBG does
• Scaling is achieved by adding parallel pixel pipelines, not additional DRBG cores
• Decrypt does not require PRNG (no container generation) — decrypt throughput is limited only by hash engine and memory bandwidth

DPA-free full stack:

• TRNG (certified IP core) → ChaCha20 DRBG streaming (custom, ARX) → ARX hash engine (BLAKE3) → pixel processing (XOR, shift, rotate) — zero table lookups from PRNG to output, no DPA attack surface at any level

Theoretical throughput:

• With ChaCha20 DRBG + parallel hash engines + parallel pixel processing, ASIC implementations could theoretically achieve >1-2 GB/s for both encrypt and decrypt — the problem is purely engineering, not architectural
• Decrypt throughput could exceed encrypt due to absence of PRNG overhead

Concurrency

A single easy.Encryptor is NOT safe for concurrent use from multiple goroutines — cipher methods (Encrypt / Decrypt / EncryptAuth / DecryptAuth), per-instance setters, and Close / Import all mutate per-instance state without locking. Sharing one Encryptor across goroutines requires external synchronisation; distinct Encryptor values, each owned by one goroutine, run independently against the libitb worker pool.

By contrast, the low-level cipher free functions (itb.Encrypt128 / itb.Decrypt128 / itb.EncryptAuthenticated128 / itb.DecryptAuthenticated128 and Cfg variants plus the 256 / 512 width counterparts) take read-only Seed pointers and allocate output per call — they are thread-safe under concurrent invocation on the same seeds. The exception is the shared *itb.Config: concurrent setter mutations on a Config that other goroutines are reading must be serialised by the caller.

Caveat — Process-wide itb.Set* setters (SetNonceBits / SetBarrierFill / SetMaxWorkers / SetBitSoup / SetLockSoup) are atomic and safe to call from any goroutine. Atomic, but not logically race-free. Each setter performs a single atomic.Int32.Store, so concurrent setter calls race-free by themselves; but mutating any of these knobs while an encrypt or decrypt call is in flight corrupts the running operation. The cipher snapshots its configuration at call entry and a mid-flight change breaks the running invariants — same plaintext shipped through two halves of the call under different settings will not round-trip on the receiver. Treat the global knobs as set-once-at-startup; rare runtime updates need external sequencing against active cipher calls.

Streaming AEAD

Streaming AEAD authenticates a chunked stream end-to-end while preserving the deniability of the per-chunk MAC-Inside-Encrypt container. Each chunk's MAC binds the encrypted payload to a 32-byte CSPRNG stream anchor (written as a once-per-stream wire prefix), the cumulative pixel offset of preceding chunks, and a final-flag bit — defending against chunk reorder, replay within or across streams sharing the PRF / MAC key, silent mid-stream drop, and truncate-tail. The wire format adds 32 bytes of stream prefix plus one byte of encrypted trailing flag per chunk; no externally visible MAC tag.

All four examples below encrypt a 64 MiB random source file in 16 MiB chunks and verify sha256 round-trip on the decrypted output. The Easy paths drive the cipher through easy.Encryptor (per-instance configuration snapshot, internal MAC key allocation); the Low-Level paths drive the same cipher through the top-level free functions itb.EncryptStream / itb.EncryptStreamAuth and decrypt counterparts (process-wide configuration via itb.Set*, explicit seed + MAC handles).

Streaming Bindings Asymmetry

The Go core and the easy package expose io.Reader / io.Writer entry points for both the Streaming AEAD path and the plain (No Mac) stream path. The official language bindings (Ada, C, C++, C#, D, Fortran, Rust, Node.js, Python and other bindings) expose IO-Driven helpers for the Streaming AEAD path only; their plain-stream surface is a per-chunk free-function call with the caller driving the read/write loop. The two patterns produce identical on-wire bytes — the Alternative examples in the No Mac subsections below mirror the binding-side idiom for callers who prefer external control over chunk granularity and back-pressure.

Quick Start

Streaming AEAD Easy (MAC Authenticated)

The high-level easy.Encryptor.EncryptStreamAuthIO consumes an io.Reader plus an explicit chunk size, generates the 32-byte stream_id prefix internally, drains the reader in chunkSize-byte windows, and writes each on-wire chunk to the supplied io.Writer in stream order. The matching DecryptStreamAuthIO reads the prefix, walks the wire bytes one chunk at a time, and writes recovered plaintext to the output writer. The MAC key is allocated CSPRNG-fresh inside the encryptor at construction time and is not exposed to the caller.

package main

import (
    "bufio"
    "os"

    "github.com/everanium/itb"
    "github.com/everanium/itb/easy"
    "github.com/everanium/itb/wrapper"
)

const (
    srcPath   = "/tmp/64mb.src"
    encPath   = "/tmp/64mb.enc"
    dstPath   = "/tmp/64mb.dst"
    chunkSize = 16 * 1024 * 1024
)

func main() {
    itb.SetMaxWorkers(8)             // process-wide: limit to 8 CPU cores

    enc := easy.New("areion512", 1024, "hmac-blake3")
    defer enc.Close()
    enc.SetNonceBits(512)            // 512-bit nonce
    enc.SetBarrierFill(4)            // CSPRNG fill margin
    enc.SetBitSoup(1)                // bit-level split
    enc.SetLockSoup(1)               // Insane Interlocked Mode

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)

    {
        fin, _ := os.Open(srcPath)
        fout, _ := os.Create(encPath)
        br, bw := bufio.NewReader(fin), bufio.NewWriter(fout)
        // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
        // ~0% overhead (Recommended in every case).
        wrapWriter, _ := wrapper.NewWrapWriter(wrapper.CipherAES128CTR, outerKey, bw)
        if err := enc.EncryptStreamAuthIO(br, wrapWriter, chunkSize); err != nil {
            panic(err)
        }
        bw.Flush(); fin.Close(); fout.Close()
    }
    {
        fin, _ := os.Open(encPath)
        fout, _ := os.Create(dstPath)
        br, bw := bufio.NewReader(fin), bufio.NewWriter(fout)
        unwrapReader, _ := wrapper.NewUnwrapReader(wrapper.CipherAES128CTR, outerKey, br)
        if err := enc.DecryptStreamAuthIO(unwrapReader, bw); err != nil {
            panic(err)
        }
        bw.Flush(); fin.Close(); fout.Close()
    }
}

Streaming AEAD Low-Level (MAC Authenticated)

Top-level free functions itb.EncryptStreamAuth / itb.DecryptStreamAuth take three explicit *Seed{N} handles plus a MACFunc closure built from the macs/ factory and stream through the same chunked-AEAD construction directly over io.Reader / io.Writer. The seeds are constructed via itb.NewSeed512 paired with the matching hash factory from the hashes/ registry; the MAC closure is built from a 32-byte CSPRNG key plus macs.Make("hmac-blake3", key). Process-wide setters configure the cipher; no per-instance Config snapshot exists at the low-level surface.

package main

import (
    "bufio"
    "crypto/rand"
    "os"

    "github.com/everanium/itb"
    "github.com/everanium/itb/hashes"
    "github.com/everanium/itb/macs"
    "github.com/everanium/itb/wrapper"
)

const (
    srcPath   = "/tmp/64mb.src"
    encPath   = "/tmp/64mb.enc"
    dstPath   = "/tmp/64mb.dst"
    chunkSize = 16 * 1024 * 1024
)

func main() {
    itb.SetMaxWorkers(8)             // process-wide: limit to 8 CPU cores
    itb.SetNonceBits(512)
    itb.SetBarrierFill(4)
    itb.SetBitSoup(1)
    itb.SetLockSoup(1)

    // Four independent CSPRNG-keyed Areion-SoEM-512 paired closures
    // (noise / data / start / lock). The batched arm wires the AVX-512 +
    // VAES + ZMM chain-absorb dispatch through Seed.BatchHash — without
    // it dispatch falls back to the legacy single-call path.
    fnN, batchN, _, _ := hashes.Make512Pair("areion512")
    fnD, batchD, _, _ := hashes.Make512Pair("areion512")
    fnS, batchS, _, _ := hashes.Make512Pair("areion512")
    fnL, batchL, _, _ := hashes.Make512Pair("areion512")

    noise, _ := itb.NewSeed512(1024, fnN); noise.BatchHash = batchN
    data,  _ := itb.NewSeed512(1024, fnD); data.BatchHash  = batchD
    start, _ := itb.NewSeed512(1024, fnS); start.BatchHash = batchS
    lock,  _ := itb.NewSeed512(1024, fnL); lock.BatchHash  = batchL

    // Optional dedicated lockSeed for the Lock Soup bit-permutation
    // channel — keying-material isolation plus algorithm-diversity
    // defence-in-depth on top of the per-chunk keyed-permutation floor,
    // without changing the public Encrypt / Decrypt signatures.
    noise.AttachLockSeed(lock)

    macKey := make([]byte, 32)
    rand.Read(macKey)
    macFunc, err := macs.Make("hmac-blake3", macKey)
    if err != nil { panic(err) }

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)

    {
        fin, _ := os.Open(srcPath)
        fout, _ := os.Create(encPath)
        br, bw := bufio.NewReader(fin), bufio.NewWriter(fout)
        // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
        // ~0% overhead (Recommended in every case).
        wrapWriter, _ := wrapper.NewWrapWriter(wrapper.CipherAES128CTR, outerKey, bw)
        if err := itb.EncryptStreamAuth(noise, data, start, br, wrapWriter, macFunc, chunkSize); err != nil {
            panic(err)
        }
        bw.Flush(); fin.Close(); fout.Close()
    }
    {
        fin, _ := os.Open(encPath)
        fout, _ := os.Create(dstPath)
        br, bw := bufio.NewReader(fin), bufio.NewWriter(fout)
        unwrapReader, _ := wrapper.NewUnwrapReader(wrapper.CipherAES128CTR, outerKey, br)
        if err := itb.DecryptStreamAuth(noise, data, start, unwrapReader, bw, macFunc); err != nil {
            panic(err)
        }
        bw.Flush(); fin.Close(); fout.Close()
    }
}

Streaming Easy (No MAC)

The plain (non-authenticated) cipher path through easy.Encryptor. EncryptStreamIO walks the reader in chunkSize-byte windows and emits each ITB wire chunk verbatim; DecryptStreamIO recovers chunk extents from the on-wire W / H header per chunk, so no length prefix is needed at the application layer. No stream_id prefix and no per-chunk MAC tag — wrong- seed input produces random-looking plaintext rather than an error, and truncate-tail / reorder are not detected.

package main

import (
    "bufio"
    "os"

    "github.com/everanium/itb"
    "github.com/everanium/itb/easy"
    "github.com/everanium/itb/wrapper"
)

const encPlainPath = "/tmp/64mb_plain.enc"
const dstPlainPath = "/tmp/64mb_plain.dst"

func main() {
    itb.SetMaxWorkers(8)             // process-wide: limit to 8 CPU cores

    enc := easy.New("areion512", 1024)
    defer enc.Close()
    enc.SetNonceBits(512)
    enc.SetBarrierFill(4)
    enc.SetBitSoup(1)
    enc.SetLockSoup(1)

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)

    {
        fin, _ := os.Open(srcPath)
        fout, _ := os.Create(encPlainPath)
        br, bw := bufio.NewReader(fin), bufio.NewWriter(fout)
        // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
        // ~0% overhead (Recommended in every case).
        wrapWriter, _ := wrapper.NewWrapWriter(wrapper.CipherAES128CTR, outerKey, bw)
        if err := enc.EncryptStreamIO(br, wrapWriter, chunkSize); err != nil {
            panic(err)
        }
        bw.Flush(); fin.Close(); fout.Close()
    }
    {
        fin, _ := os.Open(encPlainPath)
        fout, _ := os.Create(dstPlainPath)
        br, bw := bufio.NewReader(fin), bufio.NewWriter(fout)
        unwrapReader, _ := wrapper.NewUnwrapReader(wrapper.CipherAES128CTR, outerKey, br)
        if err := enc.DecryptStreamIO(unwrapReader, bw); err != nil {
            panic(err)
        }
        bw.Flush(); fin.Close(); fout.Close()
    }
}

Alternative — User-Driven Loop (No memory residency):

The same easy.Encryptor exposes per-chunk Encrypt / Decrypt methods. Driving the read / write loop in caller code mirrors the per-chunk shape exposed by the official language bindings — useful when the caller wants explicit control over chunk granularity, back-pressure, or interleaved work between chunks. The on-wire bytes are wire-format-compatible with the IO method's output above: each on-wire chunk's own W / H header carries its length, so the decrypter walks the stream by reading enc.HeaderSize() bytes, calling enc.ParseChunkLen to learn the chunk's total wire length, then reading the body — no application-level length prefix required.

package main

import (
    "bufio"
    "io"
    "os"

    "github.com/everanium/itb"
    "github.com/everanium/itb/easy"
    "github.com/everanium/itb/wrapper"
)

const encPlainPath = "/tmp/64mb_plain.enc"
const dstPlainPath = "/tmp/64mb_plain.dst"

func main() {
    itb.SetMaxWorkers(8)             // process-wide: limit to 8 CPU cores

    enc := easy.New("areion512", 1024)
    defer enc.Close()
    enc.SetNonceBits(512)
    enc.SetBarrierFill(4)
    enc.SetBitSoup(1)
    enc.SetLockSoup(1)

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)

    {
        fin, _ := os.Open(srcPath)
        fout, _ := os.Create(encPlainPath)
        br, bw := bufio.NewReader(fin), bufio.NewWriter(fout)
        // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
        // ~0% overhead (Recommended in every case).
        wrapWriter, _ := wrapper.NewWrapWriter(wrapper.CipherAES128CTR, outerKey, bw)
        buf := make([]byte, chunkSize)
        for {
            n, rerr := io.ReadFull(br, buf)
            if rerr == io.EOF { break }
            if rerr != nil && rerr != io.ErrUnexpectedEOF { panic(rerr) }
            ct, err := enc.Encrypt(buf[:n])
            if err != nil { panic(err) }
            wrapWriter.Write(ct)
            if rerr == io.ErrUnexpectedEOF { break }
        }
        bw.Flush(); fin.Close(); fout.Close()
    }
    {
        fin, _ := os.Open(encPlainPath)
        fout, _ := os.Create(dstPlainPath)
        br, bw := bufio.NewReader(fin), bufio.NewWriter(fout)
        unwrapReader, _ := wrapper.NewUnwrapReader(wrapper.CipherAES128CTR, outerKey, br)
        header := make([]byte, enc.HeaderSize())
        for {
            _, rerr := io.ReadFull(unwrapReader, header)
            if rerr == io.EOF { break }
            if rerr != nil { panic(rerr) }
            chunkLen, err := enc.ParseChunkLen(header)
            if err != nil { panic(err) }
            body := make([]byte, chunkLen-len(header))
            io.ReadFull(unwrapReader, body)
            chunk := append(append(make([]byte, 0, chunkLen), header...), body...)
            pt, err := enc.Decrypt(chunk)
            if err != nil { panic(err) }
            bw.Write(pt)
        }
        bw.Flush(); fin.Close(); fout.Close()
    }
}

Streaming Low-Level (No MAC)

Top-level free functions itb.EncryptStream / itb.DecryptStream take three explicit *Seed{N} handles (no MAC argument) and stream through the plain-Single-Ouroboros chunk pipeline directly over io.Reader / io.Writer. On-wire format = standard ITB chunk concatenation with no stream_id prefix and no per-chunk MAC tag.

package main

import (
    "bufio"
    "os"

    "github.com/everanium/itb"
    "github.com/everanium/itb/hashes"
    "github.com/everanium/itb/wrapper"
)

const encPlainPath = "/tmp/64mb_plain.enc"
const dstPlainPath = "/tmp/64mb_plain.dst"

func main() {
    itb.SetMaxWorkers(8)             // process-wide: limit to 8 CPU cores
    itb.SetNonceBits(512)
    itb.SetBarrierFill(4)
    itb.SetBitSoup(1)
    itb.SetLockSoup(1)

    // Four independent CSPRNG-keyed Areion-SoEM-512 paired closures
    // (noise / data / start / lock). The batched arm wires the AVX-512 +
    // VAES + ZMM chain-absorb dispatch through Seed.BatchHash — without
    // it dispatch falls back to the legacy single-call path.
    fnN, batchN, _, _ := hashes.Make512Pair("areion512")
    fnD, batchD, _, _ := hashes.Make512Pair("areion512")
    fnS, batchS, _, _ := hashes.Make512Pair("areion512")
    fnL, batchL, _, _ := hashes.Make512Pair("areion512")

    noise, _ := itb.NewSeed512(1024, fnN); noise.BatchHash = batchN
    data,  _ := itb.NewSeed512(1024, fnD); data.BatchHash  = batchD
    start, _ := itb.NewSeed512(1024, fnS); start.BatchHash = batchS
    lock,  _ := itb.NewSeed512(1024, fnL); lock.BatchHash  = batchL

    // Optional dedicated lockSeed for the Lock Soup bit-permutation
    // channel — keying-material isolation plus algorithm-diversity
    // defence-in-depth on top of the per-chunk keyed-permutation floor,
    // without changing the public Encrypt / Decrypt signatures.
    noise.AttachLockSeed(lock)

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)

    {
        fin, _ := os.Open(srcPath)
        fout, _ := os.Create(encPlainPath)
        br, bw := bufio.NewReader(fin), bufio.NewWriter(fout)
        // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
        // ~0% overhead (Recommended in every case).
        wrapWriter, _ := wrapper.NewWrapWriter(wrapper.CipherAES128CTR, outerKey, bw)
        if err := itb.EncryptStream(noise, data, start, br, wrapWriter, chunkSize); err != nil {
            panic(err)
        }
        bw.Flush(); fin.Close(); fout.Close()
    }
    {
        fin, _ := os.Open(encPlainPath)
        fout, _ := os.Create(dstPlainPath)
        br, bw := bufio.NewReader(fin), bufio.NewWriter(fout)
        unwrapReader, _ := wrapper.NewUnwrapReader(wrapper.CipherAES128CTR, outerKey, br)
        if err := itb.DecryptStream(noise, data, start, unwrapReader, bw); err != nil {
            panic(err)
        }
        bw.Flush(); fin.Close(); fout.Close()
    }
}

Alternative — User-Driven Loop (No memory residency):

The Go-core width-less itb.Encrypt / itb.Decrypt helpers operate on a single chunk at a time. Driving the read / write loop in caller code mirrors the per-chunk shape exposed by the official language bindings' No Mac plain-stream surface — useful when the caller wants explicit control over chunk granularity, back-pressure, or interleaved work between chunks. Each chunk's wire bytes are framed with a 4-byte big-endian length prefix (binding-style framing) so the decrypter can read one chunk's worth of bytes into a fresh buffer per iteration without parsing the on-wire ITB header.

package main

import (
    "bufio"
    "io"
    "os"

    "github.com/everanium/itb"
    "github.com/everanium/itb/hashes"
    "github.com/everanium/itb/wrapper"
)

const encPlainPath = "/tmp/64mb_plain.enc"
const dstPlainPath = "/tmp/64mb_plain.dst"

func main() {
    itb.SetMaxWorkers(8)             // process-wide: limit to 8 CPU cores
    itb.SetNonceBits(512)
    itb.SetBarrierFill(4)
    itb.SetBitSoup(1)
    itb.SetLockSoup(1)

    // Four independent CSPRNG-keyed Areion-SoEM-512 paired closures
    // (noise / data / start / lock). The batched arm wires the AVX-512 +
    // VAES + ZMM chain-absorb dispatch through Seed.BatchHash — without
    // it dispatch falls back to the legacy single-call path.
    fnN, batchN, _, _ := hashes.Make512Pair("areion512")
    fnD, batchD, _, _ := hashes.Make512Pair("areion512")
    fnS, batchS, _, _ := hashes.Make512Pair("areion512")
    fnL, batchL, _, _ := hashes.Make512Pair("areion512")

    noise, _ := itb.NewSeed512(1024, fnN); noise.BatchHash = batchN
    data,  _ := itb.NewSeed512(1024, fnD); data.BatchHash  = batchD
    start, _ := itb.NewSeed512(1024, fnS); start.BatchHash = batchS
    lock,  _ := itb.NewSeed512(1024, fnL); lock.BatchHash  = batchL

    // Optional dedicated lockSeed for the Lock Soup bit-permutation
    // channel — keying-material isolation plus algorithm-diversity
    // defence-in-depth on top of the per-chunk keyed-permutation floor,
    // without changing the public Encrypt / Decrypt signatures.
    noise.AttachLockSeed(lock)

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)

    {
        fin, _ := os.Open(srcPath)
        fout, _ := os.Create(encPlainPath)
        br, bw := bufio.NewReader(fin), bufio.NewWriter(fout)
        // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
        // ~0% overhead (Recommended in every case).
        wrapWriter, _ := wrapper.NewWrapWriter(wrapper.CipherAES128CTR, outerKey, bw)
        buf := make([]byte, chunkSize)
        var lenBuf [4]byte
        for {
            n, rerr := io.ReadFull(br, buf)
            if rerr == io.EOF { break }
            if rerr != nil && rerr != io.ErrUnexpectedEOF { panic(rerr) }
            ct, err := itb.Encrypt(noise, data, start, buf[:n])
            if err != nil { panic(err) }
            lenBuf[0] = byte(len(ct) >> 24)
            lenBuf[1] = byte(len(ct) >> 16)
            lenBuf[2] = byte(len(ct) >> 8)
            lenBuf[3] = byte(len(ct))
            wrapWriter.Write(lenBuf[:])
            wrapWriter.Write(ct)
            if rerr == io.ErrUnexpectedEOF { break }
        }
        bw.Flush(); fin.Close(); fout.Close()
    }
    {
        fin, _ := os.Open(encPlainPath)
        fout, _ := os.Create(dstPlainPath)
        br, bw := bufio.NewReader(fin), bufio.NewWriter(fout)
        unwrapReader, _ := wrapper.NewUnwrapReader(wrapper.CipherAES128CTR, outerKey, br)
        var lenBuf [4]byte
        for {
            _, rerr := io.ReadFull(unwrapReader, lenBuf[:])
            if rerr == io.EOF { break }
            if rerr != nil { panic(rerr) }
            chunkLen := int(lenBuf[0])<<24 | int(lenBuf[1])<<16 | int(lenBuf[2])<<8 | int(lenBuf[3])
            ct := make([]byte, chunkLen)
            io.ReadFull(unwrapReader, ct)
            pt, err := itb.Decrypt(noise, data, start, ct)
            if err != nil { panic(err) }
            bw.Write(pt)
        }
        bw.Flush(); fin.Close(); fout.Close()
    }
}

Single Message Examples

Three configurations covering the most common usage patterns. Every key and every seed component is CSPRNG-generated; no master key, no key-derivation step. Cross-process persistence (encrypt today, decrypt tomorrow / on a different host) is documented in hashes/README.md and macs/README.md.

Easy: Areion-SoEM-512 (No MAC)

The high-level easy.Encryptor replaces the seven-line setup ceremony of the lower-level path with one constructor call. The encryptor allocates its own three (Single) or seven (Triple) seeds + MAC closure, snapshots the global configuration into a per-instance *itb.Config, and exposes setters that mutate only its own state without touching the process-wide itb.Set* accessors. Two encryptors with different settings can run concurrently without cross-contamination.

// Sender

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/easy"
    "github.com/everanium/itb/wrapper"
)

func main() {
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)

    // Single-Ouroboros (3 seeds) constructor — variadic args by type:
    // string matching hashes.Registry → primitive, string matching
    // macs.Registry → MAC, int → key_bits. Defaults: "areion512" /
    // 1024 / "hmac-blake3". Triple Ouroboros (7 seeds) → easy.New3(...).
    enc := easy.New("areion512", 2048, "hmac-blake3")
    defer enc.Close()

    // Per-instance configuration — mutates only this encryptor's
    // *itb.Config snapshot. Two encryptors built side-by-side carry
    // independent settings; process-wide itb.Set* accessors are NOT
    // consulted after construction.
    enc.SetNonceBits(512)   // 512-bit nonce (default: 128-bit)
    enc.SetBarrierFill(4)   // CSPRNG fill margin (default: 1, valid: 1, 2, 4, 8, 16, 32)
    enc.SetBitSoup(1)       // optional bit-level split ("bit-soup"; default: 0 = byte-level)
                            // auto-enabled for Single Ouroboros if SetLockSoup(1) is on
    enc.SetLockSoup(1)      // optional Insane Interlocked Mode: per-chunk PRF-keyed
                            // bit-permutation overlay on top of bit-soup;
                            // auto-enabled for Single Ouroboros if SetBitSoup(1) is on

    //enc.SetLockSeed(1)    // optional dedicated lockSeed for the bit-permutation
                            // derivation channel — separates that PRF's keying material
                            // from the noiseSeed-driven noise-injection channel; auto-
                            // couples SetLockSoup(1) + SetBitSoup(1). Adds one extra
                            // seed slot (3 → 4 for Single, 7 → 8 for Triple). Must be
                            // called BEFORE the first Encrypt — switching mid-session
                            // panics with easy.ErrLockSeedAfterEncrypt.

    // For cross-process persistence: enc.Export() returns a single
    // JSON blob carrying PRF keys, seed components, MAC key, and
    // (when active) the dedicated lockSeed material. Ship it
    // alongside the ciphertext or out-of-band.
    blob := enc.Export()
    fmt.Printf("state blob: %d bytes\n", len(blob))
    fmt.Printf("primitive: %s, key_bits: %d, mode: %d, mac: %s\n",
        enc.Primitive, enc.KeyBits, enc.Mode, enc.MACName)

    plaintext := []byte("any text or binary data - including 0x00 bytes")
    //chunkSize := 4 * 1024 * 1024 // 4 MB - bulk local crypto, not small-frame network streaming

    // One-shot encrypt into RGBWYOPA container.
    encrypted, err := enc.Encrypt(plaintext)
    if err != nil {
        panic(err)
    }
    //var ciphertext []byte
    //err := enc.EncryptStream(plaintext, func(chunk []byte) error {
    //    ciphertext = append(ciphertext, chunk...)
    //    return nil
    //})
    fmt.Printf("encrypted: %d bytes\n", len(encrypted))

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)
    // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
    // ~0% overhead (Recommended in every case).
    nonce, _ := wrapper.WrapInPlace(wrapper.CipherAES128CTR, outerKey, encrypted)
    wire := append(nonce, encrypted...)
    fmt.Printf("wire: %d bytes\n", len(wire))

    // Send wire payload + state blob + outerKey (out-of-band)
}

// Receiver

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/easy"
    "github.com/everanium/itb/wrapper"
)

func main() {
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)

    // Receive wire payload + state blob + outerKey (out-of-band)
    // var wire, blob, outerKey []byte = ..., ..., ...

    // Optional: peek at the blob's metadata before constructing a
    // matching encryptor. Useful when the receiver multiplexes blobs
    // of different shapes (different primitive / mode / MAC choices).
    prim, keyBits, mode, mac := easy.PeekConfig(blob)
    fmt.Printf("peek: primitive=%s, key_bits=%d, mode=%d, mac=%s\n",
        prim, keyBits, mode, mac)

    var dec *easy.Encryptor
    if mode == 1 {
        dec = easy.New(prim, keyBits, mac)
    } else {
        dec = easy.New3(prim, keyBits, mac)
    }
    defer dec.Close()

    // dec.Import(blob) below automatically restores the full
    // per-instance configuration (NonceBits, BarrierFill, BitSoup,
    // LockSoup, and the dedicated lockSeed material when sender's
    // SetLockSeed(1) was active). The Set* lines below are kept for
    // documentation — they show the knobs available for explicit
    // pre-Import override. BarrierFill is asymmetric: a receiver-set
    // value > 1 takes priority over the blob's barrier_fill (the
    // receiver's heavier CSPRNG margin is preserved across Import).
    dec.SetNonceBits(512)
    dec.SetBarrierFill(4)
    dec.SetBitSoup(1)
    dec.SetLockSoup(1)
    //dec.SetLockSeed(1)    // optional — Import below restores the dedicated
                            // lockSeed slot from the blob's lock_seed:true.

    // Restore PRF keys, seed components, MAC key, and the per-instance
    // configuration overrides (nonce_bits / barrier_fill / bit_soup /
    // lock_soup / lock_seed) from the saved blob.
    if err := dec.Import(blob); err != nil {
        panic(err)
    }

    // Strip the outer cipher envelope, recovering the ITB blob.
    encrypted, err := wrapper.UnwrapInPlace(wrapper.CipherAES128CTR, outerKey, wire)
    if err != nil {
        panic(err)
    }

    // One-shot decrypt from RGBWYOPA container.
    decrypted, err := dec.Decrypt(encrypted)
    if err != nil {
        panic(err)
    }
    //var decrypted []byte
    //err = dec.DecryptStream(ciphertext, func(chunk []byte) error {
    //    decrypted = append(decrypted, chunk...)
    //    return nil
    //})
    fmt.Printf("decrypted: %s\n", string(decrypted))
}

Easy: Areion-SoEM-512 + HMAC-BLAKE3 (MAC Authenticated)

The MAC primitive is bound at construction time — the third positional argument selects one of the registry names (kmac256, hmac-sha256, hmac-blake3). The encryptor allocates a fresh 32-byte CSPRNG MAC key alongside the per-seed PRF keys; Export() carries all of them in a single JSON blob.

// Sender

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/easy"
    "github.com/everanium/itb/wrapper"
)

func main() {
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)

    enc := easy.New("areion512", 2048, "hmac-blake3")
    defer enc.Close()

    enc.SetNonceBits(512)
    enc.SetBarrierFill(4)
    enc.SetBitSoup(1)
    enc.SetLockSoup(1)

    //enc.SetLockSeed(1)    // optional dedicated lockSeed for the bit-permutation
                            // derivation channel — auto-couples SetLockSoup(1) +
                            // SetBitSoup(1). Adds one extra seed slot. Must be
                            // called BEFORE the first EncryptAuth.

    // Persistence blob — carries seeds + PRF keys + MAC key (and
    // the dedicated lockSeed material when SetLockSeed(1) is active).
    blob := enc.Export()
    fmt.Printf("state blob: %d bytes\n", len(blob))

    plaintext := []byte("any text or binary data - including 0x00 bytes")

    // Authenticated encrypt — 32-byte tag is computed across the
    // entire decrypted capacity and embedded inside the RGBWYOPA
    // container, preserving oracle-free deniability.
    encrypted, err := enc.EncryptAuth(plaintext)
    if err != nil {
        panic(err)
    }
    fmt.Printf("encrypted: %d bytes\n", len(encrypted))

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)
    // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
    // ~0% overhead (Recommended in every case).
    nonce, _ := wrapper.WrapInPlace(wrapper.CipherAES128CTR, outerKey, encrypted)
    wire := append(nonce, encrypted...)
    fmt.Printf("wire: %d bytes\n", len(wire))

    // Send wire payload + state blob + outerKey (out-of-band)
}

// Receiver

package main

import (
    "errors"
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/easy"
    "github.com/everanium/itb/wrapper"
)

func main() {
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)

    // Receive wire payload + state blob + outerKey (out-of-band)
    // var wire, blob, outerKey []byte = ..., ..., ...

    prim, keyBits, mode, mac := easy.PeekConfig(blob)

    var dec *easy.Encryptor
    if mode == 1 {
        dec = easy.New(prim, keyBits, mac)
    } else {
        dec = easy.New3(prim, keyBits, mac)
    }
    defer dec.Close()

    // dec.Import(blob) below automatically restores the full
    // per-instance configuration (NonceBits, BarrierFill, BitSoup,
    // LockSoup, and the dedicated lockSeed material when sender's
    // SetLockSeed(1) was active). The Set* lines below are kept for
    // documentation — they show the knobs available for explicit
    // pre-Import override. BarrierFill is asymmetric: a receiver-set
    // value > 1 takes priority over the blob's barrier_fill (the
    // receiver's heavier CSPRNG margin is preserved across Import).
    dec.SetNonceBits(512)
    dec.SetBarrierFill(4)
    dec.SetBitSoup(1)
    dec.SetLockSoup(1)
    //dec.SetLockSeed(1)    // optional — Import below restores the dedicated
                            // lockSeed slot from the blob's lock_seed:true.

    if err := dec.Import(blob); err != nil {
        panic(err)
    }

    // Strip the outer cipher envelope, recovering the ITB blob.
    encrypted, err := wrapper.UnwrapInPlace(wrapper.CipherAES128CTR, outerKey, wire)
    if err != nil {
        panic(err)
    }

    // Authenticated decrypt — any single-bit tamper triggers MAC
    // failure (no oracle leak about which byte was tampered).
    decrypted, err := dec.DecryptAuth(encrypted)
    if err != nil {
        if errors.Is(err, easy.ErrClosed) {
            panic("encryptor was closed")
        }
        // The underlying itb.DecryptAuthenticated* returns a fixed-text
        // error on MAC verification failure; check the error string or
        // use the structural difference between MAC failure and other
        // decrypt errors.
        panic(err)
    }
    fmt.Printf("decrypted: %s\n", string(decrypted))
}

Easy: BLAKE2b-512 + HMAC-BLAKE3 (MAC Authenticated, 2048-bit Seeds)

Same flow as the previous example, swapping the primitive name ("blake2b512") and the MAC name ("hmac-blake3") at construction time. Mixing primitives at the encryptor level is one constructor argument away — no per-call PRF / batched-arm wiring.

// Sender

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/easy"
    "github.com/everanium/itb/wrapper"
)

func main() {
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)

    enc := easy.New("blake2b512", 2048, "hmac-blake3")
    defer enc.Close()

    enc.SetNonceBits(512)
    enc.SetBarrierFill(4)
    enc.SetBitSoup(1)
    enc.SetLockSoup(1)

    //enc.SetLockSeed(1)    // optional dedicated lockSeed; auto-couples LockSoup +
                            // BitSoup. Adds one extra seed slot. Must be called
                            // BEFORE the first EncryptAuth.

    blob := enc.Export()
    fmt.Printf("state blob: %d bytes\n", len(blob))

    plaintext := []byte("any text or binary data - including 0x00 bytes")
    encrypted, err := enc.EncryptAuth(plaintext)
    if err != nil {
        panic(err)
    }
    fmt.Printf("encrypted: %d bytes\n", len(encrypted))

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)
    // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
    // ~0% overhead (Recommended in every case).
    nonce, _ := wrapper.WrapInPlace(wrapper.CipherAES128CTR, outerKey, encrypted)
    wire := append(nonce, encrypted...)
    fmt.Printf("wire: %d bytes\n", len(wire))

    // Send wire payload + state blob + outerKey (out-of-band)
}

// Receiver

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/easy"
    "github.com/everanium/itb/wrapper"
)

func main() {
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)

    // Receive wire payload + state blob + outerKey (out-of-band)
    // var wire, blob, outerKey []byte = ..., ..., ...

    prim, keyBits, mode, mac := easy.PeekConfig(blob)

    var dec *easy.Encryptor
    if mode == 1 {
        dec = easy.New(prim, keyBits, mac)
    } else {
        dec = easy.New3(prim, keyBits, mac)
    }
    defer dec.Close()

    // dec.Import(blob) below automatically restores the full
    // per-instance configuration (NonceBits, BarrierFill, BitSoup,
    // LockSoup, and the dedicated lockSeed material when sender's
    // SetLockSeed(1) was active). The Set* lines below are kept for
    // documentation — they show the knobs available for explicit
    // pre-Import override. BarrierFill is asymmetric: a receiver-set
    // value > 1 takes priority over the blob's barrier_fill (the
    // receiver's heavier CSPRNG margin is preserved across Import).
    dec.SetNonceBits(512)
    dec.SetBarrierFill(4)
    dec.SetBitSoup(1)
    dec.SetLockSoup(1)
    //dec.SetLockSeed(1)    // optional — Import below restores the dedicated
                            // lockSeed slot from the blob's lock_seed:true.

    if err := dec.Import(blob); err != nil {
        panic(err)
    }

    // Strip the outer cipher envelope, recovering the ITB blob.
    encrypted, err := wrapper.UnwrapInPlace(wrapper.CipherAES128CTR, outerKey, wire)
    if err != nil {
        panic(err)
    }

    decrypted, err := dec.DecryptAuth(encrypted)
    if err != nil {
        panic(err)
    }
    fmt.Printf("decrypted: %s\n", string(decrypted))
}

Easy: Mixed primitives — different PRF per seed slot

easy.NewMixed and easy.NewMixed3 accept a per-slot primitive spec, allowing the noise / data / start (and optional dedicated lockSeed) seed slots to use different PRF primitives within the same native hash width. The mix-and-match-PRF freedom of the lower-level path, surfaced through Easy Mode without forcing the caller off the high-level constructor. The state blob carries per-slot primitives + per-slot PRF keys; the receiver constructs a matching encryptor with the same spec and calls Import to restore.

// Sender

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/easy"
    "github.com/everanium/itb/wrapper"
)

func main() {
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)

    // Per-slot primitive selection (Single Ouroboros, 3 + 1 slots).
    // Every name must share the same native hash width — mixing
    // widths is rejected at construction with easy.ErrEasyMixedWidth.
    // Triple Ouroboros mirror — easy.NewMixed3(easy.MixedSpec3{...})
    // takes seven per-slot names (noise + 3 data + 3 start) plus
    // the optional PrimitiveL lockSeed.
    enc := easy.NewMixed(easy.MixedSpec{
        PrimitiveN: "blake3",      // noiseSeed:  BLAKE3
        PrimitiveD: "blake2s",     // dataSeed:   BLAKE2s
        PrimitiveS: "areion256",   // startSeed:  Areion-SoEM-256
        PrimitiveL: "blake2b256",  // dedicated lockSeed (optional;
                                   //   empty = no lockSeed slot)
        KeyBits:    1024,
        MACName:    "hmac-blake3",
    })
    defer enc.Close()

    // Per-instance configuration applies as for easy.New.
    enc.SetNonceBits(512)
    enc.SetBarrierFill(4)
    // BitSoup + LockSoup are auto-coupled on the on-direction by
    // PrimitiveL above; explicit calls below are unnecessary but
    // harmless if added.
    //enc.SetBitSoup(1)
    //enc.SetLockSoup(1)

    // Per-slot introspection — Primitive returns the "mixed"
    // literal, PrimitiveAt(slot) returns each slot's name,
    // IsMixed() is the typed predicate. Slot ordering is canonical:
    // 0 = noiseSeed, 1 = dataSeed, 2 = startSeed, 3 = lockSeed
    // (Single); Triple grows the middle range to 7 slots + lockSeed.
    fmt.Printf("mixed=%v primitive=%s\n", enc.IsMixed(), enc.Primitive)
    for i := 0; i < 4; i++ {
        fmt.Printf("  slot %d: %s\n", i, enc.PrimitiveAt(i))
    }

    blob := enc.Export()
    fmt.Printf("state blob: %d bytes\n", len(blob))

    plaintext := []byte("mixed-primitive Easy Mode payload")

    // Authenticated encrypt — 32-byte tag is computed across the
    // entire decrypted capacity and embedded inside the RGBWYOPA
    // container, preserving oracle-free deniability.
    encrypted, err := enc.EncryptAuth(plaintext)
    if err != nil {
        panic(err)
    }
    fmt.Printf("encrypted: %d bytes\n", len(encrypted))

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)
    // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
    // ~0% overhead (Recommended in every case).
    nonce, _ := wrapper.WrapInPlace(wrapper.CipherAES128CTR, outerKey, encrypted)
    wire := append(nonce, encrypted...)
    fmt.Printf("wire: %d bytes\n", len(wire))

    // Send wire payload + state blob + outerKey (out-of-band)
}

// Receiver

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/easy"
    "github.com/everanium/itb/wrapper"
)

func main() {
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)

    // Receive wire payload + state blob + outerKey (out-of-band)
    // var wire, blob, outerKey []byte = ..., ..., ...

    // Receiver constructs a matching mixed encryptor — every per-
    // slot primitive name plus key_bits and mac must agree with the
    // sender. Import validates each per-slot primitive against the
    // receiver's bound spec; mismatches surface as
    // easy.ErrMismatch{Field: "primitive"}.
    dec := easy.NewMixed(easy.MixedSpec{
        PrimitiveN: "blake3",
        PrimitiveD: "blake2s",
        PrimitiveS: "areion256",
        PrimitiveL: "blake2b256",
        KeyBits:    1024,
        MACName:    "hmac-blake3",
    })
    defer dec.Close()

    // Restore PRF keys, seed components, MAC key, and the per-
    // instance configuration overrides from the saved blob. Mixed
    // blobs carry mixed:true plus a primitives array; Import on a
    // single-primitive receiver (or vice versa) is rejected as a
    // primitive mismatch.
    if err := dec.Import(blob); err != nil {
        panic(err)
    }

    // Strip the outer cipher envelope, recovering the ITB blob.
    encrypted, err := wrapper.UnwrapInPlace(wrapper.CipherAES128CTR, outerKey, wire)
    if err != nil {
        panic(err)
    }

    decrypted, err := dec.DecryptAuth(encrypted)
    if err != nil {
        panic(err)
    }
    fmt.Printf("decrypted: %s\n", string(decrypted))
}

Areion-SoEM-512 (Low-Level, No MAC)

// Sender

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/wrapper"
)

func main() {
    // Optional: global configuration (all thread-safe, atomic)
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)
    itb.SetNonceBits(512)   // 512-bit nonce (default: 128-bit)
    itb.SetBarrierFill(4)   // CSPRNG fill margin (default: 1, valid: 1,2,4,8,16,32)

    itb.SetBitSoup(1)       // optional bit-level split ("bit-soup"; default: 0 = byte-level)
                            // automatically enabled for Single Ouroboros if
                            // itb.SetLockSoup(1) is enabled or vice versa

    itb.SetLockSoup(1)      // optional Insane Interlocked Mode: per-chunk PRF-keyed
                            // bit-permutation overlay on top of bit-soup;
                            // automatically enabled for Single Ouroboros if
                            // itb.SetBitSoup(1) is enabled or vice versa

    // Four independent CSPRNG-keyed Areion-SoEM-512 paired closures
    // (noise / data / start / lock). The third return value
    // (keyN/keyD/keyS/keyL) is the [64]byte fixed key — capture it
    // per seed for cross-process persistence. The batched arm
    // (batchN/batchD/batchS/batchL) wires the AVX-512 + VAES + ILP +
    // ZMM-batched chain-absorb dispatch through Seed.BatchHash.
    fnN, batchN, keyN := itb.MakeAreionSoEM512Hash() // random noise hash key generated
    fnD, batchD, keyD := itb.MakeAreionSoEM512Hash() // random data hash key generated
    fnS, batchS, keyS := itb.MakeAreionSoEM512Hash() // random start hash key generated
    fnL, batchL, keyL := itb.MakeAreionSoEM512Hash() // random lock hash key generated
    //fnN, batchN := itb.MakeAreionSoEM512HashWithKey(keyN) // [64]byte saved noise hash key
    //fnD, batchD := itb.MakeAreionSoEM512HashWithKey(keyD) // [64]byte saved data hash key
    //fnS, batchS := itb.MakeAreionSoEM512HashWithKey(keyS) // [64]byte saved start hash key
    //fnL, batchL := itb.MakeAreionSoEM512HashWithKey(keyL) // [64]byte saved lock hash key

    // Four independent CSPRNG-generated 2048-bit seeds.
    ns, _ := itb.NewSeed512(2048, fnN) // random noise CSPRNG seeds generated
    ds, _ := itb.NewSeed512(2048, fnD) // random data CSPRNG seeds generated
    ss, _ := itb.NewSeed512(2048, fnS) // random start CSPRNG seeds generated
    ls, _ := itb.NewSeed512(2048, fnL) // random lock CSPRNG seeds generated

    ns.BatchHash = batchN // must enable batch
    ds.BatchHash = batchD // must enable batch
    ss.BatchHash = batchS // must enable batch
    ls.BatchHash = batchL // must enable batch

    // Optional: dedicated lockSeed for the bit-permutation derivation
    // channel. Separates that PRF's keying material from the noiseSeed-
    // driven noise-injection channel without changing the public Encrypt
    // / Decrypt signatures. The bit-permutation overlay must be engaged
    // (itb.SetBitSoup(1) or itb.SetLockSoup(1) — both already on above)
    // before the first Encrypt; the build-PRF guard panics on encrypt-
    // time with itb.ErrLockSeedOverlayOff when an attach is present
    // without either flag.
    ns.AttachLockSeed(ls)

    plaintext := []byte("any text or binary data - including 0x00 bytes")
    //chunkSize := 4 * 1024 * 1024 // 4 MB - bulk local crypto, not small-frame network streaming

    // Encrypt into RGBWYOPA container
    encrypted, err := itb.Encrypt512(ns, ds, ss, plaintext)
    if err != nil {
        panic(err)
    }
    //var ciphertext []byte
    //err := itb.EncryptStream512(ns, ds, ss, plaintext, chunkSize, func(chunk []byte) error {
    //    ciphertext = append(ciphertext, chunk...)
    //    return nil
    //})
    fmt.Printf("encrypted: %d bytes\n", len(encrypted))

    // Cross-process persistence — Blob512 packs every PRF fixed key
    // ([64]byte each) plus every seed's Components ([]uint64) plus the
    // captured itb.Set* globals (NonceBits / BarrierFill / BitSoup /
    // LockSoup) into one self-describing JSON blob. Triple-Ouroboros
    // counterparts are Export3 / Import3 below; the lockSeed slot
    // rides in Blob512Opts.
    bSrc := &itb.Blob512{}
    blob, err := bSrc.Export(keyN, keyD, keyS, ns, ds, ss,
        itb.Blob512Opts{KeyL: keyL, LS: ls},
    )
    if err != nil {
        panic(err)
    }
    fmt.Printf("blob: %d bytes\n", len(blob))

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)
    // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
    // ~0% overhead (Recommended in every case).
    nonce, _ := wrapper.WrapInPlace(wrapper.CipherAES128CTR, outerKey, encrypted)
    wire := append(nonce, encrypted...)
    fmt.Printf("wire: %d bytes\n", len(wire))

    // Send wire payload + blob + outerKey (out-of-band)
}

// Receiver

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/wrapper"
)

func main() {
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)

    // Receive wire payload + blob + outerKey (out-of-band)
    // var wire, blob, outerKey []byte = ..., ..., ...

    // Restore everything from the blob — Blob512.Import applies the
    // sender's NonceBits / BarrierFill / BitSoup / LockSoup globals
    // unconditionally, then populates Mode + KeyN / KeyD / KeyS /
    // KeyL plus NS / DS / SS / LS with .Components filled in. Hash
    // and BatchHash on the seeds stay nil — caller wires them from
    // the saved key bytes through the matching factory.
    bDst := &itb.Blob512{}
    if err := bDst.Import(blob); err != nil {
        panic(err)
    }

    fnN, batchN := itb.MakeAreionSoEM512HashWithKey(bDst.KeyN)
    fnD, batchD := itb.MakeAreionSoEM512HashWithKey(bDst.KeyD)
    fnS, batchS := itb.MakeAreionSoEM512HashWithKey(bDst.KeyS)
    fnL, batchL := itb.MakeAreionSoEM512HashWithKey(bDst.KeyL)

    bDst.NS.Hash, bDst.NS.BatchHash = fnN, batchN
    bDst.DS.Hash, bDst.DS.BatchHash = fnD, batchD
    bDst.SS.Hash, bDst.SS.BatchHash = fnS, batchS
    bDst.LS.Hash, bDst.LS.BatchHash = fnL, batchL

    // Mirror the sender's AttachLockSeed wire-up — the bit-permutation
    // derivation channel must consult the same dedicated lockSeed
    // material on both sides.
    bDst.NS.AttachLockSeed(bDst.LS)

    // Strip the outer cipher envelope, recovering the ITB blob.
    encrypted, err := wrapper.UnwrapInPlace(wrapper.CipherAES128CTR, outerKey, wire)
    if err != nil {
        panic(err)
    }

    // Decrypt from RGBWYOPA container
    decrypted, err := itb.Decrypt512(bDst.NS, bDst.DS, bDst.SS, encrypted)
    if err != nil {
        panic(err)
    }
    //var decrypted []byte
    //err = itb.DecryptStream512(bDst.NS, bDst.DS, bDst.SS, ciphertext, func(chunk []byte) error {
    //    decrypted = append(decrypted, chunk...)
    //    return nil
    //})
    fmt.Printf("decrypted: %s\n", string(decrypted))
}

Areion-SoEM-512 + HMAC-BLAKE3 (Low-Level, MAC Authenticated)

// Sender

package main

import (
    "crypto/rand"
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/macs"
    "github.com/everanium/itb/wrapper"
)

func main() {
    // Optional: global configuration (all thread-safe, atomic)
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)
    itb.SetNonceBits(512)   // 512-bit nonce (default: 128-bit)
    itb.SetBarrierFill(4)   // CSPRNG fill margin (default: 1, valid: 1,2,4,8,16,32)

    itb.SetBitSoup(1)       // optional bit-level split ("bit-soup"; default: 0 = byte-level)
                            // automatically enabled for Single Ouroboros if
                            // itb.SetLockSoup(1) is enabled or vice versa

    itb.SetLockSoup(1)      // optional Insane Interlocked Mode: per-chunk PRF-keyed
                            // bit-permutation overlay on top of bit-soup;
                            // automatically enabled for Single Ouroboros if
                            // itb.SetBitSoup(1) is enabled or vice versa

    // Four independent CSPRNG-keyed Areion-SoEM-512 paired closures
    // (noise / data / start / lock). The third return value
    // (keyN/keyD/keyS/keyL) is the [64]byte fixed key — capture it
    // per seed for cross-process persistence.
    fnN, batchN, keyN := itb.MakeAreionSoEM512Hash() // random noise hash key generated
    fnD, batchD, keyD := itb.MakeAreionSoEM512Hash() // random data hash key generated
    fnS, batchS, keyS := itb.MakeAreionSoEM512Hash() // random start hash key generated
    fnL, batchL, keyL := itb.MakeAreionSoEM512Hash() // random lock hash key generated
    //fnN, batchN := itb.MakeAreionSoEM512HashWithKey(keyN) // [64]byte saved noise hash key
    //fnD, batchD := itb.MakeAreionSoEM512HashWithKey(keyD) // [64]byte saved data hash key
    //fnS, batchS := itb.MakeAreionSoEM512HashWithKey(keyS) // [64]byte saved start hash key
    //fnL, batchL := itb.MakeAreionSoEM512HashWithKey(keyL) // [64]byte saved lock hash key

    ns, _ := itb.NewSeed512(2048, fnN) // random noise CSPRNG seeds generated
    ds, _ := itb.NewSeed512(2048, fnD) // random data CSPRNG seeds generated
    ss, _ := itb.NewSeed512(2048, fnS) // random start CSPRNG seeds generated
    ls, _ := itb.NewSeed512(2048, fnL) // random lock CSPRNG seeds generated

    ns.BatchHash = batchN // must enable batch
    ds.BatchHash = batchD // must enable batch
    ss.BatchHash = batchS // must enable batch
    ls.BatchHash = batchL // must enable batch

    // Optional: dedicated lockSeed for the bit-permutation derivation
    // channel — same pattern as the No Mac quick-start above.
    ns.AttachLockSeed(ls)

    // HMAC-BLAKE3 — 32-byte CSPRNG key, 32-byte tag.
    var macKey [32]byte
    rand.Read(macKey[:])
    mac, _ := macs.HMACBLAKE3(macKey[:])

    plaintext := []byte("any text or binary data - including 0x00 bytes")

    // Authenticated encrypt — 32-byte tag is computed across the entire
    // decrypted capacity and embedded inside the RGBWYOPA container,
    // preserving oracle-free deniability.
    encrypted, err := itb.EncryptAuthenticated512(ns, ds, ss, plaintext, mac)
    if err != nil {
        panic(err)
    }
    fmt.Printf("encrypted: %d bytes\n", len(encrypted))

    // Cross-process persistence — Blob512 packs every PRF fixed key,
    // every seed's Components, the dedicated lockSeed material, the
    // captured itb.Set* globals, and the MAC key + name into one
    // self-describing JSON blob.
    bSrc := &itb.Blob512{}
    blob, err := bSrc.Export(keyN, keyD, keyS, ns, ds, ss,
        itb.Blob512Opts{
            KeyL: keyL, LS: ls,
            MACKey: macKey[:], MACName: "hmac-blake3",
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Printf("blob: %d bytes\n", len(blob))

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)
    // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
    // ~0% overhead (Recommended in every case).
    nonce, _ := wrapper.WrapInPlace(wrapper.CipherAES128CTR, outerKey, encrypted)
    wire := append(nonce, encrypted...)
    fmt.Printf("wire: %d bytes\n", len(wire))

    // Send wire payload + blob + outerKey (out-of-band)
}

// Receiver

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/macs"
    "github.com/everanium/itb/wrapper"
)

func main() {
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)

    // Receive wire payload + blob + outerKey (out-of-band)
    // var wire, blob, outerKey []byte = ..., ..., ...

    // Restore everything from the blob — Import applies the sender's
    // globals + populates seeds + Key* fields + MACKey / MACName.
    bDst := &itb.Blob512{}
    if err := bDst.Import(blob); err != nil {
        panic(err)
    }

    fnN, batchN := itb.MakeAreionSoEM512HashWithKey(bDst.KeyN)
    fnD, batchD := itb.MakeAreionSoEM512HashWithKey(bDst.KeyD)
    fnS, batchS := itb.MakeAreionSoEM512HashWithKey(bDst.KeyS)
    fnL, batchL := itb.MakeAreionSoEM512HashWithKey(bDst.KeyL)

    bDst.NS.Hash, bDst.NS.BatchHash = fnN, batchN
    bDst.DS.Hash, bDst.DS.BatchHash = fnD, batchD
    bDst.SS.Hash, bDst.SS.BatchHash = fnS, batchS
    bDst.LS.Hash, bDst.LS.BatchHash = fnL, batchL
    bDst.NS.AttachLockSeed(bDst.LS)

    // Rebuild the MAC closure from the saved name + key. macs.Make
    // routes through the registry, so any of the shipped MAC primitives
    // (kmac256 / hmac-sha256 / hmac-blake3) restores via the same call.
    mac, _ := macs.Make(bDst.MACName, bDst.MACKey)

    // Strip the outer cipher envelope, recovering the ITB blob.
    encrypted, err := wrapper.UnwrapInPlace(wrapper.CipherAES128CTR, outerKey, wire)
    if err != nil {
        panic(err)
    }

    // Authenticated decrypt — any single-bit tamper triggers MAC failure
    // (no oracle leak about which byte was tampered).
    decrypted, err := itb.DecryptAuthenticated512(bDst.NS, bDst.DS, bDst.SS, encrypted, mac)
    if err != nil {
        panic(err)
    }
    fmt.Printf("decrypted: %s\n", string(decrypted))
}

Other shipped MACs: macs.HMACSHA256(key), macs.KMAC256(key) — all three produce 32-byte tags. See macs/README.md for the full MAC matrix.

BLAKE2b-512 + HMAC-BLAKE3 (Low-Level, MAC Authenticated, 2048-bit Seeds)

// Sender

package main

import (
    "crypto/rand"
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/hashes"
    "github.com/everanium/itb/macs"
    "github.com/everanium/itb/wrapper"
)

func main() {
    // Optional: global configuration (all thread-safe, atomic)
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)
    itb.SetNonceBits(512)   // 512-bit nonce (default: 128-bit)
    itb.SetBarrierFill(4)   // CSPRNG fill margin (default: 1, valid: 1,2,4,8,16,32)

    itb.SetBitSoup(1)       // optional bit-level split ("bit-soup"; default: 0 = byte-level)
                            // automatically enabled for Single Ouroboros if
                            // itb.SetLockSoup(1) is enabled or vice versa

    itb.SetLockSoup(1)      // optional Insane Interlocked Mode: per-chunk PRF-keyed
                            // bit-permutation overlay on top of bit-soup;
                            // automatically enabled for Single Ouroboros if
                            // itb.SetBitSoup(1) is enabled or vice versa

    // Four independent CSPRNG-keyed BLAKE2b-512 paired closures
    // (noise / data / start / lock). The third return value
    // (keyN/keyD/keyS/keyL) is the [64]byte fixed key — capture it
    // per seed for cross-process persistence. The batched arm
    // (batchN/batchD/batchS/batchL) wires the AVX-512 + ZMM-batched
    // chain-absorb dispatch through Seed.BatchHash.
    fnN, batchN, keyN := hashes.BLAKE2b512Pair() // random noise hash key generated
    fnD, batchD, keyD := hashes.BLAKE2b512Pair() // random data hash key generated
    fnS, batchS, keyS := hashes.BLAKE2b512Pair() // random start hash key generated
    fnL, batchL, keyL := hashes.BLAKE2b512Pair() // random lock hash key generated
    //fnN, batchN := hashes.BLAKE2b512PairWithKey(keyN) // [64]byte saved noise hash key
    //fnD, batchD := hashes.BLAKE2b512PairWithKey(keyD) // [64]byte saved data hash key
    //fnS, batchS := hashes.BLAKE2b512PairWithKey(keyS) // [64]byte saved start hash key
    //fnL, batchL := hashes.BLAKE2b512PairWithKey(keyL) // [64]byte saved lock hash key

    // 2048-bit seeds — 32 components × 64 bits, multiple of 8 for Seed512.
    ns, _ := itb.NewSeed512(2048, fnN) // random noise CSPRNG seeds generated
    ds, _ := itb.NewSeed512(2048, fnD) // random data CSPRNG seeds generated
    ss, _ := itb.NewSeed512(2048, fnS) // random start CSPRNG seeds generated
    ls, _ := itb.NewSeed512(2048, fnL) // random lock CSPRNG seeds generated

    ns.BatchHash = batchN // must enable batch
    ds.BatchHash = batchD // must enable batch
    ss.BatchHash = batchS // must enable batch
    ls.BatchHash = batchL // must enable batch

    // Optional: dedicated lockSeed for the bit-permutation derivation
    // channel — same pattern as the No Mac quick-start above.
    ns.AttachLockSeed(ls)

    // HMAC-BLAKE3 — 32-byte CSPRNG key, 32-byte tag.
    var macKey [32]byte
    rand.Read(macKey[:])
    mac, _ := macs.HMACBLAKE3(macKey[:])

    plaintext := []byte("any text or binary data - including 0x00 bytes")

    // Authenticated encrypt — 32-byte tag is computed across the entire
    // decrypted capacity and embedded inside the RGBWYOPA container,
    // preserving oracle-free deniability.
    encrypted, err := itb.EncryptAuthenticated512(ns, ds, ss, plaintext, mac)
    if err != nil {
        panic(err)
    }
    fmt.Printf("encrypted: %d bytes\n", len(encrypted))

    // Cross-process persistence — Blob512 packs PRF fixed keys, seed
    // components, dedicated lockSeed material, captured itb.Set*
    // globals, and MAC key + name into one self-describing JSON blob.
    bSrc := &itb.Blob512{}
    blob, err := bSrc.Export(keyN, keyD, keyS, ns, ds, ss,
        itb.Blob512Opts{
            KeyL: keyL, LS: ls,
            MACKey: macKey[:], MACName: "hmac-blake3",
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Printf("blob: %d bytes\n", len(blob))

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)
    // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
    // ~0% overhead (Recommended in every case).
    nonce, _ := wrapper.WrapInPlace(wrapper.CipherAES128CTR, outerKey, encrypted)
    wire := append(nonce, encrypted...)
    fmt.Printf("wire: %d bytes\n", len(wire))

    // Send wire payload + blob + outerKey (out-of-band)
}

// Receiver

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/hashes"
    "github.com/everanium/itb/macs"
    "github.com/everanium/itb/wrapper"
)

func main() {
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)

    // Receive wire payload + blob + outerKey (out-of-band)
    // var wire, blob, outerKey []byte = ..., ..., ...

    bDst := &itb.Blob512{}
    if err := bDst.Import(blob); err != nil {
        panic(err)
    }

    fnN, batchN := hashes.BLAKE2b512PairWithKey(bDst.KeyN)
    fnD, batchD := hashes.BLAKE2b512PairWithKey(bDst.KeyD)
    fnS, batchS := hashes.BLAKE2b512PairWithKey(bDst.KeyS)
    fnL, batchL := hashes.BLAKE2b512PairWithKey(bDst.KeyL)

    bDst.NS.Hash, bDst.NS.BatchHash = fnN, batchN
    bDst.DS.Hash, bDst.DS.BatchHash = fnD, batchD
    bDst.SS.Hash, bDst.SS.BatchHash = fnS, batchS
    bDst.LS.Hash, bDst.LS.BatchHash = fnL, batchL
    bDst.NS.AttachLockSeed(bDst.LS)

    mac, _ := macs.Make(bDst.MACName, bDst.MACKey)

    // Strip the outer cipher envelope, recovering the ITB blob.
    encrypted, err := wrapper.UnwrapInPlace(wrapper.CipherAES128CTR, outerKey, wire)
    if err != nil {
        panic(err)
    }

    // Authenticated decrypt — any single-bit tamper triggers MAC failure
    // (no oracle leak about which byte was tampered).
    decrypted, err := itb.DecryptAuthenticated512(bDst.NS, bDst.DS, bDst.SS, encrypted, mac)
    if err != nil {
        panic(err)
    }
    fmt.Printf("decrypted: %s\n", string(decrypted))
}

SipHash-2-4 (lightweight, 128-bit hash, no internal fixed key)

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/hashes"
    "github.com/everanium/itb/wrapper"
)

func main() {
    // Optional: global configuration (all thread-safe, atomic)
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)
    itb.SetNonceBits(512)   // 512-bit nonce (default: 128-bit)
    itb.SetBarrierFill(4)   // CSPRNG fill margin (default: 1, valid: 1,2,4,8,16,32)

    itb.SetBitSoup(1)       // optional bit-level split ("bit-soup"; default: 0 = byte-level)
                            // automatically enabled for Single Ouroboros if
                            // itb.SetLockSoup(1) is enabled or vice versa

    itb.SetLockSoup(1)      // optional Insane Interlocked Mode: per-chunk PRF-keyed
                            // bit-permutation overlay on top of bit-soup;
                            // automatically enabled for Single Ouroboros if
                            // itb.SetBitSoup(1) is enabled or vice versa

    // SipHash-2-4 has no internal fixed key — the seed components themselves
    // are the entire keying material. Three independent factory calls paired
    // with three CSPRNG-generated seeds give three independent 1024-bit
    // effective keys. The batched arm (batchN/batchD/batchS) wires the
    // AVX-512 ZMM-batched chain-absorb dispatch through Seed.BatchHash.
    fnN, batchN := hashes.SipHash24Pair()
    fnD, batchD := hashes.SipHash24Pair()
    fnS, batchS := hashes.SipHash24Pair()

    ns, _ := itb.NewSeed128(1024, fnN); ns.BatchHash = batchN // random noise CSPRNG seeds generated, batch enabled
    ds, _ := itb.NewSeed128(1024, fnD); ds.BatchHash = batchD // random data CSPRNG seeds generated, batch enabled
    ss, _ := itb.NewSeed128(1024, fnS); ss.BatchHash = batchS // random start CSPRNG seeds generated, batch enabled

    // Optional: dedicated lockSeed for the bit-permutation derivation
    // channel — same flow as the Areion-SoEM-512 quick-starts above.
    fnL, batchL := hashes.SipHash24Pair()
    ls, _ := itb.NewSeed128(1024, fnL); ls.BatchHash = batchL
    ns.AttachLockSeed(ls)

    plaintext := []byte("any text or binary data - including 0x00 bytes")

    encrypted, _ := itb.Encrypt128(ns, ds, ss, plaintext)
    fmt.Printf("encrypted: %d bytes\n", len(encrypted))

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)
    // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
    // ~0% overhead (Recommended in every case).
    nonce, _ := wrapper.WrapInPlace(wrapper.CipherAES128CTR, outerKey, encrypted)
    wire := append(nonce, encrypted...)
    fmt.Printf("wire: %d bytes\n", len(wire))

    // Cross-process persistence — Blob128 packs every seed's Components
    // (SipHash-2-4 has no fixed PRF key; the seed components are the
    // entire keying material — KeyN/KeyD/KeyS/KeyL stay nil) plus the
    // optional dedicated lockSeed and the captured itb.Set* globals
    // into one self-describing JSON blob.
    bSrc := &itb.Blob128{}
    blob, _ := bSrc.Export(nil, nil, nil, ns, ds, ss,
        itb.Blob128Opts{LS: ls})

    // Receiver — Import reverses Export. Globals are restored
    // unconditionally; Hash / BatchHash on each seed stay nil so the
    // caller wires SipHash-2-4 closures from a fresh factory call.
    bDst := &itb.Blob128{}
    _ = bDst.Import(blob)

    fnN2, batchN2 := hashes.SipHash24Pair()
    fnD2, batchD2 := hashes.SipHash24Pair()
    fnS2, batchS2 := hashes.SipHash24Pair()
    fnL2, batchL2 := hashes.SipHash24Pair()
    bDst.NS.Hash, bDst.NS.BatchHash = fnN2, batchN2
    bDst.DS.Hash, bDst.DS.BatchHash = fnD2, batchD2
    bDst.SS.Hash, bDst.SS.BatchHash = fnS2, batchS2
    bDst.LS.Hash, bDst.LS.BatchHash = fnL2, batchL2
    bDst.NS.AttachLockSeed(bDst.LS)

    // Strip the outer cipher envelope, recovering the ITB blob.
    recovered, _ := wrapper.UnwrapInPlace(wrapper.CipherAES128CTR, outerKey, wire)
    decrypted, _ := itb.Decrypt128(bDst.NS, bDst.DS, bDst.SS, recovered)
    fmt.Printf("decrypted: %s\n", string(decrypted))
}

Triple Ouroboros (7 seeds, 3× security)

// Triple Ouroboros: 7 seeds (1 noise + 3 data + 3 start) plus an
// optional 8th dedicated lockSeed, 512-bit for speed.

itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)

// Light secure bit-permutation mode without performance trade-off (Recommended to use with Triple Ouroboros)
itb.SetBitSoup(1)       // optional mode: bit-level split ("bit soup"), opt-in SAT-resistance reserve (default: 0 = byte-level)
                        // automatically enabled for Single Ouroboros if itb.SetLockSoup(1) is enabled or vice versa
// Most secure bit-permutation mode with performance trade-off ~2×-7× slower
itb.SetLockSoup(1)      // optional Insane Interlocked Mode overlay: per-chunk PRF-keyed bit-permutation; ~2×-7× slower
                        // automatically engages itb.SetBitSoup(1)

// Eight independent CSPRNG-keyed Areion-SoEM-512 paired closures
// (1 noise + 3 data + 3 start + 1 lock).
fnN,  batchN,  keyN  := itb.MakeAreionSoEM512Hash()
fnD1, batchD1, keyD1 := itb.MakeAreionSoEM512Hash()
fnD2, batchD2, keyD2 := itb.MakeAreionSoEM512Hash()
fnD3, batchD3, keyD3 := itb.MakeAreionSoEM512Hash()
fnS1, batchS1, keyS1 := itb.MakeAreionSoEM512Hash()
fnS2, batchS2, keyS2 := itb.MakeAreionSoEM512Hash()
fnS3, batchS3, keyS3 := itb.MakeAreionSoEM512Hash()
fnL,  batchL,  keyL  := itb.MakeAreionSoEM512Hash()

ns,  _ := itb.NewSeed512(2048, fnN);  ns.BatchHash  = batchN
ds1, _ := itb.NewSeed512(2048, fnD1); ds1.BatchHash = batchD1
ds2, _ := itb.NewSeed512(2048, fnD2); ds2.BatchHash = batchD2
ds3, _ := itb.NewSeed512(2048, fnD3); ds3.BatchHash = batchD3
ss1, _ := itb.NewSeed512(2048, fnS1); ss1.BatchHash = batchS1
ss2, _ := itb.NewSeed512(2048, fnS2); ss2.BatchHash = batchS2
ss3, _ := itb.NewSeed512(2048, fnS3); ss3.BatchHash = batchS3
ls,  _ := itb.NewSeed512(2048, fnL);  ls.BatchHash  = batchL

// Optional: dedicated lockSeed for the bit-permutation derivation
// channel — same flow as the Single Ouroboros quick-starts above.
ns.AttachLockSeed(ls)

encrypted, _ := itb.Encrypt3x512(ns, ds1, ds2, ds3, ss1, ss2, ss3, plaintext)

// Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
// in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)
// Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
// ~0% overhead (Recommended in every case).
nonce, _ := wrapper.WrapInPlace(wrapper.CipherAES128CTR, outerKey, encrypted)
wire := append(nonce, encrypted...)

// Cross-process persistence — Blob512.Export3 packs the 7 seeds, the
// 7 hash keys, the dedicated lockSeed material, and the captured
// itb.Set* globals into one self-describing JSON blob. Add MACKey /
// MACName to Blob512Opts when an authenticated variant is in use.
bSrc := &itb.Blob512{}
blob, _ := bSrc.Export3(
    keyN, keyD1, keyD2, keyD3, keyS1, keyS2, keyS3,
    ns, ds1, ds2, ds3, ss1, ss2, ss3,
    itb.Blob512Opts{KeyL: keyL, LS: ls},
)

// Receiver — Import3 reverses Export3. Globals are restored
// unconditionally; Hash / BatchHash on each seed stay nil so the
// caller wires them from the saved Key* bytes.
bDst := &itb.Blob512{}
_ = bDst.Import3(blob)

fnN2,  batchN2  := itb.MakeAreionSoEM512HashWithKey(bDst.KeyN)
fnD1b, batchD1b := itb.MakeAreionSoEM512HashWithKey(bDst.KeyD1)
fnD2b, batchD2b := itb.MakeAreionSoEM512HashWithKey(bDst.KeyD2)
fnD3b, batchD3b := itb.MakeAreionSoEM512HashWithKey(bDst.KeyD3)
fnS1b, batchS1b := itb.MakeAreionSoEM512HashWithKey(bDst.KeyS1)
fnS2b, batchS2b := itb.MakeAreionSoEM512HashWithKey(bDst.KeyS2)
fnS3b, batchS3b := itb.MakeAreionSoEM512HashWithKey(bDst.KeyS3)
fnLb,  batchLb  := itb.MakeAreionSoEM512HashWithKey(bDst.KeyL)

bDst.NS.Hash,  bDst.NS.BatchHash  = fnN2,  batchN2
bDst.DS1.Hash, bDst.DS1.BatchHash = fnD1b, batchD1b
bDst.DS2.Hash, bDst.DS2.BatchHash = fnD2b, batchD2b
bDst.DS3.Hash, bDst.DS3.BatchHash = fnD3b, batchD3b
bDst.SS1.Hash, bDst.SS1.BatchHash = fnS1b, batchS1b
bDst.SS2.Hash, bDst.SS2.BatchHash = fnS2b, batchS2b
bDst.SS3.Hash, bDst.SS3.BatchHash = fnS3b, batchS3b
bDst.LS.Hash,  bDst.LS.BatchHash  = fnLb,  batchLb
bDst.NS.AttachLockSeed(bDst.LS)

// Strip the outer cipher envelope, recovering the ITB blob.
recovered, _ := wrapper.UnwrapInPlace(wrapper.CipherAES128CTR, outerKey, wire)
decrypted, _ := itb.Decrypt3x512(
    bDst.NS, bDst.DS1, bDst.DS2, bDst.DS3, bDst.SS1, bDst.SS2, bDst.SS3, recovered,
)
// Security: P × 2^(3×512) = P × 2^1536. Faster than Single 1024-bit, stronger security.

Mixing PRF Primitives

Each seed has its own hash function — different PRF implementations are allowed for different seeds within the same hash width, including the dedicated lockSeed when one is attached via AttachLockSeed. The receiver must use the same assignment. Both arms of the *Pair() factory propagate to the seed via BatchHash so the AVX-512 ZMM-batched dispatch stays active per primitive. The Lock Soup overlay's per-chunk derivation captures the attached lockSeed's Hash (and components) — primitive divergence between the noise-injection channel and the bit-permutation channel is observable end-to-end and offers algorithm-diversity defence-in-depth on top of the independent keying material.

Single Ouroboros (3 seeds + optional dedicated lockSeed):

fnN, batchN, _ := hashes.BLAKE3256Pair()   // noiseSeed: BLAKE3
fnD, batchD, _ := hashes.BLAKE2s256Pair()  // dataSeed:  BLAKE2s
fnS, batchS, _ := hashes.BLAKE3256Pair()   // startSeed: BLAKE3

ns, _ := itb.NewSeed256(1024, fnN)
ds, _ := itb.NewSeed256(1024, fnD)
ss, _ := itb.NewSeed256(1024, fnS)
ns.BatchHash, ds.BatchHash, ss.BatchHash = batchN, batchD, batchS

// Optional: dedicated lockSeed for the bit-permutation derivation
// channel — pick any 256-bit primitive; the Lock Soup overlay
// honestly routes its per-chunk PRF through ls.Hash and ls.Components,
// so the lockSeed primitive may legitimately differ from the
// noiseSeed primitive.
fnL, batchL, _ := hashes.BLAKE2s256Pair()  // lockSeed: BLAKE2s
ls, _ := itb.NewSeed256(1024, fnL); ls.BatchHash = batchL
ns.AttachLockSeed(ls)

encrypted, _ := itb.Encrypt256(ns, ds, ss, plaintext)

Triple Ouroboros (7 seeds + optional dedicated lockSeed):

fnN,  batchN,  _ := hashes.BLAKE3256Pair()   // shared noise: BLAKE3
fnD1, batchD1, _ := hashes.BLAKE2s256Pair()  // ring 1 data:  BLAKE2s
fnD2, batchD2, _ := hashes.BLAKE3256Pair()   // ring 2 data:  BLAKE3
fnD3, batchD3, _ := hashes.BLAKE2s256Pair()  // ring 3 data:  BLAKE2s
fnS1, batchS1, _ := hashes.BLAKE3256Pair()   // ring 1 start: BLAKE3
fnS2, batchS2, _ := hashes.BLAKE2s256Pair()  // ring 2 start: BLAKE2s
fnS3, batchS3, _ := hashes.BLAKE3256Pair()   // ring 3 start: BLAKE3

ns,  _ := itb.NewSeed256(512, fnN)
ds1, _ := itb.NewSeed256(512, fnD1)
ds2, _ := itb.NewSeed256(512, fnD2)
ds3, _ := itb.NewSeed256(512, fnD3)
ss1, _ := itb.NewSeed256(512, fnS1)
ss2, _ := itb.NewSeed256(512, fnS2)
ss3, _ := itb.NewSeed256(512, fnS3)
ns.BatchHash, ds1.BatchHash, ds2.BatchHash, ds3.BatchHash = batchN, batchD1, batchD2, batchD3
ss1.BatchHash, ss2.BatchHash, ss3.BatchHash = batchS1, batchS2, batchS3

// Optional: dedicated lockSeed for the bit-permutation derivation
// channel — same mixing rule as the Single Ouroboros block above.
// ls.Hash and ls.Components both flow through the Lock Soup overlay,
// so a primitive choice for ls is meaningful and not just keying-
// material isolation.
fnL, batchL, _ := hashes.BLAKE3256Pair()    // lockSeed: BLAKE3
ls, _ := itb.NewSeed256(512, fnL); ls.BatchHash = batchL
ns.AttachLockSeed(ls)

encrypted, _ := itb.Encrypt3x256(ns, ds1, ds2, ds3, ss1, ss2, ss3, plaintext)

For Triple Ouroboros, use the most performance-balanced PRF primitives across the three dataSeed rings — this ensures all three parallel goroutines finish at similar times. BLAKE3 / BLAKE2s sit close on the AVX-512 ZMM throughput envelope (see BENCH.md / BENCH3.md) and are a natural balanced pair.

How It Works

ITB encrypts data into raw RGBWYOPA pixel containers (8 channels per pixel: Red, Green, Blue, White, Yellow, Orange, Purple, Alpha — mnemonic labels for an 8-byte unit; the format is not tied to image processing) generated from crypto/rand. Each 8-bit channel carries 7 data bits and 1 noise bit, yielding 56 data bits per pixel at 1.14× overhead. Each pixel's bit-plane selection and per-channel XOR masks are derived from a chained hash of the seed and a per-message nonce. The random container creates an information-theoretic barrier: hash outputs are absorbed by modifications of random pixel values — the original container bytes are never transmitted, so the modifications are unknown, and the hash output is unobservable.

The data is embedded starting at a seed-dependent pixel offset with wrap-around — the physical layout in the container is completely non-sequential. An observer sees uniformly random pixel values with no way to determine which pixels carry data, in what order, or what bit-plane is used.

Hash Width Variants

The library provides three parallel API sets for different hash output widths. All share the same pixel format, framing, and security properties — the difference is in ChainHash intermediate state width.

API	Seeds	Hash Type	State	Effective Max Key	Target Hash Functions
Encrypt256 / Decrypt256	3	HashFunc256 (256-bit)	256-bit	1024 bits	Areion-SoEM-256, BLAKE2s, BLAKE3 keyed, BLAKE2b-256, ChaCha20
Encrypt512 / Decrypt512	3	HashFunc512 (512-bit)	512-bit	2048 bits	Areion-SoEM-512, BLAKE2b-512
Encrypt128 / Decrypt128	3	HashFunc128 (128-bit)	128-bit	1024 bits	SipHash-2-4, AES-CMAC
Encrypt3x256 / Decrypt3x256	7	HashFunc256 (256-bit)	256-bit	1024 bits	Areion-SoEM-256, BLAKE2s, BLAKE3 keyed, BLAKE2b-256, ChaCha20
Encrypt3x512 / Decrypt3x512	7	HashFunc512 (512-bit)	512-bit	2048 bits	Areion-SoEM-512, BLAKE2b-512
Encrypt3x128 / Decrypt3x128	7	HashFunc128 (128-bit)	128-bit	1024 bits	SipHash-2-4, AES-CMAC

Each variant also has authenticated versions (EncryptAuthenticated128/DecryptAuthenticated128, EncryptAuthenticated3x128/DecryptAuthenticated3x128, etc.) and streaming versions (EncryptStream128/DecryptStream128, EncryptStream3x128/DecryptStream3x128, etc.).

Optimized Hash Wrappers

Hash functions like AES and BLAKE3 have expensive key setup. Creating a new cipher/hasher on every call wastes time on initialization. The cached wrapper pattern fixes this: create the cipher once with a fixed random key, mix seed components into the data instead. Each of the three seeds must get its own wrapper instance (independent key).

The hashes/ subpackage ships ready cached factories — hashes.SipHash24(), hashes.AESCMAC(), hashes.ChaCha20(), hashes.BLAKE2s(), hashes.BLAKE2b256(), hashes.BLAKE2b512(), hashes.BLAKE3() — each returning a closure with a freshly-generated random key. For the recommended default Areion-SoEM, use the flagship factories shipped directly from the itb root package (see below). A WithKey variant is also exported for every primitive (hashes.AESCMACWithKey(key) etc.) for serialization paths where the fixed key must persist across processes.

Areion-SoEM (256/512-bit, VAES-accelerated batched dispatch — Recommended)

Areion-SoEM is a formally proven beyond-birthday-bound PRF based on AES round functions. ITB ships a built-in 4-way batched implementation (AreionSoEM256x4 / AreionSoEM512x4) that runs ~2× faster than four serial calls on x86_64 hardware with VAES + AVX-512 (Intel Rocket Lake / Tiger Lake+, AMD Zen 4+) and ~1.3× over scalar AES-NI on hosts with VAES + AVX2 but no AVX-512 (AMD Zen 3, Intel Alder Lake P/E-cores). The paired-factory helpers MakeAreionSoEM256Hash / MakeAreionSoEM512Hash return (HashFunc, BatchHashFunc, fixedKey) so each seed wires both arms with the same fixed key — ITB's processChunk{256,512} then dispatches per-pixel hashing four pixels per batched call. Pass nothing for a CSPRNG-generated fixedKey (returned for cross-process persistence — save it!) or pass a saved [32]byte / [64]byte on the restore path.

Recent ASM work in internal/areionasm/ lifts both arms substantially: the SoEM batched dispatch interleaves four VAES lanes per round for 3-4× over the prior sequential layout, and fused Single Message AVX-512 chain kernels (areion_chain{256,512}_{20,36,68}_amd64.s) collapse a full per-pixel ChainHash into one ASM call for 5-10× over the per-call Go path. The 20 / 36 / 68 byte specialisations cover SetNonceBits(128 / 256 / 512) respectively; state is held in ZMM registers across all CBC-MAC absorb rounds with zero memory round-trips.

The example below pairs Areion-SoEM-256 with the streaming API (EncryptStream256 / DecryptStream256) at a deliberately modest 1024-bit seed width — same Quick Start shape, just one tier down on key size and routed through the chunk-emitting callback variant suitable for socket / pipe / file delivery:

package main

import (
    "fmt"
    "github.com/everanium/itb"
    "github.com/everanium/itb/wrapper"
)

func main() {
    // Optional: global configuration (all thread-safe, atomic)
    itb.SetMaxWorkers(8)    // limit to 8 CPU cores (default: all CPUs)
    itb.SetNonceBits(512)   // 512-bit nonce (default: 128-bit)
    itb.SetBarrierFill(4)   // CSPRNG fill margin (default: 1, valid: 1,2,4,8,16,32)

    itb.SetBitSoup(1)       // optional bit-level split ("bit-soup"; default: 0 = byte-level)
                            // automatically enabled for Single Ouroboros if
                            // itb.SetLockSoup(1) is enabled or vice versa

    itb.SetLockSoup(1)      // optional Insane Interlocked Mode: per-chunk PRF-keyed
                            // bit-permutation overlay on top of bit-soup;
                            // automatically enabled for Single Ouroboros if
                            // itb.SetBitSoup(1) is enabled or vice versa


    // Four independent CSPRNG-keyed Areion-SoEM-256 paired closures
    // (3 main seeds + 1 optional dedicated lockSeed). The third return
    // value (keyN/keyD/keyS/keyL) is the [32]byte fixed key — capture
    // it per seed for cross-process persistence. The batched arm
    // (batchN/batchD/batchS/batchL) wires the AVX-512 + VAES + ILP +
    // ZMM-batched chain-absorb dispatch through Seed.BatchHash.
    fnN, batchN, keyN := itb.MakeAreionSoEM256Hash() // random noise hash key generated
    fnD, batchD, keyD := itb.MakeAreionSoEM256Hash() // random data hash key generated
    fnS, batchS, keyS := itb.MakeAreionSoEM256Hash() // random start hash key generated
    fnL, batchL, keyL := itb.MakeAreionSoEM256Hash() // random lock hash key generated
    //fnN, batchN := itb.MakeAreionSoEM256HashWithKey(keyN) // [32]byte saved noise hash key
    //fnD, batchD := itb.MakeAreionSoEM256HashWithKey(keyD) // [32]byte saved data hash key
    //fnS, batchS := itb.MakeAreionSoEM256HashWithKey(keyS) // [32]byte saved start hash key
    //fnL, batchL := itb.MakeAreionSoEM256HashWithKey(keyL) // [32]byte saved lock hash key

    // 1024-bit seeds — 16 components × 64 bits, multiple of 4 for Seed256.
    ns, _ := itb.NewSeed256(1024, fnN); ns.BatchHash = batchN // random noise CSPRNG seeds, batch enabled
    ds, _ := itb.NewSeed256(1024, fnD); ds.BatchHash = batchD // random data CSPRNG seeds, batch enabled
    ss, _ := itb.NewSeed256(1024, fnS); ss.BatchHash = batchS // random start CSPRNG seeds, batch enabled
    ls, _ := itb.NewSeed256(1024, fnL); ls.BatchHash = batchL // random lock CSPRNG seeds, batch enabled

    // Optional: dedicated lockSeed for the bit-permutation derivation
    // channel — same flow as the Areion-SoEM-512 quick-starts above.
    ns.AttachLockSeed(ls)

    plaintext := []byte("any text or binary data - including 0x00 bytes")
    chunkSize := 4 * 1024 * 1024 // 4 MB — bulk local crypto, not small-frame network streaming

    // EncryptStream256 — emits successive ciphertext chunks via callback.
    // Useful for file-sized payloads that shouldn't materialise in memory.
    var ciphertext []byte
    err := itb.EncryptStream256(ns, ds, ss, plaintext, chunkSize, func(chunk []byte) error {
        ciphertext = append(ciphertext, chunk...)
        return nil
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("encrypted: %d bytes\n", len(ciphertext))

    // Outer cipher key - preferred surface for HKDF / ML-KEM / key-rotation policy
    // in user-side application. ITB Inner seeds + PRF key keep as CSPRNG derived.
    outerKey, _ := wrapper.GenerateKey(wrapper.CipherAES128CTR)
    // Format-deniability ITB masking via outer-cipher wrapper (AES-128-CTR)
    // ~0% overhead (Recommended in every case).
    nonce, _ := wrapper.WrapInPlace(wrapper.CipherAES128CTR, outerKey, ciphertext)
    wire := append(nonce, ciphertext...)
    fmt.Printf("wire: %d bytes\n", len(wire))

    // Cross-process persistence — Blob256 packs every seed's hash key
    // ([32]byte for Areion-SoEM-256) and Components ([]uint64) plus
    // the optional dedicated lockSeed and the captured itb.Set* globals
    // into one self-describing JSON blob.
    bSrc := &itb.Blob256{}
    blob, _ := bSrc.Export(keyN, keyD, keyS, ns, ds, ss,
        itb.Blob256Opts{KeyL: keyL, LS: ls})

    // Receiver — Import reverses Export. Globals are restored
    // unconditionally; Hash / BatchHash on each seed stay nil so the
    // caller wires them from the saved Key* bytes.
    bDst := &itb.Blob256{}
    _ = bDst.Import(blob)

    fnN2, batchN2 := itb.MakeAreionSoEM256HashWithKey(bDst.KeyN)
    fnD2, batchD2 := itb.MakeAreionSoEM256HashWithKey(bDst.KeyD)
    fnS2, batchS2 := itb.MakeAreionSoEM256HashWithKey(bDst.KeyS)
    fnL2, batchL2 := itb.MakeAreionSoEM256HashWithKey(bDst.KeyL)
    bDst.NS.Hash, bDst.NS.BatchHash = fnN2, batchN2
    bDst.DS.Hash, bDst.DS.BatchHash = fnD2, batchD2
    bDst.SS.Hash, bDst.SS.BatchHash = fnS2, batchS2
    bDst.LS.Hash, bDst.LS.BatchHash = fnL2, batchL2
    bDst.NS.AttachLockSeed(bDst.LS)

    // Strip the outer cipher envelope, recovering the ITB blob.
    recovered, _ := wrapper.UnwrapInPlace(wrapper.CipherAES128CTR, outerKey, wire)

    // DecryptStream256 — emits successive plaintext chunks via callback.
    // Production callers drive emit from a file / mapped-region read loop.
    var decrypted []byte
    err = itb.DecryptStream256(bDst.NS, bDst.DS, bDst.SS, recovered, func(chunk []byte) error {
        decrypted = append(decrypted, chunk...)
        return nil
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("decrypted: %s\n", string(decrypted))
}

The Areion-SoEM-512 variant uses MakeAreionSoEM512Hash() paired with itb.Encrypt512 / itb.Decrypt512 and is wired identically. The batched arm of the returned pair shares the same internally-generated random fixed key as the single arm, so per-pixel hashes match bit-exact between the two dispatch paths (verified by the parity test suite). Triple Ouroboros wires the same way: each of the seven seeds receives an independent paired factory call.

Backward compatibility — no VAES required. The same code works on every platform; only the throughput tier changes:

CPU / build	Path	Throughput tier
amd64 + VAES + AVX-512 (Intel Ice Lake+, AMD Zen 4+)	SoEM batched: internal/areionasm/areion_soem{256,512}_amd64.s + fused chain: internal/areionasm/areion_chain{256,512}_{20,36,68}_amd64.s	Top tier: 4-way VAES interleaved on ZMM and fused-state chain kernel (one ASM call per pixel; no memory round-trips between absorb rounds)
amd64 + VAES + AVX2 only (AMD Zen 3, Alder Lake E-cores)	Per-half permute: internal/areionasm/areion_amd64.s (Areion256Permutex4Avx2 / Areion512Permutex4Avx2); SoEM XOR finalize on the Go side	4-way VAES on YMM (2 AES blocks per VAESENC × 2 sequential lane pairs = 4 blocks per state half), ~2× over scalar AES-NI; SoEM-state interleaving and fused chain kernel are AVX-512-only and fall back to per-call Go path
amd64 without VAES (older Intel / AMD)	Go fallback via aes.Round4HW(state, zeroKey) (internal/areionasm/areion_amd64.s base permutation)	4× sequential AES-NI per round (no SIMD width gain, still hardware-accelerated)
Pure software / CGO_ENABLED=0	Same Go fallback (process_generic.go batched dispatch wired)	Slowest tier, correct output preserved

Runtime CPU detection (areionasm.HasVAESAVX512 and areionasm.HasVAESAVX2NoAVX512) selects the right path once at package init via the upstream github.com/jedisct1/go-aes CPUID checks — no per-call branching cost. The bit-exact parity invariant BatchHash(data)[i] == Hash(data[i]) holds on every platform; ITB's parity test suite (TestAreionSoEM{256,512}x4Parity plus the direct-call parity tests for each tier and a 3-way cross-path parity test on hosts where all three implementations are runnable) verifies this on every test run.

If the underlying primitive must be wired manually (custom key management, keyless probe, etc.) call aes.AreionSoEM256 / aes.AreionSoEM512 from github.com/jedisct1/go-aes directly — same primitive, no batched dispatch, useful only when the paired-factory pattern does not fit the deployment.

Pluggable PRF primitives via hashes/

The hashes/ subpackage ships paired cached factories for every PRF-grade primitive ITB exposes through its FFI surface. Each <Primitive>Pair() factory pre-keys its primitive once at construction, returns a (single, batched, key) triple — the batched arm wires the AVX-512 ZMM-batched chain-absorb dispatch through Seed.BatchHash automatically — reuses a sync.Pool of scratch buffers, and is safe to call concurrently. Pass nothing for a CSPRNG-generated key (returned for cross-process persistence — capture and save it); pass a saved key on the restore path. The <Primitive>PairWithKey counterpart takes the fixed key as a single non-variadic argument for unambiguously explicit-key call sites. SipHash-2-4 is the one exception — its keying material is the seed components themselves, no internal fixed key, so SipHash24Pair() takes no arguments and returns a (single, batched) pair without a third key element.

Single-arm-only factories (AESCMAC(), BLAKE2b256(), BLAKE2b512(), BLAKE2s(), BLAKE3(), ChaCha20(), SipHash24()) remain available for callers that don't need the batched dispatch — they return only the single-call closure without exposing the ZMM-batched arm.

In FFI-stable index order:

#	Variadic factory	Explicit-key counterpart	Returns (variadic form)	Native width
0	Areion256Pair(key ...[32]byte)	Areion256PairWithKey(key [32]byte)	(HashFunc256, BatchHashFunc256, [32]byte)	256
1	Areion512Pair(key ...[64]byte)	Areion512PairWithKey(key [64]byte)	(HashFunc512, BatchHashFunc512, [64]byte)	512
2	SipHash24Pair()	— (seed components are the entire key)	(HashFunc128, BatchHashFunc128)	128
3	AESCMACPair(key ...[16]byte)	AESCMACPairWithKey(key [16]byte)	(HashFunc128, BatchHashFunc128, [16]byte)	128
4	BLAKE2b256Pair(key ...[32]byte)	BLAKE2b256PairWithKey(key [32]byte)	(HashFunc256, BatchHashFunc256, [32]byte)	256
5	BLAKE2b512Pair(key ...[64]byte)	BLAKE2b512PairWithKey(key [64]byte)	(HashFunc512, BatchHashFunc512, [64]byte)	512
6	BLAKE2s256Pair(key ...[32]byte)	BLAKE2s256PairWithKey(key [32]byte)	(HashFunc256, BatchHashFunc256, [32]byte)	256
7	BLAKE3256Pair(key ...[32]byte)	BLAKE3256PairWithKey(key [32]byte)	(HashFunc256, BatchHashFunc256, [32]byte)	256
8	ChaCha20256Pair(key ...[32]byte)	ChaCha20256PairWithKey(key [32]byte)	(HashFunc256, BatchHashFunc256, [32]byte)	256

Name-keyed dispatch (used by the FFI layer; works for any code that selects the primitive at runtime). The key is []byte, size validated against the primitive's native length. Make<N>Pair returns the batched arm alongside the single arm; Make<N> (no Pair suffix) is the single-arm-only convenience that drops the batched arm:

Function	Returns	Covers
Make128(name, key ...[]byte)	(HashFunc128, []byte, error)	128-bit primitives, single arm only
Make128Pair(name, key ...[]byte)	(HashFunc128, BatchHashFunc128, []byte, error)	128-bit primitives, single + batched (SipHash-2-4, AES-CMAC)
Make256(name, key ...[]byte)	(HashFunc256, []byte, error)	256-bit primitives, single arm only
Make256Pair(name, key ...[]byte)	(HashFunc256, BatchHashFunc256, []byte, error)	256-bit primitives, single + batched (Areion-SoEM-256, BLAKE2b-256, BLAKE2s, BLAKE3, ChaCha20)
Make512(name, key ...[]byte)	(HashFunc512, []byte, error)	512-bit primitives, single arm only
Make512Pair(name, key ...[]byte)	(HashFunc512, BatchHashFunc512, []byte, error)	512-bit primitives, single + batched (Areion-SoEM-512, BLAKE2b-512)
Find(name)	(Spec, bool)	Spec lookup for key-size / native-width metadata

Authenticated MACs via macs/

The macs/ subpackage ships three MAC primitives with a fixed 32-byte tag and FFI-stable index order. All three pre-key the primitive once at construction and are safe to call concurrently. The factory takes the key as []byte (no variadic random-key path — the caller generates the key via crypto/rand.Read and passes it explicitly):

#	Factory	Returns	Key size	Tag size
0	KMAC256(key []byte)	(MACFunc, error)	≥16 B	32 B
	KMAC256WithCustomization(key, customization []byte)	(MACFunc, error)	≥16 B	32 B
1	HMACSHA256(key []byte)	(MACFunc, error)	≥16 B	32 B
2	HMACBLAKE3(key []byte)	(MACFunc, error)	32 B	32 B

Name-keyed dispatch:

Function	Returns	Purpose
Make(name, key []byte)	(MACFunc, error)	Name-keyed dispatch (FFI / runtime selection)
Find(name)	(Spec, bool)	Spec lookup for key-size metadata

See macs/README.md for full authenticated-encryption examples (EncryptAuthenticated{128,256,512} / DecryptAuthenticated{128,256,512}) and the MAC-Inside-Encrypt placement-hiding rationale.

Custom factory pattern (advanced)

Write your own HashFunc when you need a primitive not covered by the hashes/ subpackage, or want a different keying / pooling strategy. The pattern below is what hashes.BLAKE3() itself ships, kept here as a reference. Three techniques worth noting:

• sync.Pool amortises per-call allocation of the scratch buffer
• blake3.NewKeyed produces a hasher template; Clone() per call sidesteps the data race that Reset() on a shared hasher would cause under ITB's parallel goroutines in process256
• the payload region is zero-padded out to seedInjectBytes (32) so all four seed uint64's contribute even when len(data) is shorter than 32 (a 20-byte ITB pixel input would otherwise drop seed[2..3] silently)

func makeBlake3Hash() itb.HashFunc256 {
    var key [32]byte
    rand.Read(key[:])
    template, _ := blake3.NewKeyed(key[:])
    pool := &sync.Pool{New: func() any { b := make([]byte, 0, 128); return &b }}

    return func(data []byte, seed [4]uint64) [4]uint64 {
        h := template.Clone()
        const seedInjectBytes = 32
        payloadLen := len(data)
        if payloadLen < seedInjectBytes { payloadLen = seedInjectBytes }
        ptr := pool.Get().(*[]byte)
        mixed := *ptr
        if cap(mixed) < payloadLen { mixed = make([]byte, payloadLen) } else { mixed = mixed[:payloadLen] }
        for i := len(data); i < payloadLen; i++ { mixed[i] = 0 }
        copy(mixed[:len(data)], data)
        for i := 0; i < 4; i++ {
            off := i * 8
            binary.LittleEndian.PutUint64(mixed[off:], binary.LittleEndian.Uint64(mixed[off:])^seed[i])
        }
        h.Write(mixed)
        *ptr = mixed; pool.Put(ptr)
        var buf [32]byte
        h.Sum(buf[:0])
        return [4]uint64{
            binary.LittleEndian.Uint64(buf[0:]),  binary.LittleEndian.Uint64(buf[8:]),
            binary.LittleEndian.Uint64(buf[16:]), binary.LittleEndian.Uint64(buf[24:]),
        }
    }
}

ns, _ := itb.NewSeed256(2048, makeBlake3Hash())
ds, _ := itb.NewSeed256(2048, makeBlake3Hash())
ss, _ := itb.NewSeed256(2048, makeBlake3Hash())

Hash Function Wrappers

// 128-bit: HashFunc128 = func(data []byte, seed0, seed1 uint64) (lo, hi uint64)
// SipHash-2-4 (PRF) — see Optimized Hash Wrappers above
// AES-NI cached (PRF, hardware-accelerated) — see Optimized Hash Wrappers above

// 256-bit: HashFunc256 = func(data []byte, seed [4]uint64) [4]uint64
// BLAKE3 keyed cached (PRF, SIMD) — see Optimized Hash Wrappers above

// 512-bit: HashFunc512 = func(data []byte, seed [8]uint64) [8]uint64
// BLAKE2b-512 keyed cached (PRF, native 512-bit) — see Optimized Hash Wrappers above

Key Size Selection

// 128-bit hash: up to 1024-bit keys
ns128, _ := itb.NewSeed128(1024, hashes.SipHash24())
ds128, _ := itb.NewSeed128(1024, hashes.SipHash24())
ss128, _ := itb.NewSeed128(1024, hashes.SipHash24())

// 256-bit hash: up to 2048-bit keys
ns256, _ := itb.NewSeed256(2048, hashes.BLAKE3())
ds256, _ := itb.NewSeed256(2048, hashes.BLAKE3())
ss256, _ := itb.NewSeed256(2048, hashes.BLAKE3())

// 512-bit hash: up to 2048-bit keys
ns512, _ := itb.NewSeed512(2048, hashes.BLAKE2b512())
ds512, _ := itb.NewSeed512(2048, hashes.BLAKE2b512())
ss512, _ := itb.NewSeed512(2048, hashes.BLAKE2b512())

Seed Alignment Requirements

Seed Type	Bits Range	Bits Alignment	Components	Components Alignment
Seed128	[512, 2048]	multiple of 128	[8, 32]	×2
Seed256	[512, 2048]	multiple of 256	[8, 32]	multiple of 4
Seed512 (512-bit)	[512, 2048]	multiple of 512	[8, 32]	multiple of 8

Minimum Container Size

Minimum container size depends on the API mode. Encrypt/Stream uses ceil(keyBits / log₂(56)) pixels, ensuring encoding ambiguity (56^P) exceeds the key space. Auth uses ceil(keyBits / log₂(7)) pixels, ensuring CCA ambiguity (7^P) exceeds the key space:

Key Size	Mode	Min Pixels → Container	Noise Barrier
1024 bits	Encrypt/Stream	177 → 196 (14×14)	2^1568 ≥ 2^1024
1024 bits	Auth	365 → 400 (20×20)	2^3200 ≥ 2^1024
2048 bits	Encrypt/Stream	353 → 361 (19×19)	2^2888 ≥ 2^2048
2048 bits	Auth	730 → 784 (28×28)	2^6272 ≥ 2^2048

Output Format

Offset  Size     Content
0       N        Nonce (crypto/rand, public; N = 16/32/64 bytes for 128/256/512-bit nonce)
N       2        Width (uint16 big-endian)
N+2     2        Height (uint16 big-endian)
N+4     W×H×8    Raw RGBWYOPA pixel data with embedded encrypted payload

Default nonce size is 128-bit (16 bytes). Configurable to 256-bit (32 bytes) or 512-bit (64 bytes) via SetNonceBits. The output format is identical across all three hash width variants.

Security Summary

Property	ITB
Key space	Up to 2^2048
Grover resistance	√P × 2^keyBits (Core/Silent Drop) to √P × 2^(keyBits/2) (MAC + Reveal)
Plausible deniability	✓ All modes (wrong seed → garbage indistinguishable from valid plaintext)
Encoding ambiguity	✓ All modes (7^P unverifiable rotation combinations, survives CCA; CSPRNG residue adds independent ambiguity in data positions, Proof 10)
Triple-seed isolation	✓ All modes (noiseSeed / dataSeed / startSeed independent; CCA leaks noiseSeed only)
Oracle-free deniability	✓ Core ITB / MAC + Silent Drop; MAC + Reveal has CCA oracle limited to noise positions
Known-plaintext resistance	3-factor under PRF assumption for Full KPA: PRF non-invertibility + independent startSeed + 7-rotation × 8-noisePos per-pixel ambiguity at signal/noise 1:1. gcd(7,8) byte-splitting is a 4th factor effective only under Partial KPA (see Proof 4a)
Chosen-plaintext resistance	Independent maps
Noise absorption	✓ Core ITB / MAC + Silent Drop; bypassed via CCA in MAC + Reveal (CSPRNG residue in data positions survives, Proof 10)
Noise barrier (min container)	2^1568 (1024-bit, P=196) to 2^2888 (2048-bit, P=361)
Hash function requirement	PRF required; PRF and barrier are complementary — neither sufficient alone (see Proof 4a)
Nonce reuse protection	128/256/512-bit per-message nonce (default 128-bit)
Nonce misuse resistance	Local only: at most 2–3 colliding messages theoretically affected. In practice ITB's per-encryption noise + rotation + channelXOR mean C1 ⊕ C2 does NOT reduce to plaintext_1 ⊕ plaintext_2 as in a stream cipher — plaintext recovery requires the full demasker pipeline whose output is the hash stream, not plaintext bits (see ITB.md §8). Seeds remain secret (PRF non-invertibility), future messages safe, no key rotation required. Single collision too few observations for Simon / structural / quantum algebraic attacks. Unlike AES-GCM where nonce reuse leaks H and enables forgery until key rotation (global catastrophe)
Storage overhead	1.14× (56 data bits per 64-bit pixel)

Integrity (MAC-Inside-Encrypt)

The core construction provides confidentiality only. For integrity protection against bit-flipping attacks, use the MAC-Inside-Encrypt pattern — the MAC is encrypted inside the container, preserving oracle-free deniability:

// 128-bit variant
encrypted, err := itb.EncryptAuthenticated128(ns128, ds128, ss128, plaintext, myMACFunc)
original, err = itb.DecryptAuthenticated128(ns128, ds128, ss128, encrypted, myMACFunc)

// 256-bit variant
encrypted, err = itb.EncryptAuthenticated256(ns256, ds256, ss256, plaintext, myMACFunc)
original, err = itb.DecryptAuthenticated256(ns256, ds256, ss256, encrypted, myMACFunc)

// 512-bit variant
encrypted, err = itb.EncryptAuthenticated512(ns512, ds512, ss512, plaintext, myMACFunc)
original, err = itb.DecryptAuthenticated512(ns512, ds512, ss512, encrypted, myMACFunc)

Important: never place a MAC outside the encrypted container in cleartext — this creates a verification oracle that breaks deniability.

Triple-Seed Isolation

All three seeds must be distinct pointers — passing the same seed as multiple parameters returns an error:

// This will fail:
encrypted, err := itb.Encrypt128(seed, seed, seed, data)
// Error: "itb: all three seeds must be different (triple-seed isolation)"

// Correct usage: three independent seeds
encrypted, err := itb.Encrypt128(noiseSeed, dataSeed, startSeed, data)

Formal Security Model

A simulation-based proof is a purely mathematical construction: "for every adversary A in the real world, there exists a simulator S in the ideal world such that the outputs of A and S are indistinguishable." This is proven logically, not computationally. It is independent of hardware, logic system, or computational model.

ITB does not fit cleanly into the standard binary security model:

• Standard model: the adversary either distinguishes (break) or does not (secure). Binary.
• ITB: the adversary always receives output. The output is always "valid." There is no point where the system returns accept/reject. Instead, the result is a spectrum of plausibility — every key produces output, and there is no way to rank candidates without external context.

The semantics of decryption are ternary:

1. Correct key → correct plaintext
2. Wrong key → garbage indistinguishable from plaintext
3. Observer → cannot determine which of the two cases is present

Possible formalization paths:

• Indistinguishability-based definitions (standard in cryptography, binary logic — sufficient)
• Simulation-based proof with an ideal functionality that always returns random bytes (this is the "ideal world" of ITB — the real-world output is indistinguishable from random)
• Quantitative information flow (how many bits leak — the per-byte barrier shows 0 bits leaked per observation)

All three approaches use standard mathematics. The formal relationship between ITB's Ambiguity-Based Security and Shannon's framework remains an open research question (see SCIENCE.md §7).

See Also

• ITB.md — How the barrier works (accessible explanation)
• ITB3.md — Triple Ouroboros (7-seed variant, 3× security)
• FEATURES.md — Complete feature list and security properties
• PROOFS.md — Formal security proofs
• SCIENCE.md — Scientific analysis and formal security arguments
• SECURITY.md — Security reference tables
• HWTHREATS.md — Hardware-level threat analysis (Spectre, Meltdown, Rowhammer, etc.)
• HARNESS.md — Additional analysis of non-crypto hashes within barrier bias absorption and SAT calibration.
• REDTEAM.md — Empirical Red Team validation (12-primitive hash matrix, multiple statistical / structural distinguishers, 2×2 Ouroboros × BarrierFill matrix)
• hashes/CONSTRUCTIONS.md — Per-primitive construction descriptions (how each registry name wraps its underlying RFC / NIST primitive, where the wrappers diverge from the canonical specification, and why)

License

MIT — see LICENSE.

Documentation

Overview

Package itb — 4-way batched Areion-SoEM primitives.

AreionSoEM256x4 and AreionSoEM512x4 process four independent (key, input) tuples simultaneously using the upstream `github.com/jedisct1/go-aes` parallel AES-round primitives. On x86_64 CPUs with VAES (AVX-512) the inner loop dispatches to a single `vaesenc` instruction processing four AES blocks in one ZMM register; without VAES the same Block4 path falls back to four sequential AES-NI instructions. ARM64 with Crypto Extensions uses the analogous parallel hardware instruction.

Bit-exact parity invariant. For every i in {0,1,2,3}:

AreionSoEM256x4(keys, inputs)[i] == aes.AreionSoEM256(&keys[i], &inputs[i])
AreionSoEM512x4(keys, inputs)[i] == aes.AreionSoEM512(&keys[i], &inputs[i])

This is enforced empirically by `TestAreionSoEM{256,512}x4Parity` in areion_test.go on every test run and is mandatory for ITB security claims under the batched dispatch path (any divergence breaks the PRF assumption invocation in SECURITY.md).

Algorithm reference. The SoEM construction is from Iwata-Mennink (Sum of Even-Mansour, beyond-birthday-bound PRF):

F(k1, k2, m) = P(m ⊕ k1) ⊕ P(m ⊕ k2 ⊕ d)

where P is the Areion permutation (10 rounds for Areion256, 15 for Areion512), d is a fixed domain separation constant (`[N]byte{0x01}`), k1 is the first half of the SoEM key, k2 the second half. The upstream serial reference is in `github.com/jedisct1/go-aes/areion.go` (`AreionSoEM256` / `AreionSoEM512`). The 4-way batched composition here applies the permutation to four independent states in parallel using the `Block4`/`RoundNoKey4HW`/`FinalRoundNoKey4HW`/`XorBlock4` primitives from the same upstream package.

Layout. Each batched permutation reshapes the four Areion states from the natural array-of-structures layout (one contiguous 32- or 64-byte state per lane) into structure-of-arrays layout where every Block4 holds the same logical AES-block index across all four lanes. The reshape is a one-shot 64–256 byte copy at entry and exit; all round operations run entirely in the SoA layout so VAES instructions can process four lanes per issued instruction without per-round gather/scatter cost.

Light secure bit-permutation mode without performance trade-off (Recommended to use with Triple Ouroboros)
itb.SetBitSoup(1)       // Triple Ouroboros bit-level split ("bit soup"; default: 0 = byte-level)
                        // automatically enabled for Single Ouroboros if itb.SetLockSoup(1) is enabled or vice versa

Most secure bit-permutation mode with performance trade-off ~2×-7× slower
itb.SetLockSoup(1)      // optional Insane Interlocked Mode: per-chunk PRF-keyed bit-permutation overlay on top of bit-soup;
                        // ~2×-7× slower, raises SAT cryptanalysis to information-theoretic instance-formulation
                        // automatically enabled for Single Ouroboros if itb.SetBitSoup(1) is enabled or vice versa

// Areion-SoEM-256 with built-in batched VAES dispatch — fastest 256-bit
// PRF wiring, recommended default. The paired factory returns (single,
// batched, fixedKey) sharing the same fixed key; ITB processChunk256
// dispatches per-pixel hashing four pixels per batched call. The
// runtime CPU detection picks the most capable VAES tier available —
// AVX-512+VAES on ZMM (Intel Ice Lake+, AMD Zen 4+), AVX2+VAES on
// YMM (AMD Zen 3, Alder Lake E-cores), or a portable Go fallback via
// aes.Round4HW on hardware without VAES (correctness preserved on
// every platform).
//
// Pass nothing for a CSPRNG-generated key (returned alongside the
// closure for cross-process persistence — save it!) or pass a saved
// [32]byte key on the restore path. Three independent factory calls
// give three independent fixed keys.
fnN, batchN, keyN := itb.MakeAreionSoEM256Hash()
fnD, batchD, keyD := itb.MakeAreionSoEM256Hash()
fnS, batchS, keyS := itb.MakeAreionSoEM256Hash()
saveKey("noise-key", keyN[:]) // persistence — write to config / KMS
saveKey("data-key", keyD[:]) // persistence — write to config / KMS
saveKey("start-key", keyS[:]) // persistence — write to config / KMS
ns256, _ := itb.NewSeed256(1024, fnN)
ds256, _ := itb.NewSeed256(1024, fnD)
ss256, _ := itb.NewSeed256(1024, fnS)
ns256.BatchHash = batchN
ds256.BatchHash = batchD
ss256.BatchHash = batchS
// (analogous wiring for ns256, ds256, ss256 — three independent (hashFn, batchFn, hashKey)
// triples, three independent saved keys)

encrypted, _ := itb.Encrypt256(ns256, ds256, ss256, plaintext)
decrypted, _ := itb.Decrypt256(ns256, ds256, ss256, encrypted)

// Areion-SoEM-512 with batched VAES dispatch — same factory pattern,
// 64-byte key, 64-byte input, 8 × uint64 seed. Use itb.NewSeed512 +
// itb.Encrypt512 / itb.Decrypt512 in place of the 256-bit variants.
fnN, batchN, keyN := itb.MakeAreionSoEM512Hash()
fnD, batchD, keyD := itb.MakeAreionSoEM512Hash()
fnS, batchS, keyS := itb.MakeAreionSoEM512Hash()
saveKey("noise-key", keyN[:]) // persistence — write to config / KMS
saveKey("data-key", keyD[:]) // persistence — write to config / KMS
saveKey("start-key", keyS[:]) // persistence — write to config / KMS
ns512, _ := itb.NewSeed512(2048, fnN)
ds512, _ := itb.NewSeed512(2048, fnD)
ss512, _ := itb.NewSeed512(2048, fnS)
ns512.BatchHash = batchN
ds512.BatchHash = batchD
ss512.BatchHash = batchS
// (analogous wiring for ns512, ds512, ss512 — three independent (hashFn, batchFn, hashKey)
// triples, three independent saved keys)

encrypted, _ := itb.Encrypt512(ns512, ds512, ss512, plaintext)
decrypted, _ := itb.Decrypt512(ns512, ds512, ss512, encrypted)

// Other PRF primitives — use the hashes/ subpackage. Same variadic
// pattern: pass nothing for random key, pass a saved key for restore.
// Returned key is always emitted as the second value — capture it
// for persistence (test fixtures discard via `_`).

// SipHash-2-4 (128-bit hash, 1024-bit effective key) — exception:
// no internal fixed key (keying material is the seed components),
// so this is the only factory that returns just one value.
ns, _ := itb.NewSeed128(1024, hashes.SipHash24())
ds, _ := itb.NewSeed128(1024, hashes.SipHash24())
ss, _ := itb.NewSeed128(1024, hashes.SipHash24())

encrypted, _ := itb.Encrypt128(ns, ds, ss, plaintext)
decrypted, _ := itb.Decrypt128(ns, ds, ss, encrypted)

// AES-CMAC (128-bit hash, 1024-bit effective key, AES-NI hardware
// path on amd64 / arm64 hosts that expose the AES round instructions)
aesFn, aesKey := hashes.AESCMAC()
saveKey("aescmac-noise", aesKey[:])
ns, _ = itb.NewSeed128(1024, aesFn)
// (repeat for ds, ss with independent keys; saveKey omitted in subsequent
// snippets for brevity — but always required on the persistence path)

// BLAKE3 keyed (256-bit hash, 2048-bit effective key)
b3Fn, b3Key := hashes.BLAKE3()
_ = b3Key
ns256, _ = itb.NewSeed256(2048, b3Fn)

// BLAKE2b-512 (512-bit hash, 2048-bit effective key, native 512-bit
// output and up to 64-byte key)
b2Fn, b2Key := hashes.BLAKE2b512()
_ = b2Key
ns512, _ = itb.NewSeed512(2048, b2Fn)

// Custom factory pattern (advanced) — write your own HashFunc when
// you need a primitive not covered by the hashes/ subpackage, or
// want a different keying / pooling strategy. The pattern below
// is what hashes.BLAKE3() itself ships, reproduced here as a
// reference. Three techniques worth noting:
//
//   - sync.Pool amortises per-call allocation of the scratch buffer
//   - blake3.NewKeyed produces a hasher template; Clone() per call
//     sidesteps the data race that Reset() on a shared hasher would
//     cause under ITB's parallel goroutines in process256
//   - the payload region is zero-padded out to seedInjectBytes (32)
//     so all four seed uint64's contribute even when len(data) is
//     shorter than 32 (e.g. a 20-byte ITB pixel input would
//     otherwise drop seed[2..3] silently)
func makeBlake3Hash() itb.HashFunc256 {
    var key [32]byte
    rand.Read(key[:])
    template, _ := blake3.NewKeyed(key[:])
    pool := &sync.Pool{New: func() any { b := make([]byte, 0, 128); return &b }}

    return func(data []byte, seed [4]uint64) [4]uint64 {
        h := template.Clone()
        const seedInjectBytes = 32
        payloadLen := len(data)
        if payloadLen < seedInjectBytes { payloadLen = seedInjectBytes }
        ptr := pool.Get().(*[]byte)
        mixed := *ptr
        if cap(mixed) < payloadLen { mixed = make([]byte, payloadLen) } else { mixed = mixed[:payloadLen] }
        for i := len(data); i < payloadLen; i++ { mixed[i] = 0 }
        copy(mixed[:len(data)], data)
        for i := 0; i < 4; i++ {
            off := i * 8
            binary.LittleEndian.PutUint64(mixed[off:], binary.LittleEndian.Uint64(mixed[off:])^seed[i])
        }
        h.Write(mixed)
        *ptr = mixed; pool.Put(ptr)
        var buf [32]byte
        h.Sum(buf[:0])
        return [4]uint64{
            binary.LittleEndian.Uint64(buf[0:]),  binary.LittleEndian.Uint64(buf[8:]),
            binary.LittleEndian.Uint64(buf[16:]), binary.LittleEndian.Uint64(buf[24:]),
        }
    }
}

ns256, _ = itb.NewSeed256(2048, makeBlake3Hash())
ds256, _ = itb.NewSeed256(2048, makeBlake3Hash())
ss256, _ = itb.NewSeed256(2048, makeBlake3Hash())

Authenticated Encryption (MAC-Inside-Encrypt)

The core construction provides confidentiality only. For integrity protection, use EncryptAuthenticated128 (or 256/512 variant) which encrypts a MAC tag inside the container, preserving oracle-free deniability. The MAC function is pluggable:

encrypted, _ := itb.EncryptAuthenticated128(ns, ds, ss, plaintext, myMACFunc)
decrypted, _ := itb.DecryptAuthenticated128(ns, ds, ss, encrypted, myMACFunc)

MACFunc is defined as func([]byte) []byte — any function that takes data and returns a fixed-size tag. The MAC covers the entire decrypted capacity (COBS + null terminator + fill), preventing CCA spatial pattern leaks.

Authenticated variants are available for all three widths: EncryptAuthenticated128, EncryptAuthenticated256, EncryptAuthenticated512, DecryptAuthenticated128, DecryptAuthenticated256, DecryptAuthenticated512.

Triple Ouroboros authenticated variants (7 seeds): EncryptAuthenticated3x128, EncryptAuthenticated3x256, EncryptAuthenticated3x512, DecryptAuthenticated3x128, DecryptAuthenticated3x256, DecryptAuthenticated3x512.

Each authenticated entry point has a Cfg counterpart taking a Config first argument for per-instance overrides (EncryptAuthenticated128Cfg / DecryptAuthenticated128Cfg and the 256/512 mirrors, plus the Triple-Ouroboros EncryptAuthenticated3x128Cfg / DecryptAuthenticated3x128Cfg and mirrors). See Config / SnapshotGlobals.

Short-name aliases

Every authenticated entry point is also reachable under a shorter name with the [EncryptAuthenticated] / [DecryptAuthenticated] prefix collapsed to EncryptAuth / DecryptAuth — for example EncryptAuth128 forwards to EncryptAuthenticated128 and DecryptAuth3x256Cfg forwards to DecryptAuthenticated3x256Cfg. The alias surface covers all 24 entry points and is allocation-free.

Width-less convenience helpers

The width-suffixed entry points (Encrypt128 / Encrypt256 / Encrypt512 and the corresponding Decrypt / authenticated / streaming counterparts) require the caller to pick the correct suffix for the chosen seed type. The width-less helpers Encrypt, Decrypt, Encrypt3x, Decrypt3x, EncryptAuth, DecryptAuth, EncryptAuth3x, DecryptAuth3x, EncryptStream, DecryptStream, EncryptStream3x, DecryptStream3x, EncryptStreamAuth, DecryptStreamAuth, EncryptStreamAuth3x, and DecryptStreamAuth3x accept the seed bundle as `any` and dispatch internally on the concrete pointer type. All seeds in the bundle must carry one matching `*Seed{N}` width; mixing widths returns an error. The dispatcher resolves the width once per call and forwards verbatim — no allocation beyond what the underlying width-suffixed call would do anyway. Callers using a single seed width across the application can freeze on the width-less helpers without losing performance.

Streaming (Chunked Encryption)

For large data that exceeds available memory, use the streaming API. Data is split into chunks, each encrypted as a self-contained ITB message with its own nonce. Chunks can be concatenated and later decrypted sequentially. ChunkSize selects an appropriate chunk size automatically (default DefaultChunkSize = 16 MB).

err := itb.EncryptStream128(ns, ds, ss, largeData, 0, func(chunk []byte) error {
    _, err := file.Write(chunk)
    return err
})

var result []byte
err = itb.DecryptStream128(ns, ds, ss, fileData, func(chunk []byte) error {
    result = append(result, chunk...)
    return nil
})

Streaming variants are available for all three widths: EncryptStream128, EncryptStream256, EncryptStream512, DecryptStream128, DecryptStream256, DecryptStream512.

Triple Ouroboros streaming variants (7 seeds): EncryptStream3x128, EncryptStream3x256, EncryptStream3x512, DecryptStream3x128, DecryptStream3x256, DecryptStream3x512.

ParseChunkLen inspects the first 20 bytes of a chunk header and reports the chunk's total length on the wire, letting external streaming consumers (FFI bindings, custom file-format wrappers) walk a concatenated chunk stream one chunk at a time without buffering the whole stream in memory. The function is also exposed through the C ABI as ITB_ParseChunkLen.

Each streaming entry point has a Cfg counterpart taking a Config first argument for per-instance overrides (EncryptStream128Cfg / DecryptStream128Cfg and the 256/512 mirrors, plus the Triple-Ouroboros EncryptStream3x128Cfg / DecryptStream3x128Cfg and mirrors). ParseChunkLenCfg is the matching per-instance chunk-header reader, honouring the cfg's own NonceBits when walking a stream produced by an encryptor that overrides the global. See Config / SnapshotGlobals.

The width-less plain-stream entry points EncryptStream and DecryptStream (plus the Triple counterparts EncryptStream3x / DecryptStream3x) accept seed pointers typed as `any` and drive the read/write loop internally via io.Reader / io.Writer. They dispatch on the concrete seed pointer type to the matching width-suffixed per-chunk path. The on-wire bytes are identical to the callback-driven helpers above; choice between the two is a caller-side ergonomic preference.

Streaming AEAD (chunked authenticated encryption)

The Streaming AEAD construction binds every chunk's MAC tag to a 32-byte CSPRNG-fresh stream anchor (written once as a wire prefix preceding chunk 0), the cumulative pixel offset of every preceding chunk, and a final-flag bit recovered from inside the encrypted container — defending against chunk reorder, replay within or across streams sharing the PRF / MAC key, silent mid-stream drop, and truncate-tail. The wire format adds 32 bytes of stream prefix plus one byte of trailing flag per chunk inside the deniable container layout; no externally visible MAC tag.

Per-chunk primitives (one chunk per call, caller drives the loop): EncryptStreamAuthenticated128 / EncryptStreamAuthenticated256 / EncryptStreamAuthenticated512 and the corresponding DecryptStreamAuthenticated128 / DecryptStreamAuthenticated256 / DecryptStreamAuthenticated512 entry points, plus the Triple-Ouroboros 7-seed variants EncryptStreamAuthenticated3x128 / EncryptStreamAuthenticated3x256 / EncryptStreamAuthenticated3x512 and decrypt mirrors. Each takes the streamID, the running cumulative pixel offset, and finalFlag (true on the terminating chunk, false otherwise) explicitly. The Cfg counterparts (EncryptStreamAuthenticated128Cfg etc., 24 in total across width × Single+Triple × Encrypt+Decrypt × no-Cfg+Cfg) honour a per-instance Config override.

Higher-level helpers covering the per-chunk loop server-side: EncryptStreamAuth128 / EncryptStreamAuth256 / EncryptStreamAuth512 (and the [EncryptStreamAuth3x{N}] variants) drive a per-chunk emit callback under fixed seed handles, drawing the 32-byte stream anchor, advancing cumulative pixel offset, and flipping finalFlag on the last chunk. The width-less EncryptStreamAuth / DecryptStreamAuth (plus the Triple counterparts EncryptStreamAuth3x / DecryptStreamAuth3x) instead consume an io.Reader and write to an io.Writer directly, dispatching on the concrete seed pointer type. Aliasing follows the same `Authenticated` → `Auth` collapse rule used by the Single Message family.

ErrStreamTruncated and ErrStreamAfterFinal are the two stream-specific sentinel errors. Decrypt-side helpers return ErrStreamTruncated when the on-wire transcript exhausts before a chunk with finalFlag = true is observed, and ErrStreamAfterFinal when additional chunk bytes follow the terminating chunk. Either error condition leaves any plaintext emitted earlier in the stream trustworthy as far as it went; the trailing data after the failure point is rejected verbatim.

Streaming bindings asymmetry

For the No-MAC paths, the Go core and the github.com/everanium/itb/easy package expose io.Reader / io.Writer entry points (EncryptStream / DecryptStream and the corresponding github.com/everanium/itb/easy.Encryptor.EncryptStreamIO / github.com/everanium/itb/easy.Encryptor.DecryptStreamIO methods) that drive the read/write loop internally. The official bindings to other languages expose the No-MAC stream surface as per-chunk free functions only and let the caller drive the loop. The two patterns produce identical on-wire bytes; choice between them is a Go-side convenience.

Triple Ouroboros (7-seed variant)

Triple Ouroboros splits plaintext into 3 parts at the byte level (every 3rd byte), encrypting each into 1/3 of the pixel data with independent dataSeed and startSeed, sharing noiseSeed. Output format is identical to standard ITB. Security: P × 2^(3×keyBits) under CCA. 7 seeds: 3×dataSeed + 3×startSeed + 1×noiseSeed. All seven seeds must be distinct pointers.

encrypted, _ := itb.Encrypt3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3,
    startSeed1, startSeed2, startSeed3, plaintext)
decrypted, _ := itb.Decrypt3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3,
    startSeed1, startSeed2, startSeed3, encrypted)

Available for all three hash widths: Encrypt3x128, Encrypt3x256, Encrypt3x512, Decrypt3x128, Decrypt3x256, Decrypt3x512.

Each Triple Ouroboros entry point has a Cfg counterpart taking a Config first argument for per-instance overrides (Encrypt3x128Cfg / Decrypt3x128Cfg and the 256/512 mirrors). See Config / SnapshotGlobals.

For best throughput, use 512-bit ITB key — security becomes P × 2^1536 (3 × 512), stronger than Single 1024-bit, while ChainHash runs at 512-bit speed. See [ITB3.md] for accessible explanation and [BENCH3.md] for benchmarks.

Bit Soup (opt-in)

SetBitSoup configures plaintext split granularity for the whole process. Default mode 0 is byte-level (shipped behaviour). Mode 1 enables bit-level split ("bit soup").

On Triple Ouroboros, mode 1 routes every third bit of the plaintext to a different snake, so no snake carries a real plaintext byte — each snake's payload is a fixed public bit-permutation across three consecutive plaintext bytes. On Single Ouroboros, mode 1 engages the Lock Soup overlay (the public fixed bit-permutation alone gives no architectural barrier on a single snake, so the Single bit-level path is keyed by construction; see SetLockSoup).

Bit soup relocates the SAT-cryptanalysis barrier from the computational layer to the instance-formulation layer. Standard cryptanalytic intuition pictures SAT recovery as a solver-speed problem: "given a defined NP instance, how fast can the attacker solve it." Bit soup targets the prior question: "does the attacker have enough observation to define the instance." Under Partial KPA + realistic protocol traffic, the per-snake SAT instance is information-theoretically under-determined at typical crib coverage — multiple joint (seed, startPixel) tuples satisfy the sparse constraint set. Faster solvers, including any hypothetical shortcut to PRF inversion, do not widen the crib or convert under-determination into determination. This is orthogonal to, not stronger than, computational hardness.

Applies uniformly to every Triple Ouroboros variant — Encrypt3x128 / Decrypt3x128, the 256- / 512-bit mirrors, EncryptAuthenticated3x128 / DecryptAuthenticated3x128 and their mirrors, and EncryptStream3x128 / DecryptStream3x128 and mirrors — and to every Single Ouroboros variant: Encrypt128 / Decrypt128, the 256/512 mirrors, authenticated and streaming counterparts. The ciphertext wire format is identical in all modes. Callers must set the same mode on both encrypt and decrypt sides of the channel. Each variant's Cfg counterpart honours BitSoup / LockSoup as a per-instance override — see Config / SnapshotGlobals.

itb.SetBitSoup(1)  // whole-process opt-in; default 0 = byte-level
                   // (Single) automatically engages Lock Soup overlay
itb.SetLockSoup(1) // optional Insane Interlocked Mode overlay: per-chunk PRF-keyed
                   // bit-permutation; ~2×-7× slower; auto-enables SetBitSoup(1)

SetLockSoup is the keyed-bit-permutation overlay. It replaces the public fixed bit-permutation with a per-chunk PRF-keyed bijection drawn from a 2^33-mask space (Triple, balanced 8-of-24 partition) or 2^64 permutation space (Single, full S_24 via Lehmer-code unrank), derived deterministically per chunk from the encrypt-side noiseSeed and nonce. Each crib chunk multiplies attacker enumeration by the per-chunk mask space size with no shared algebraic structure to couple chunks across, making the joint SAT instance under-determined under any realistic crib coverage. Performance cost is ~2×–7× over plain Bit Soup depending on platform — the BMI2 PEXT/PDEP path on x86 (Haswell+, Excavator+/Zen 1+) on Triple, AVX-512 VBMI VPERMB path on x86 (Ice Lake+, Zen 4+) on Single, sit near the lower bound; Pure Go fallbacks near the upper. The trade-off is acceptable only where the architectural barrier is the deployment priority. Default SetLockSoup(0) leaves Bit Soup behaviour unchanged.

Setting SetLockSoup(1) automatically engages SetBitSoup(1) — the overlay layers on top of bit soup, so the two flags are coupled in the on-direction. SetBitSoup remains independent in the off-direction.

See [ITB.md] / [ITB3.md] for accessible explanation and [REDTEAM.md] Phase 2g for the defensive framing in the SAT attack context.

Per-instance configuration ([Config], Cfg variants)

Every public encrypt / decrypt entry point has a Cfg counterpart taking a Config first argument: Encrypt128Cfg / Decrypt128Cfg and the 256/512 mirrors for Single Ouroboros, Encrypt3x128Cfg / Decrypt3x128Cfg and mirrors for Triple Ouroboros, the matching authenticated and streaming counterparts, and ParseChunkLenCfg. A nil cfg falls through to the process-global setter state, preserving the legacy entry-point behaviour bit-exactly. A non-nil cfg overrides NonceBits / BarrierFill / BitSoup / LockSoup / LockSeed on a per-call basis without mutating the process globals — multiple encryptors with distinct configurations can coexist in one process.

SnapshotGlobals returns a fresh Config initialised from the current global setter state, pinning the per-instance value to the global at snapshot time. Subsequent global mutations do not leak into a previously-snapshotted Config; subsequent mutations of a snapshotted Config do not leak back into the globals. The github.com/everanium/itb/easy.Encryptor surface uses this at New / New3 time to seed each encryptor's own Config copy.

State persistence — Blob

Blob128 / Blob256 / Blob512 pack the native-API encryptor material (per-seed hash key + Components + optional dedicated lockSeed + optional MAC key + name) plus the captured process-wide configuration into one self-describing JSON blob. Export / Export3 produce the blob; Import / Import3 reverse it, applying the captured globals via SetNonceBits / SetBarrierFill / SetBitSoup / SetLockSoup before populating the struct's public Key* / Components fields. The receiver wires Hash / BatchHash from the saved key bytes through the matching factory (e.g. MakeAreionSoEM512HashWithKey), keeping the pluggable-PRF philosophy of the native API. Optional LockSeed and MAC slots ride in the trailing Blob128Opts / Blob256Opts / Blob512Opts options struct. The github.com/everanium/itb/easy.Encryptor.Export surface is the high-level alternative for callers that prefer constructor-bound primitive selection plus auto-coupling.

AttachLockSeed (dedicated lockSeed)

Seed128.AttachLockSeed / Seed256.AttachLockSeed / Seed512.AttachLockSeed route the bit-permutation derivation channel through a dedicated lockSeed instead of the noiseSeed, without changing the public Encrypt / Decrypt signatures. The per-chunk PRF closure captures BOTH the lockSeed's Components (independent keying material) AND its Hash function, so the overlay channel may legitimately run a different PRF primitive from the noise-injection channel within the same native width (the Seed128.AttachLockSeed / Seed256.AttachLockSeed / Seed512.AttachLockSeed type signatures enforce width match). This yields keying-material isolation AND algorithm diversity for defence-in-depth on the bit-permutation overlay. The dedicated seed is a fourth (Single) or fifth-through-eighth (Triple) seed slot allocated alongside the standard noise / data / start trio. With no dedicated lockSeed attached, the overlay falls through to the noiseSeed's Components and Hash.

The bit-permutation overlay must be engaged via SetBitSoup (1) or SetLockSoup (1) before the first Encrypt call — the build-PRF guard panics with ErrLockSeedOverlayOff on encrypt-time when an attach is present without either flag, surfacing the misuse loudly rather than silently producing byte-level ciphertext that ignores the dedicated lockSeed entirely.

Three attach-time misuse paths panic with their own sentinels: ErrLockSeedSelfAttach (passing the same handle for noise and lock), ErrLockSeedComponentAliasing (two distinct seed handles whose Components slices share the same backing array), and ErrLockSeedAfterEncrypt (calling AttachLockSeed on a noise seed that has already produced ciphertext — switching mid-session would break decryptability of pre-switch chunks).

itb.SetLockSoup(1)              // engage overlay BEFORE attach
fnN, batchN, _ := itb.MakeAreionSoEM512Hash()
fnL, batchL, _ := itb.MakeAreionSoEM512Hash()
ns, _ := itb.NewSeed512(2048, fnN); ns.BatchHash = batchN
ls, _ := itb.NewSeed512(2048, fnL); ls.BatchHash = batchL
ns.AttachLockSeed(ls)           // bit-permutation derivation now keyed by ls
// ... ds, ss as usual; ns.AttachedLockSeed() returns ls.
// Receiver mirrors the wire-up after rebuilding ls from saved
// components / hash key.

The [easy.Encryptor] surface auto-allocates and wires the dedicated lockSeed when [easy.Encryptor.SetLockSeed] is called, auto-couples LockSoup + BitSoup, and persists the dedicated seed material across [easy.Encryptor.Export] / [easy.Encryptor.Import] — no caller-side AttachLockSeed bookkeeping required on the high-level path.

Parallelism Control

Pixel processing is parallelized across available CPU cores by default. To limit CPU usage (e.g., on shared servers), use SetMaxWorkers:

itb.SetMaxWorkers(4) // use at most 4 cores

Pass 0 to use all available CPUs (default). Valid range: 0 to 256. The setting is global and thread-safe (atomic). Query the current limit with GetMaxWorkers.

Nonce Configuration

By default the nonce is 128 bits (NonceSize = 16 bytes). For higher collision resistance, increase the nonce size with SetNonceBits:

itb.SetNonceBits(256) // 256-bit nonce (~2^128 birthday bound)

Valid values: 128, 256, 512. The setting is global and thread-safe (atomic). Both sender and receiver must use the same nonce size. Query the current setting with GetNonceBits.

Barrier Fill (CSPRNG Margin)

The container side is increased by a configurable margin to guarantee CSPRNG residue in every container (Proof 10: No Perfect Fill). The gap between pixel capacity and data requirement ensures that some pixel channels carry only CSPRNG random data, even after CCA eliminates noise bits. Default margin is 1. To increase the CSPRNG fill margin:

itb.SetBarrierFill(4) // side += 4 instead of side += 1

Valid values: 1, 2, 4, 8, 16, 32. Panics on invalid input. Asymmetric: the receiver does not need the same value as the sender, because the container dimensions are stored in the header. The setting is global and thread-safe (atomic). Query the current value with GetBarrierFill.

Index

• Constants
• Variables
• func AreionSoEM256x4(keys *[4][64]byte, inputs *[4][32]byte) [4][32]byte
• func AreionSoEM512x4(keys *[4][128]byte, inputs *[4][64]byte) [4][64]byte
• func ChunkSize(dataLen int) int
• func Decrypt(noiseSeed, dataSeed, startSeed any, fileData []byte) ([]byte, error)
• func Decrypt3x(...) ([]byte, error)
• func Decrypt3x128(...) ([]byte, error)
• func Decrypt3x128Cfg(cfg *Config, ...) ([]byte, error)
• func Decrypt3x256(...) ([]byte, error)
• func Decrypt3x256Cfg(cfg *Config, ...) ([]byte, error)
• func Decrypt3x512(...) ([]byte, error)
• func Decrypt3x512Cfg(cfg *Config, ...) ([]byte, error)
• func Decrypt128(noiseSeed, dataSeed, startSeed *Seed128, fileData []byte) ([]byte, error)
• func Decrypt128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, fileData []byte) ([]byte, error)
• func Decrypt256(noiseSeed, dataSeed, startSeed *Seed256, fileData []byte) ([]byte, error)
• func Decrypt256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, fileData []byte) ([]byte, error)
• func Decrypt512(noiseSeed, dataSeed, startSeed *Seed512, fileData []byte) ([]byte, error)
• func Decrypt512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, fileData []byte) ([]byte, error)
• func DecryptAuth(noiseSeed, dataSeed, startSeed any, fileData []byte, macFunc MACFunc) ([]byte, error)
• func DecryptAuth3x(...) ([]byte, error)
• func DecryptAuth3x128(...) ([]byte, error)
• func DecryptAuth3x128Cfg(cfg *Config, ...) ([]byte, error)
• func DecryptAuth3x256(...) ([]byte, error)
• func DecryptAuth3x256Cfg(cfg *Config, ...) ([]byte, error)
• func DecryptAuth3x512(...) ([]byte, error)
• func DecryptAuth3x512Cfg(cfg *Config, ...) ([]byte, error)
• func DecryptAuth128(noiseSeed, dataSeed, startSeed *Seed128, fileData []byte, macFunc MACFunc) ([]byte, error)
• func DecryptAuth128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, fileData []byte, ...) ([]byte, error)
• func DecryptAuth256(noiseSeed, dataSeed, startSeed *Seed256, fileData []byte, macFunc MACFunc) ([]byte, error)
• func DecryptAuth256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, fileData []byte, ...) ([]byte, error)
• func DecryptAuth512(noiseSeed, dataSeed, startSeed *Seed512, fileData []byte, macFunc MACFunc) ([]byte, error)
• func DecryptAuth512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, fileData []byte, ...) ([]byte, error)
• func DecryptAuthenticated3x128(...) ([]byte, error)
• func DecryptAuthenticated3x128Cfg(cfg *Config, ...) ([]byte, error)
• func DecryptAuthenticated3x256(...) ([]byte, error)
• func DecryptAuthenticated3x256Cfg(cfg *Config, ...) ([]byte, error)
• func DecryptAuthenticated3x512(...) ([]byte, error)
• func DecryptAuthenticated3x512Cfg(cfg *Config, ...) ([]byte, error)
• func DecryptAuthenticated128(noiseSeed, dataSeed, startSeed *Seed128, fileData []byte, macFunc MACFunc) ([]byte, error)
• func DecryptAuthenticated128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, fileData []byte, ...) ([]byte, error)
• func DecryptAuthenticated256(noiseSeed, dataSeed, startSeed *Seed256, fileData []byte, macFunc MACFunc) ([]byte, error)
• func DecryptAuthenticated256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, fileData []byte, ...) ([]byte, error)
• func DecryptAuthenticated512(noiseSeed, dataSeed, startSeed *Seed512, fileData []byte, macFunc MACFunc) ([]byte, error)
• func DecryptAuthenticated512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, fileData []byte, ...) ([]byte, error)
• func DecryptStream(noiseSeed, dataSeed, startSeed any, src io.Reader, dst io.Writer) error
• func DecryptStream3x(...) error
• func DecryptStream3x128(...) error
• func DecryptStream3x128Cfg(cfg *Config, ...) error
• func DecryptStream3x256(...) error
• func DecryptStream3x256Cfg(cfg *Config, ...) error
• func DecryptStream3x512(...) error
• func DecryptStream3x512Cfg(cfg *Config, ...) error
• func DecryptStream128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, ...) error
• func DecryptStream128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, ...) error
• func DecryptStream256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, ...) error
• func DecryptStream256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, ...) error
• func DecryptStream512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, ...) error
• func DecryptStream512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, ...) error
• func DecryptStreamAuth(noiseSeed, dataSeed, startSeed any, src io.Reader, dst io.Writer, mac MACFunc) error
• func DecryptStreamAuth3x(...) error
• func DecryptStreamAuth3x128(...) error
• func DecryptStreamAuth3x128Cfg(cfg *Config, ...) error
• func DecryptStreamAuth3x256(...) error
• func DecryptStreamAuth3x256Cfg(cfg *Config, ...) error
• func DecryptStreamAuth3x512(...) error
• func DecryptStreamAuth3x512Cfg(cfg *Config, ...) error
• func DecryptStreamAuth128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, macFunc MACFunc, ...) error
• func DecryptStreamAuth128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, ...) error
• func DecryptStreamAuth256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, macFunc MACFunc, ...) error
• func DecryptStreamAuth256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, ...) error
• func DecryptStreamAuth512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, macFunc MACFunc, ...) error
• func DecryptStreamAuth512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, ...) error
• func DecryptStreamAuthenticated3x128(...) ([]byte, bool, error)
• func DecryptStreamAuthenticated3x128Cfg(cfg *Config, ...) ([]byte, bool, error)
• func DecryptStreamAuthenticated3x256(...) ([]byte, bool, error)
• func DecryptStreamAuthenticated3x256Cfg(cfg *Config, ...) ([]byte, bool, error)
• func DecryptStreamAuthenticated3x512(...) ([]byte, bool, error)
• func DecryptStreamAuthenticated3x512Cfg(cfg *Config, ...) ([]byte, bool, error)
• func DecryptStreamAuthenticated128(noiseSeed, dataSeed, startSeed *Seed128, chunkData []byte, macFunc MACFunc, ...) ([]byte, bool, error)
• func DecryptStreamAuthenticated128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, chunkData []byte, ...) ([]byte, bool, error)
• func DecryptStreamAuthenticated256(noiseSeed, dataSeed, startSeed *Seed256, chunkData []byte, macFunc MACFunc, ...) ([]byte, bool, error)
• func DecryptStreamAuthenticated256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, chunkData []byte, ...) ([]byte, bool, error)
• func DecryptStreamAuthenticated512(noiseSeed, dataSeed, startSeed *Seed512, chunkData []byte, macFunc MACFunc, ...) ([]byte, bool, error)
• func DecryptStreamAuthenticated512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, chunkData []byte, ...) ([]byte, bool, error)
• func Encrypt(noiseSeed, dataSeed, startSeed any, data []byte) ([]byte, error)
• func Encrypt3x(...) ([]byte, error)
• func Encrypt3x128(...) ([]byte, error)
• func Encrypt3x128Cfg(cfg *Config, ...) ([]byte, error)
• func Encrypt3x256(...) ([]byte, error)
• func Encrypt3x256Cfg(cfg *Config, ...) ([]byte, error)
• func Encrypt3x512(...) ([]byte, error)
• func Encrypt3x512Cfg(cfg *Config, ...) ([]byte, error)
• func Encrypt128(noiseSeed, dataSeed, startSeed *Seed128, data []byte) ([]byte, error)
• func Encrypt128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte) ([]byte, error)
• func Encrypt256(noiseSeed, dataSeed, startSeed *Seed256, data []byte) ([]byte, error)
• func Encrypt256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte) ([]byte, error)
• func Encrypt512(noiseSeed, dataSeed, startSeed *Seed512, data []byte) ([]byte, error)
• func Encrypt512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte) ([]byte, error)
• func EncryptAuth(noiseSeed, dataSeed, startSeed any, data []byte, macFunc MACFunc) ([]byte, error)
• func EncryptAuth3x(...) ([]byte, error)
• func EncryptAuth3x128(...) ([]byte, error)
• func EncryptAuth3x128Cfg(cfg *Config, ...) ([]byte, error)
• func EncryptAuth3x256(...) ([]byte, error)
• func EncryptAuth3x256Cfg(cfg *Config, ...) ([]byte, error)
• func EncryptAuth3x512(...) ([]byte, error)
• func EncryptAuth3x512Cfg(cfg *Config, ...) ([]byte, error)
• func EncryptAuth128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, macFunc MACFunc) ([]byte, error)
• func EncryptAuth128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, ...) ([]byte, error)
• func EncryptAuth256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, macFunc MACFunc) ([]byte, error)
• func EncryptAuth256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, ...) ([]byte, error)
• func EncryptAuth512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, macFunc MACFunc) ([]byte, error)
• func EncryptAuth512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, ...) ([]byte, error)
• func EncryptAuthenticated3x128(...) ([]byte, error)
• func EncryptAuthenticated3x128Cfg(cfg *Config, ...) ([]byte, error)
• func EncryptAuthenticated3x256(...) ([]byte, error)
• func EncryptAuthenticated3x256Cfg(cfg *Config, ...) ([]byte, error)
• func EncryptAuthenticated3x512(...) ([]byte, error)
• func EncryptAuthenticated3x512Cfg(cfg *Config, ...) ([]byte, error)
• func EncryptAuthenticated128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, macFunc MACFunc) ([]byte, error)
• func EncryptAuthenticated128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, ...) ([]byte, error)
• func EncryptAuthenticated256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, macFunc MACFunc) ([]byte, error)
• func EncryptAuthenticated256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, ...) ([]byte, error)
• func EncryptAuthenticated512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, macFunc MACFunc) ([]byte, error)
• func EncryptAuthenticated512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, ...) ([]byte, error)
• func EncryptStream(noiseSeed, dataSeed, startSeed any, src io.Reader, dst io.Writer, ...) error
• func EncryptStream3x(...) error
• func EncryptStream3x128(...) error
• func EncryptStream3x128Cfg(cfg *Config, ...) error
• func EncryptStream3x256(...) error
• func EncryptStream3x256Cfg(cfg *Config, ...) error
• func EncryptStream3x512(...) error
• func EncryptStream3x512Cfg(cfg *Config, ...) error
• func EncryptStream128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, chunkSize int, ...) error
• func EncryptStream128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, ...) error
• func EncryptStream256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, chunkSize int, ...) error
• func EncryptStream256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, ...) error
• func EncryptStream512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, chunkSize int, ...) error
• func EncryptStream512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, ...) error
• func EncryptStreamAuth(noiseSeed, dataSeed, startSeed any, src io.Reader, dst io.Writer, mac MACFunc, ...) error
• func EncryptStreamAuth3x(...) error
• func EncryptStreamAuth3x128(...) error
• func EncryptStreamAuth3x128Cfg(cfg *Config, ...) error
• func EncryptStreamAuth3x256(...) error
• func EncryptStreamAuth3x256Cfg(cfg *Config, ...) error
• func EncryptStreamAuth3x512(...) error
• func EncryptStreamAuth3x512Cfg(cfg *Config, ...) error
• func EncryptStreamAuth128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, chunkSize int, ...) error
• func EncryptStreamAuth128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, ...) error
• func EncryptStreamAuth256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, chunkSize int, ...) error
• func EncryptStreamAuth256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, ...) error
• func EncryptStreamAuth512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, chunkSize int, ...) error
• func EncryptStreamAuth512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, ...) error
• func EncryptStreamAuthenticated3x128(...) ([]byte, error)
• func EncryptStreamAuthenticated3x128Cfg(cfg *Config, ...) ([]byte, error)
• func EncryptStreamAuthenticated3x256(...) ([]byte, error)
• func EncryptStreamAuthenticated3x256Cfg(cfg *Config, ...) ([]byte, error)
• func EncryptStreamAuthenticated3x512(...) ([]byte, error)
• func EncryptStreamAuthenticated3x512Cfg(cfg *Config, ...) ([]byte, error)
• func EncryptStreamAuthenticated128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, macFunc MACFunc, ...) ([]byte, error)
• func EncryptStreamAuthenticated128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, ...) ([]byte, error)
• func EncryptStreamAuthenticated256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, macFunc MACFunc, ...) ([]byte, error)
• func EncryptStreamAuthenticated256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, ...) ([]byte, error)
• func EncryptStreamAuthenticated512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, macFunc MACFunc, ...) ([]byte, error)
• func EncryptStreamAuthenticated512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, ...) ([]byte, error)
• func GetBarrierFill() int
• func GetBitSoup() int32
• func GetLockSeed() int32
• func GetLockSoup() int32
• func GetMaxWorkers() int
• func GetNonceBits() int
• func MakeAreionSoEM256Hash(key ...[32]byte) (HashFunc256, BatchHashFunc256, [32]byte)
• func MakeAreionSoEM256HashWithKey(fixedKey [32]byte) (HashFunc256, BatchHashFunc256)
• func MakeAreionSoEM512Hash(key ...[64]byte) (HashFunc512, BatchHashFunc512, [64]byte)
• func MakeAreionSoEM512HashWithKey(fixedKey [64]byte) (HashFunc512, BatchHashFunc512)
• func ParseChunkLen(data []byte) (int, error)
• func ParseChunkLenCfg(cfg *Config, data []byte) (int, error)
• func SetBarrierFill(n int)
• func SetBitSoup(mode int32)
• func SetGCPercent(pct int) int
• func SetLockSeed(n int)
• func SetLockSoup(mode int32)
• func SetMaxWorkers(n int)
• func SetMemoryLimit(limit int64) int64
• func SetNonceBits(n int)
• type BatchHashFunc128
• type BatchHashFunc256
• type BatchHashFunc512
• type Blob128
  • func (b *Blob128) Export(keyN, keyD, keyS []byte, ns, ds, ss *Seed128, opts ...Blob128Opts) ([]byte, error)
  • func (b *Blob128) Export3(keyN []byte, keyD1, keyD2, keyD3 []byte, keyS1, keyS2, keyS3 []byte, ...) ([]byte, error)
  • func (b *Blob128) Import(data []byte) error
  • func (b *Blob128) Import3(data []byte) error
• type Blob128Opts
• type Blob256
  • func (b *Blob256) Export(keyN, keyD, keyS [32]byte, ns, ds, ss *Seed256, opts ...Blob256Opts) ([]byte, error)
  • func (b *Blob256) Export3(keyN [32]byte, keyD1, keyD2, keyD3 [32]byte, keyS1, keyS2, keyS3 [32]byte, ...) ([]byte, error)
  • func (b *Blob256) Import(data []byte) error
  • func (b *Blob256) Import3(data []byte) error
• type Blob256Opts
• type Blob512
  • func (b *Blob512) Export(keyN, keyD, keyS [64]byte, ns, ds, ss *Seed512, opts ...Blob512Opts) ([]byte, error)
  • func (b *Blob512) Export3(keyN [64]byte, keyD1, keyD2, keyD3 [64]byte, keyS1, keyS2, keyS3 [64]byte, ...) ([]byte, error)
  • func (b *Blob512) Import(data []byte) error
  • func (b *Blob512) Import3(data []byte) error
• type Blob512Opts
• type Config
  • func SnapshotGlobals() *Config
• type HashFunc128
• type HashFunc256
• type HashFunc512
• type MACFunc
• type Seed128
  • func NewSeed128(bits int, hashFunc HashFunc128) (*Seed128, error)
  • func SeedFromComponents128(hashFunc HashFunc128, components ...uint64) (*Seed128, error)
  • func (s *Seed128) AttachLockSeed(ls *Seed128)
  • func (s *Seed128) AttachedLockSeed() *Seed128
  • func (s *Seed128) BatchChainHash128(buf *[4][]byte) [4][2]uint64
  • func (s *Seed128) Bits() int
  • func (s *Seed128) ChainHash128(buf []byte) (uint64, uint64)
  • func (s *Seed128) DetachLockSeed()
  • func (s *Seed128) MinPixels() int
  • func (s *Seed128) MinPixelsAuth() int
  • func (s *Seed128) MinSide() int
• type Seed256
  • func NewSeed256(bits int, hashFunc HashFunc256) (*Seed256, error)
  • func SeedFromComponents256(hashFunc HashFunc256, components ...uint64) (*Seed256, error)
  • func (s *Seed256) AttachLockSeed(ls *Seed256)
  • func (s *Seed256) AttachedLockSeed() *Seed256
  • func (s *Seed256) BatchChainHash256(buf *[4][]byte) [4][4]uint64
  • func (s *Seed256) Bits() int
  • func (s *Seed256) ChainHash256(buf []byte) [4]uint64
  • func (s *Seed256) DetachLockSeed()
  • func (s *Seed256) MinPixels() int
  • func (s *Seed256) MinPixelsAuth() int
  • func (s *Seed256) MinSide() int
• type Seed512
  • func NewSeed512(bits int, hashFunc HashFunc512) (*Seed512, error)
  • func SeedFromComponents512(hashFunc HashFunc512, components ...uint64) (*Seed512, error)
  • func (s *Seed512) AttachLockSeed(ls *Seed512)
  • func (s *Seed512) AttachedLockSeed() *Seed512
  • func (s *Seed512) BatchChainHash512(buf *[4][]byte) [4][8]uint64
  • func (s *Seed512) Bits() int
  • func (s *Seed512) ChainHash512(buf []byte) [8]uint64
  • func (s *Seed512) DetachLockSeed()
  • func (s *Seed512) MinPixels() int
  • func (s *Seed512) MinPixelsAuth() int
  • func (s *Seed512) MinSide() int

Constants

const (
	// Channels is the number of channels per pixel (RGBWYOPA:
	// Red, Green, Blue, White, Yellow, Orange, Purple, Alpha).
	// 8 channels ensures DataBitsPerPixel (56) is byte-aligned,
	// enabling race-free parallel decode.
	Channels = 8

	// DataBitsPerChannel is the data bits per channel.
	// Each 8-bit channel carries 7 data bits and 1 noise bit.
	DataBitsPerChannel = 7

	// DataBitsPerPixel is the total data bits per pixel.
	DataBitsPerPixel = Channels * DataBitsPerChannel // 56

	// NoisePosRange is the number of possible noise bit positions (0-7).
	NoisePosRange = 8

	// NoisePosConfigBits is the config bits for noise position selection.
	NoisePosConfigBits = 3 // ceil(log2(NoisePosRange))

	// DataRotationBits is the config bits for data rotation within non-noise positions.
	DataRotationBits = 3 // ceil(log2(7)) — rotation 0-6 within 7 data positions

	// NoiseConfigBits is the config bits from the noise seed per pixel.
	NoiseConfigBits = NoisePosConfigBits // 3 — noise position only

	// DataConfigBits is the config bits from the data seed per pixel.
	DataConfigBits = DataRotationBits + DataBitsPerPixel // 59 — rotation + per-bit XOR
)

const DefaultChunkSize = 16 << 20

DefaultChunkSize is the default chunk size for streaming encryption (16 MB).

const MaxKeyBits = 2048

MaxKeyBits is the maximum supported key size in bits. Effective security depends on hash function's internal state width.

const NonceSize = 16

NonceSize is the default per-message nonce size in bytes (128 bits). Use SetNonceBits to change. Birthday collision at ~2^(nonceBits/2) messages.

Variables

var ErrBlobMalformed = errors.New("itb: blob malformed")

ErrBlobMalformed is returned when the JSON blob fails to parse or carries fields outside the documented shape (zero-length components, bad hex / decimal encoding, key_bits inconsistent with components length, etc.).

var ErrBlobModeMismatch = errors.New("itb: blob mode mismatch (Single Import on Triple blob, or vice versa)")

ErrBlobModeMismatch is returned by Blob128.Import / Blob256.Import / Blob512.Import when the blob carries mode=3 (Triple) and from Import3 when the blob carries mode=1 (Single). Caller picks the matching method; no automatic dispatch.

var ErrBlobTooManyOpts = errors.New("itb: Export accepts at most one options struct")

ErrBlobTooManyOpts is returned by Export / Export3 when more than one Blob128Opts / Blob256Opts / Blob512Opts is supplied to the trailing variadic position. Zero or one is accepted.

var ErrBlobVersionTooNew = errors.New("itb: blob version too new")

ErrBlobVersionTooNew is returned when the blob's "v" field is greater than the highest version this build understands.

var ErrLockSeedAfterEncrypt = errors.New("itb: AttachLockSeed: cannot attach lockSeed after first Encrypt")

ErrLockSeedAfterEncrypt is the panic value raised by Seed128.AttachLockSeed / Seed256.AttachLockSeed / Seed512.AttachLockSeed when AttachLockSeed is invoked on a noiseSeed that has already been used in a successful Encrypt path. Switching the dedicated lockSeed mid-session would break decryptability of pre-switch ciphertext; the guard rejects the switch loudly so callers correct the call ordering rather than shipping silently-wrong ciphertext.

var ErrLockSeedComponentAliasing = errors.New("itb: AttachLockSeed: noiseSeed and lockSeed share the same Components backing array")

ErrLockSeedComponentAliasing is the panic value raised by Seed128.AttachLockSeed / Seed256.AttachLockSeed / Seed512.AttachLockSeed when the noiseSeed and lockSeed share the same Components backing array. Aliased Components carry identical uint64 values, again defeating the entropy-isolation purpose; the guard catches the case where a caller built lockSeed by copying noiseSeed and then re-pointed lockSeed.Components at noiseSeed's slice.

var ErrLockSeedOverlayOff = errors.New("itb: AttachedLockSeed installed but neither BitSoup nor LockSoup overlay is engaged")

ErrLockSeedOverlayOff is the panic value raised by the bit- permutation PRF builders ([buildPermutePRF128] / [buildPermutePRF256] / [buildPermutePRF512] for Single Ouroboros, [buildLockPRF128] / [buildLockPRF256] / [buildLockPRF512] for Triple Ouroboros, plus the matching Cfg-suffixed variants) when the noiseSeed carries an attached dedicated lockSeed but neither the bit-soup nor the lock-soup overlay is engaged on the active dispatch path. The dedicated lockSeed has no observable effect on the wire output without one of the overlays — derivation is consulted only inside [splitForSingle] / [splitForTriple] / their Cfg counterparts, both of which short-circuit to an unchanged-data pass-through when both flags are off. Silently producing byte-level ciphertext while the caller has explicitly attached a dedicated lockSeed is an action- at-a-distance bug; the guard panics so callers either turn on the overlay (via SetLockSoup / SetBitSoup for the legacy path, per-encryptor cfg.LockSoup / cfg.BitSoup for the Cfg path, or github.com/everanium/itb/easy.Encryptor.SetLockSeed for the high-level surface which auto-couples both overlays) or remove the AttachLockSeed call.

On-encrypt rather than on-attach: the guard fires every time a build-PRF function is invoked, so it catches the misuse regardless of call ordering — attach before SetLockSoup, attach after, or SetLockSoup(0) toggled between attach and Encrypt all surface as the same panic at the same point in the pipeline.

var ErrLockSeedSelfAttach = errors.New("itb: AttachLockSeed: cannot attach a seed to itself")

ErrLockSeedSelfAttach is the panic value raised by Seed128.AttachLockSeed / Seed256.AttachLockSeed / Seed512.AttachLockSeed when the receiver noiseSeed pointer is identical to the lockSeed argument. Self-attach would defeat the entire entropy-isolation purpose of the dedicated lockSeed (bit-permutation derivation would still consume noiseSeed material) and is rejected loudly rather than silently degraded.

var ErrMACFailure = errors.New("itb: MAC verification failed (tampered or wrong key)")

ErrMACFailure is returned by every authenticated-decrypt entry point (DecryptAuthenticated128 / DecryptAuthenticated256 / DecryptAuthenticated512 and the Triple-Ouroboros mirrors DecryptAuthenticated3x128 / DecryptAuthenticated3x256 / DecryptAuthenticated3x512) when the embedded MAC tag does not match the recomputed tag over the recovered plaintext.

The sentinel value lets capi / FFI layers detect the integrity failure with errors.Is rather than substring-matching the error message, which would silently regress if the message was ever rewritten. The C ABI maps this to `cmd/cshared/internal/capi.StatusMACFailure`.

Authenticated-decrypt errors that are NOT MAC failures (decode errors, malformed container, key-mismatch garbage that survives MAC because the receiver wired the wrong MAC closure but happened to verify against the same tag space) surface through distinct error paths and do not wrap this sentinel.

var ErrStreamAfterFinal = fmt.Errorf("itb: Streaming AEAD chunk after terminator")

ErrStreamAfterFinal is returned when DecryptStreamAuthenticated* observes additional chunk bytes after a chunk whose recovered finalFlag equals 0xFF. The transcript carries trailing data after the terminator; the encoder helper would not produce this layout.

var ErrStreamTruncated = fmt.Errorf("itb: Streaming AEAD transcript truncated before terminator")

ErrStreamTruncated is returned when DecryptStreamAuthenticated* exhausts its input without observing a chunk whose recovered finalFlag equals 0xFF. The transcript has been truncated at or before the terminating chunk; no plaintext after the last successfully verified chunk is trustworthy.

Functions

func AreionSoEM256x4

func AreionSoEM256x4(keys *[4][64]byte, inputs *[4][32]byte) [4][32]byte

AreionSoEM256x4 evaluates the Areion-SoEM-256 PRF on four independent (key, input) tuples in parallel.

output[i] = aes.AreionSoEM256(&keys[i], &inputs[i])  for i in {0,1,2,3}

Each `keys[i]` is 64 bytes (two 32-byte SoEM subkeys k1‖k2). Each `inputs[i]` is 32 bytes. The result is four independent 32-byte PRF outputs.

The function is `crypto/rand`-equivalent in security to four serial `aes.AreionSoEM256` calls — output is bit-exact identical (verified in `TestAreionSoEM256x4Parity`). Throughput is faster on x86_64 with VAES (AVX-512) because the four lanes share VAES instruction issue; on hardware without VAES the function falls back to per-lane AES-NI at near-identical cost to four serial calls.

func AreionSoEM512x4

func AreionSoEM512x4(keys *[4][128]byte, inputs *[4][64]byte) [4][64]byte

AreionSoEM512x4 evaluates the Areion-SoEM-512 PRF on four independent (key, input) tuples in parallel.

output[i] = aes.AreionSoEM512(&keys[i], &inputs[i])  for i in {0,1,2,3}

Each `keys[i]` is 128 bytes (two 64-byte SoEM subkeys k1‖k2). Each `inputs[i]` is 64 bytes. The result is four independent 64-byte PRF outputs. Bit-exact parity invariant identical to the SoEM-256 case; see `TestAreionSoEM512x4Parity`.

func ChunkSize

func ChunkSize(dataLen int) int

ChunkSize returns an appropriate chunk size for the given total data length. For small data (≤16 MB): encrypts in a single chunk. For medium data (≤256 MB): uses 16 MB chunks. For large data (>256 MB): uses 64 MB chunks.

func Decrypt

func Decrypt(noiseSeed, dataSeed, startSeed any, fileData []byte) ([]byte, error)

Decrypt is the width-less Single Message plain Decrypt entry point. Mirrors Encrypt; dispatches to Decrypt128 / Decrypt256 / Decrypt512.

func Decrypt3x

func Decrypt3x(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 any, fileData []byte) ([]byte, error)

Decrypt3x is the width-less Single Message Triple-Ouroboros Decrypt entry point. Mirrors Encrypt3x; dispatches to Decrypt3x128 / Decrypt3x256 / Decrypt3x512.

func Decrypt3x128

func Decrypt3x128(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, fileData []byte) ([]byte, error)

Decrypt3x128 decrypts data encrypted by Encrypt3x128 (Triple Ouroboros, 128-bit variant).

func Decrypt3x128Cfg

func Decrypt3x128Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, fileData []byte) ([]byte, error)

Decrypt3x128Cfg is the Cfg variant of Decrypt3x128.

func Decrypt3x256

func Decrypt3x256(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, fileData []byte) ([]byte, error)

Decrypt3x256 decrypts data encrypted by Encrypt3x256 (Triple Ouroboros, 256-bit variant).

func Decrypt3x256Cfg

func Decrypt3x256Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, fileData []byte) ([]byte, error)

Decrypt3x256Cfg is the Cfg variant of Decrypt3x256.

func Decrypt3x512

func Decrypt3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, fileData []byte) ([]byte, error)

Decrypt3x512 decrypts data encrypted by Encrypt3x512 (Triple Ouroboros, 512-bit variant).

func Decrypt3x512Cfg

func Decrypt3x512Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, fileData []byte) ([]byte, error)

Decrypt3x512Cfg is the Cfg variant of Decrypt3x512.

func Decrypt128

func Decrypt128(noiseSeed, dataSeed, startSeed *Seed128, fileData []byte) ([]byte, error)

Decrypt128 extracts data hidden by Encrypt128 using 128-bit seeds.

Parses [nonce][width][height][RGBWYOPA] format, applies the reverse extraction with triple-seed decryption, and COBS-decodes the result.

Errors only on structural issues (header parsing, dimension validation). Wrong seeds produce random-looking output, never error — non-Auth mode has no failure signal by design.

func Decrypt128Cfg

func Decrypt128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, fileData []byte) ([]byte, error)

Decrypt128Cfg is the Cfg variant of Decrypt128: threads cfg through currentNonceSizeCfg, headerSizeCfg, process128Cfg, the PRF builder, and interleaveForSingleCfg. Body otherwise identical to Decrypt128, including the constant-iteration null search and the plausible-decryption invariant — never errors on wrong-seed input, only on structural header / dimension issues.

func Decrypt256

func Decrypt256(noiseSeed, dataSeed, startSeed *Seed256, fileData []byte) ([]byte, error)

Decrypt256 extracts data hidden by Encrypt256 using 256-bit seeds.

Parses [nonce][width][height][RGBWYOPA] format, applies the reverse extraction with triple-seed decryption, and COBS-decodes the result.

Errors only on structural issues (header parsing, dimension validation). Wrong seeds produce random-looking output, never error — non-Auth mode has no failure signal by design.

func Decrypt256Cfg

func Decrypt256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, fileData []byte) ([]byte, error)

Decrypt256Cfg is the Cfg variant of Decrypt256: threads cfg through currentNonceSizeCfg, headerSizeCfg, process256Cfg, the PRF builder, and interleaveForSingleCfg. Body otherwise identical to Decrypt256, including the constant-iteration null search and the plausible-decryption invariant — never errors on wrong-seed input, only on structural header / dimension issues.

func Decrypt512

func Decrypt512(noiseSeed, dataSeed, startSeed *Seed512, fileData []byte) ([]byte, error)

Decrypt512 extracts data hidden by Encrypt512 using 512-bit seeds.

Parses [nonce][width][height][RGBWYOPA] format, applies the reverse extraction with triple-seed decryption, and COBS-decodes the result.

Errors only on structural issues (header parsing, dimension validation). Wrong seeds produce random-looking output, never error — non-Auth mode has no failure signal by design.

func Decrypt512Cfg

func Decrypt512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, fileData []byte) ([]byte, error)

Decrypt512Cfg is the Cfg variant of Decrypt512: threads cfg through currentNonceSizeCfg, headerSizeCfg, process512Cfg, the PRF builder, and interleaveForSingleCfg. Body otherwise identical to Decrypt512, including the constant-iteration null search and the plausible-decryption invariant — never errors on wrong-seed input, only on structural header / dimension issues.

func DecryptAuth

func DecryptAuth(noiseSeed, dataSeed, startSeed any, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth is the width-less Single Message authenticated Decrypt entry point. Mirrors EncryptAuth; dispatches to DecryptAuthenticated128 / DecryptAuthenticated256 / DecryptAuthenticated512.

func DecryptAuth3x

func DecryptAuth3x(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 any, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth3x is the width-less Single Message Triple-Ouroboros authenticated Decrypt entry point. Mirrors EncryptAuth3x; dispatches to DecryptAuthenticated3x128 / DecryptAuthenticated3x256 / DecryptAuthenticated3x512.

func DecryptAuth3x128

func DecryptAuth3x128(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth3x128 is an alias for DecryptAuthenticated3x128.

func DecryptAuth3x128Cfg

func DecryptAuth3x128Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth3x128Cfg is an alias for DecryptAuthenticated3x128Cfg.

func DecryptAuth3x256

func DecryptAuth3x256(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth3x256 is an alias for DecryptAuthenticated3x256.

func DecryptAuth3x256Cfg

func DecryptAuth3x256Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth3x256Cfg is an alias for DecryptAuthenticated3x256Cfg.

func DecryptAuth3x512

func DecryptAuth3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth3x512 is an alias for DecryptAuthenticated3x512.

func DecryptAuth3x512Cfg

func DecryptAuth3x512Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth3x512Cfg is an alias for DecryptAuthenticated3x512Cfg.

func DecryptAuth128

func DecryptAuth128(noiseSeed, dataSeed, startSeed *Seed128, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth128 is an alias for DecryptAuthenticated128.

func DecryptAuth128Cfg

func DecryptAuth128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth128Cfg is an alias for DecryptAuthenticated128Cfg.

func DecryptAuth256

func DecryptAuth256(noiseSeed, dataSeed, startSeed *Seed256, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth256 is an alias for DecryptAuthenticated256.

func DecryptAuth256Cfg

func DecryptAuth256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth256Cfg is an alias for DecryptAuthenticated256Cfg.

func DecryptAuth512

func DecryptAuth512(noiseSeed, dataSeed, startSeed *Seed512, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth512 is an alias for DecryptAuthenticated512.

func DecryptAuth512Cfg

func DecryptAuth512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuth512Cfg is an alias for DecryptAuthenticated512Cfg.

func DecryptAuthenticated3x128

func DecryptAuthenticated3x128(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuthenticated3x128 decrypts and verifies integrity using Triple Ouroboros (128-bit variant).

func DecryptAuthenticated3x128Cfg

func DecryptAuthenticated3x128Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuthenticated3x128Cfg is the Cfg variant of DecryptAuthenticated3x128.

func DecryptAuthenticated3x256

func DecryptAuthenticated3x256(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuthenticated3x256 decrypts and verifies integrity using Triple Ouroboros (256-bit variant).

func DecryptAuthenticated3x256Cfg

func DecryptAuthenticated3x256Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuthenticated3x256Cfg is the Cfg variant of DecryptAuthenticated3x256.

func DecryptAuthenticated3x512

func DecryptAuthenticated3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuthenticated3x512 decrypts and verifies integrity using Triple Ouroboros (512-bit variant).

func DecryptAuthenticated3x512Cfg

func DecryptAuthenticated3x512Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuthenticated3x512Cfg is the Cfg variant of DecryptAuthenticated3x512.

func DecryptAuthenticated128

func DecryptAuthenticated128(noiseSeed, dataSeed, startSeed *Seed128, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuthenticated128 decrypts and verifies integrity using 128-bit hash.

func DecryptAuthenticated128Cfg

func DecryptAuthenticated128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuthenticated128Cfg is the Cfg variant of DecryptAuthenticated128.

func DecryptAuthenticated256

func DecryptAuthenticated256(noiseSeed, dataSeed, startSeed *Seed256, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuthenticated256 decrypts and verifies integrity using 256-bit hash.

func DecryptAuthenticated256Cfg

func DecryptAuthenticated256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuthenticated256Cfg is the Cfg variant of DecryptAuthenticated256.

func DecryptAuthenticated512

func DecryptAuthenticated512(noiseSeed, dataSeed, startSeed *Seed512, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuthenticated512 decrypts and verifies integrity using 512-bit hash.

func DecryptAuthenticated512Cfg

func DecryptAuthenticated512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, fileData []byte, macFunc MACFunc) ([]byte, error)

DecryptAuthenticated512Cfg is the Cfg variant of DecryptAuthenticated512.

func DecryptStream

func DecryptStream(noiseSeed, dataSeed, startSeed any, src io.Reader, dst io.Writer) error

DecryptStream is the width-less plain-stream Decrypt entry point. Walks src one chunk at a time using the on-wire header to recover each chunk's extent, decrypts the chunk via the matching width-suffixed Single Message path, and writes the recovered plaintext to dst.

func DecryptStream3x

func DecryptStream3x(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 any, src io.Reader, dst io.Writer) error

DecryptStream3x is the width-less Triple-Ouroboros plain-stream Decrypt entry point.

func DecryptStream3x128

func DecryptStream3x128(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, emit func(chunk []byte) error) error

DecryptStream3x128 decrypts concatenated chunks produced by EncryptStream3x128.

func DecryptStream3x128Cfg

func DecryptStream3x128Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, emit func(chunk []byte) error) error

DecryptStream3x128Cfg is the Cfg variant of DecryptStream3x128.

func DecryptStream3x256

func DecryptStream3x256(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, emit func(chunk []byte) error) error

DecryptStream3x256 decrypts concatenated chunks produced by EncryptStream3x256.

func DecryptStream3x256Cfg

func DecryptStream3x256Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, emit func(chunk []byte) error) error

DecryptStream3x256Cfg is the Cfg variant of DecryptStream3x256.

func DecryptStream3x512

func DecryptStream3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, emit func(chunk []byte) error) error

DecryptStream3x512 decrypts concatenated chunks produced by EncryptStream3x512.

func DecryptStream3x512Cfg

func DecryptStream3x512Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, emit func(chunk []byte) error) error

DecryptStream3x512Cfg is the Cfg variant of DecryptStream3x512.

func DecryptStream128

func DecryptStream128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, emit func(chunk []byte) error) error

DecryptStream128 decrypts concatenated chunks produced by EncryptStream128.

func DecryptStream128Cfg

func DecryptStream128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, emit func(chunk []byte) error) error

DecryptStream128Cfg is the Cfg variant of DecryptStream128.

func DecryptStream256

func DecryptStream256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, emit func(chunk []byte) error) error

DecryptStream256 decrypts concatenated chunks produced by EncryptStream256.

func DecryptStream256Cfg

func DecryptStream256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, emit func(chunk []byte) error) error

DecryptStream256Cfg is the Cfg variant of DecryptStream256.

func DecryptStream512

func DecryptStream512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, emit func(chunk []byte) error) error

DecryptStream512 decrypts concatenated chunks produced by EncryptStream512.

func DecryptStream512Cfg

func DecryptStream512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, emit func(chunk []byte) error) error

DecryptStream512Cfg is the Cfg variant of DecryptStream512.

func DecryptStreamAuth

func DecryptStreamAuth(noiseSeed, dataSeed, startSeed any, src io.Reader, dst io.Writer, mac MACFunc) error

DecryptStreamAuth is the width-less single-Ouroboros Streaming AEAD Decrypt entry point. Reads the 32-byte streamID prefix, walks the remaining bytes one chunk at a time, dispatches each chunk through the matching Single Message DecryptStreamAuthenticated* path with the running cumulative pixel offset, and writes recovered plaintext to dst. Returns ErrStreamTruncated when the transcript exhausts without a terminating chunk and ErrStreamAfterFinal when chunks follow a terminator-flagged chunk.

func DecryptStreamAuth3x

func DecryptStreamAuth3x(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 any, src io.Reader, dst io.Writer, mac MACFunc) error

DecryptStreamAuth3x is the width-less Triple-Ouroboros Streaming AEAD Decrypt entry point.

func DecryptStreamAuth3x128

func DecryptStreamAuth3x128(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, macFunc MACFunc, emit func(chunk []byte) error) error

DecryptStreamAuth3x128 mirrors DecryptStreamAuth128 for Triple Ouroboros (7-seed) at 128-bit hash width.

func DecryptStreamAuth3x128Cfg

func DecryptStreamAuth3x128Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, macFunc MACFunc, emit func(chunk []byte) error) error

DecryptStreamAuth3x128Cfg is the Cfg variant of DecryptStreamAuth3x128.

func DecryptStreamAuth3x256

func DecryptStreamAuth3x256(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, macFunc MACFunc, emit func(chunk []byte) error) error

DecryptStreamAuth3x256 mirrors DecryptStreamAuth128 for Triple Ouroboros (7-seed) at 256-bit hash width.

func DecryptStreamAuth3x256Cfg

func DecryptStreamAuth3x256Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, macFunc MACFunc, emit func(chunk []byte) error) error

DecryptStreamAuth3x256Cfg is the Cfg variant of DecryptStreamAuth3x256.

func DecryptStreamAuth3x512

func DecryptStreamAuth3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, macFunc MACFunc, emit func(chunk []byte) error) error

DecryptStreamAuth3x512 mirrors DecryptStreamAuth128 for Triple Ouroboros (7-seed) at 512-bit hash width.

func DecryptStreamAuth3x512Cfg

func DecryptStreamAuth3x512Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, macFunc MACFunc, emit func(chunk []byte) error) error

DecryptStreamAuth3x512Cfg is the Cfg variant of DecryptStreamAuth3x512.

func DecryptStreamAuth128

func DecryptStreamAuth128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, macFunc MACFunc, emit func(chunk []byte) error) error

DecryptStreamAuth128 is the wide-stream entry point for Streaming AEAD using 128-bit hash seeds. Reads the leading 32-byte stream anchor from data, walks the remaining bytes through ParseChunkLen one chunk at a time, calls DecryptStreamAuthenticated128 per chunk with the cumulative pixel offset, and emits each recovered plaintext through the supplied emit callback. Returns ErrStreamTruncated when the transcript exhausts without observing a chunk whose finalFlag is true, and ErrStreamAfterFinal when additional chunk bytes follow the terminator.

func DecryptStreamAuth128Cfg

func DecryptStreamAuth128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, macFunc MACFunc, emit func(chunk []byte) error) error

DecryptStreamAuth128Cfg is the Cfg variant of DecryptStreamAuth128.

func DecryptStreamAuth256

func DecryptStreamAuth256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, macFunc MACFunc, emit func(chunk []byte) error) error

DecryptStreamAuth256 mirrors DecryptStreamAuth128 for 256-bit hash seeds.

func DecryptStreamAuth256Cfg

func DecryptStreamAuth256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, macFunc MACFunc, emit func(chunk []byte) error) error

DecryptStreamAuth256Cfg is the Cfg variant of DecryptStreamAuth256.

func DecryptStreamAuth512

func DecryptStreamAuth512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, macFunc MACFunc, emit func(chunk []byte) error) error

DecryptStreamAuth512 mirrors DecryptStreamAuth128 for 512-bit hash seeds.

func DecryptStreamAuth512Cfg

func DecryptStreamAuth512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, macFunc MACFunc, emit func(chunk []byte) error) error

DecryptStreamAuth512Cfg is the Cfg variant of DecryptStreamAuth512.

func DecryptStreamAuthenticated3x128

func DecryptStreamAuthenticated3x128(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, chunkData []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64) ([]byte, bool, error)

DecryptStreamAuthenticated3x128 decrypts and verifies a single Streaming AEAD chunk using Triple Ouroboros (128-bit variant). Returns the recovered plaintext, the recovered finalFlag, and any error from the cipher / MAC layer.

func DecryptStreamAuthenticated3x128Cfg

func DecryptStreamAuthenticated3x128Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, chunkData []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64) ([]byte, bool, error)

DecryptStreamAuthenticated3x128Cfg is the Cfg variant of DecryptStreamAuthenticated3x128.

func DecryptStreamAuthenticated3x256

func DecryptStreamAuthenticated3x256(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, chunkData []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64) ([]byte, bool, error)

DecryptStreamAuthenticated3x256 decrypts and verifies a single Streaming AEAD chunk using Triple Ouroboros (256-bit variant). Returns the recovered plaintext, the recovered finalFlag, and any error from the cipher / MAC layer.

func DecryptStreamAuthenticated3x256Cfg

func DecryptStreamAuthenticated3x256Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, chunkData []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64) ([]byte, bool, error)

DecryptStreamAuthenticated3x256Cfg is the Cfg variant of DecryptStreamAuthenticated3x256.

func DecryptStreamAuthenticated3x512

func DecryptStreamAuthenticated3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, chunkData []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64) ([]byte, bool, error)

DecryptStreamAuthenticated3x512 decrypts and verifies a single Streaming AEAD chunk using Triple Ouroboros (512-bit variant). Returns the recovered plaintext, the recovered finalFlag, and any error from the cipher / MAC layer.

func DecryptStreamAuthenticated3x512Cfg

func DecryptStreamAuthenticated3x512Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, chunkData []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64) ([]byte, bool, error)

DecryptStreamAuthenticated3x512Cfg is the Cfg variant of DecryptStreamAuthenticated3x512.

func DecryptStreamAuthenticated128

func DecryptStreamAuthenticated128(noiseSeed, dataSeed, startSeed *Seed128, chunkData []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64) ([]byte, bool, error)

DecryptStreamAuthenticated128 decrypts and verifies a single Streaming AEAD chunk using 128-bit hash seeds. Returns the recovered plaintext, the recovered finalFlag indicating whether this chunk terminates the stream, and any error from the cipher / MAC layer.

streamID and cumulativePixelOffset must match the encoder's values for chunk i; reorder, replay, or cross-stream splice attempts cause MAC mismatch and return ErrMACFailure. The recovered flag byte is extracted before MAC verification by splitting the decrypted container body at the known offsets.

func DecryptStreamAuthenticated128Cfg

func DecryptStreamAuthenticated128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, chunkData []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64) ([]byte, bool, error)

DecryptStreamAuthenticated128Cfg is the Cfg variant of DecryptStreamAuthenticated128.

func DecryptStreamAuthenticated256

func DecryptStreamAuthenticated256(noiseSeed, dataSeed, startSeed *Seed256, chunkData []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64) ([]byte, bool, error)

DecryptStreamAuthenticated256 decrypts and verifies a single Streaming AEAD chunk using 256-bit hash seeds. Returns the recovered plaintext, the recovered finalFlag indicating whether this chunk terminates the stream, and any error from the cipher / MAC layer.

streamID and cumulativePixelOffset must match the encoder's values for chunk i; reorder, replay, or cross-stream splice attempts cause MAC mismatch and return ErrMACFailure. The recovered flag byte is extracted before MAC verification by splitting the decrypted container body at the known offsets.

func DecryptStreamAuthenticated256Cfg

func DecryptStreamAuthenticated256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, chunkData []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64) ([]byte, bool, error)

DecryptStreamAuthenticated256Cfg is the Cfg variant of DecryptStreamAuthenticated256.

func DecryptStreamAuthenticated512

func DecryptStreamAuthenticated512(noiseSeed, dataSeed, startSeed *Seed512, chunkData []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64) ([]byte, bool, error)

DecryptStreamAuthenticated512 decrypts and verifies a single Streaming AEAD chunk using 512-bit hash seeds. Returns the recovered plaintext, the recovered finalFlag indicating whether this chunk terminates the stream, and any error from the cipher / MAC layer.

streamID and cumulativePixelOffset must match the encoder's values for chunk i; reorder, replay, or cross-stream splice attempts cause MAC mismatch and return ErrMACFailure. The recovered flag byte is extracted before MAC verification by splitting the decrypted container body at the known offsets.

func DecryptStreamAuthenticated512Cfg

func DecryptStreamAuthenticated512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, chunkData []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64) ([]byte, bool, error)

DecryptStreamAuthenticated512Cfg is the Cfg variant of DecryptStreamAuthenticated512.

func Encrypt

func Encrypt(noiseSeed, dataSeed, startSeed any, data []byte) ([]byte, error)

Encrypt is the width-less Single Message plain Encrypt entry point. Dispatches to Encrypt128 / Encrypt256 / Encrypt512 based on the concrete pointer type of the supplied seeds. Every seed must carry the same concrete *SeedN type; mixing widths returns an itb-wrapped error matching the existing low-level error shape.

Accepts seeds typed as any (interface{}) so a single signature covers all three primitive widths. The internal type-switch resolves the width once and forwards verbatim — the helper is allocation-free beyond the dispatch overhead and the underlying width-suffixed call's return slice.

func Encrypt3x

func Encrypt3x(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 any, data []byte) ([]byte, error)

Encrypt3x is the width-less Single Message Triple-Ouroboros Encrypt entry point. Dispatches to Encrypt3x128 / Encrypt3x256 / Encrypt3x512 based on the concrete pointer type of the supplied seeds. All seven seeds must share one concrete *SeedN type; mixing widths returns an itb-wrapped error.

func Encrypt3x128

func Encrypt3x128(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte) ([]byte, error)

Encrypt3x128 encrypts data using Triple Ouroboros with 7 seeds (128-bit variant). Plaintext is split into 3 parts (every 3rd byte), each encrypted into 1/3 of the pixel data with independent dataSeed and startSeed, sharing noiseSeed. Output format is identical to standard ITB: [nonce][W][H][W×H×8 pixels].

func Encrypt3x128Cfg

func Encrypt3x128Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte) ([]byte, error)

Encrypt3x128Cfg is the Cfg variant of Encrypt3x128: threads cfg through every Cfg-aware accessor in the Triple Ouroboros pipeline. Body otherwise identical to Encrypt3x128, including the 3-goroutine COBS-encode / payload-build / CSPRNG-fill / process stages and the per-third buffer-pool discipline.

func Encrypt3x256

func Encrypt3x256(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte) ([]byte, error)

Encrypt3x256 encrypts data using Triple Ouroboros with 7 seeds (256-bit variant). Plaintext is split into 3 parts (every 3rd byte), each encrypted into 1/3 of the pixel data with independent dataSeed and startSeed, sharing noiseSeed. Output format is identical to standard ITB: [nonce][W][H][W×H×8 pixels].

func Encrypt3x256Cfg

func Encrypt3x256Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte) ([]byte, error)

Encrypt3x256Cfg is the Cfg variant of Encrypt3x256: threads cfg through every Cfg-aware accessor in the Triple Ouroboros pipeline. Body otherwise identical to Encrypt3x256, including the 3-goroutine COBS-encode / payload-build / CSPRNG-fill / process stages and the per-third buffer-pool discipline.

func Encrypt3x512

func Encrypt3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte) ([]byte, error)

Encrypt3x512 encrypts data using Triple Ouroboros with 7 seeds (512-bit variant). Plaintext is split into 3 parts (every 3rd byte), each encrypted into 1/3 of the pixel data with independent dataSeed and startSeed, sharing noiseSeed. Output format is identical to standard ITB: [nonce][W][H][W×H×8 pixels].

func Encrypt3x512Cfg

func Encrypt3x512Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte) ([]byte, error)

Encrypt3x512Cfg is the Cfg variant of Encrypt3x512: threads cfg through every Cfg-aware accessor in the Triple Ouroboros pipeline. Body otherwise identical to Encrypt3x512, including the 3-goroutine COBS-encode / payload-build / CSPRNG-fill / process stages and the per-third buffer-pool discipline.

func Encrypt128

func Encrypt128(noiseSeed, dataSeed, startSeed *Seed128, data []byte) ([]byte, error)

Encrypt128 encrypts arbitrary binary data into a raw RGBWYOPA pixel container using 128-bit seeds.

Uses triple-seed architecture with Seed128: noiseSeed controls noise bit placement, dataSeed controls data rotation and XOR masks, startSeed controls pixel start offset. All three seeds are independent — compromise of one does not reveal the others.

Pipeline: data → COBS encode → [0x00 terminator] → embed into crypto/rand RGBWYOPA container with per-bit XOR, data rotation, and dynamic noise position.

Output format: [16-byte nonce][2-byte width BE][2-byte height BE][W×H×8 raw RGBWYOPA].

func Encrypt128Cfg

func Encrypt128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte) ([]byte, error)

Encrypt128Cfg is the Cfg variant of Encrypt128: threads cfg through generateNonceCfg, the PRF builder, splitForSingleCfg, the container- sizing helper, process128Cfg, and headerSizeCfg so per-encryptor NonceBits / BarrierFill / BitSoup / LockSoup / LockSeed overrides are honoured. Body otherwise identical to Encrypt128, including every error-path message and the COBS-plus-null-fill payload layout.

func Encrypt256

func Encrypt256(noiseSeed, dataSeed, startSeed *Seed256, data []byte) ([]byte, error)

Encrypt256 encrypts arbitrary binary data into a raw RGBWYOPA pixel container using 256-bit seeds.

Uses triple-seed architecture with Seed256: noiseSeed controls noise bit placement, dataSeed controls data rotation and XOR masks, startSeed controls pixel start offset. All three seeds are independent — compromise of one does not reveal the others.

Pipeline: data → COBS encode → [0x00 terminator] → embed into crypto/rand RGBWYOPA container with per-bit XOR, data rotation, and dynamic noise position.

Output format: [16-byte nonce][2-byte width BE][2-byte height BE][W×H×8 raw RGBWYOPA].

func Encrypt256Cfg

func Encrypt256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte) ([]byte, error)

Encrypt256Cfg is the Cfg variant of Encrypt256: threads cfg through generateNonceCfg, the PRF builder, splitForSingleCfg, the container- sizing helper, process256Cfg, and headerSizeCfg so per-encryptor NonceBits / BarrierFill / BitSoup / LockSoup / LockSeed overrides are honoured. Body otherwise identical to Encrypt256, including every error-path message and the COBS-plus-null-fill payload layout.

func Encrypt512

func Encrypt512(noiseSeed, dataSeed, startSeed *Seed512, data []byte) ([]byte, error)

Encrypt512 encrypts arbitrary binary data into a raw RGBWYOPA pixel container using 512-bit seeds.

Uses triple-seed architecture with Seed512: noiseSeed controls noise bit placement, dataSeed controls data rotation and XOR masks, startSeed controls pixel start offset. All three seeds are independent — compromise of one does not reveal the others.

Pipeline: data → COBS encode → [0x00 terminator] → embed into crypto/rand RGBWYOPA container with per-bit XOR, data rotation, and dynamic noise position.

Output format: [16-byte nonce][2-byte width BE][2-byte height BE][W×H×8 raw RGBWYOPA].

func Encrypt512Cfg

func Encrypt512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte) ([]byte, error)

Encrypt512Cfg is the Cfg variant of Encrypt512: threads cfg through generateNonceCfg, the PRF builder, splitForSingleCfg, the container- sizing helper, process512Cfg, and headerSizeCfg so per-encryptor NonceBits / BarrierFill / BitSoup / LockSoup / LockSeed overrides are honoured. Body otherwise identical to Encrypt512, including every error-path message and the COBS-plus-null-fill payload layout.

func EncryptAuth

func EncryptAuth(noiseSeed, dataSeed, startSeed any, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth is the width-less Single Message authenticated Encrypt entry point. Dispatches to EncryptAuthenticated128 / EncryptAuthenticated256 / EncryptAuthenticated512 based on the concrete pointer type of the supplied seeds. Every seed must carry the same concrete *SeedN type; mixing widths returns an itb-wrapped error.

Accepts seeds typed as any (interface{}) so a single signature covers all three primitive widths. The internal type-switch resolves the width once and forwards verbatim to the matching width-suffixed implementation; the supplied MACFunc closure is passed through unchanged.

func EncryptAuth3x

func EncryptAuth3x(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 any, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth3x is the width-less Single Message Triple-Ouroboros authenticated Encrypt entry point. Dispatches to EncryptAuthenticated3x128 / EncryptAuthenticated3x256 / EncryptAuthenticated3x512 based on the concrete pointer type of the supplied seeds. All seven seeds must share one concrete *SeedN type; mixing widths returns an itb-wrapped error.

func EncryptAuth3x128

func EncryptAuth3x128(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth3x128 is an alias for EncryptAuthenticated3x128.

func EncryptAuth3x128Cfg

func EncryptAuth3x128Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth3x128Cfg is an alias for EncryptAuthenticated3x128Cfg.

func EncryptAuth3x256

func EncryptAuth3x256(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth3x256 is an alias for EncryptAuthenticated3x256.

func EncryptAuth3x256Cfg

func EncryptAuth3x256Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth3x256Cfg is an alias for EncryptAuthenticated3x256Cfg.

func EncryptAuth3x512

func EncryptAuth3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth3x512 is an alias for EncryptAuthenticated3x512.

func EncryptAuth3x512Cfg

func EncryptAuth3x512Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth3x512Cfg is an alias for EncryptAuthenticated3x512Cfg.

func EncryptAuth128

func EncryptAuth128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth128 is an alias for EncryptAuthenticated128.

func EncryptAuth128Cfg

func EncryptAuth128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth128Cfg is an alias for EncryptAuthenticated128Cfg.

func EncryptAuth256

func EncryptAuth256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth256 is an alias for EncryptAuthenticated256.

func EncryptAuth256Cfg

func EncryptAuth256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth256Cfg is an alias for EncryptAuthenticated256Cfg.

func EncryptAuth512

func EncryptAuth512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth512 is an alias for EncryptAuthenticated512.

func EncryptAuth512Cfg

func EncryptAuth512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuth512Cfg is an alias for EncryptAuthenticated512Cfg.

func EncryptAuthenticated3x128

func EncryptAuthenticated3x128(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuthenticated3x128 encrypts data with integrity using Triple Ouroboros (128-bit variant).

func EncryptAuthenticated3x128Cfg

func EncryptAuthenticated3x128Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuthenticated3x128Cfg is the Cfg variant of EncryptAuthenticated3x128: threads cfg through every Cfg-aware accessor in the Triple Ouroboros authenticated pipeline. Body otherwise identical to EncryptAuthenticated3x128, including the part2-reserves-tag layout and the MAC-over-concatenated-payloads invariant.

func EncryptAuthenticated3x256

func EncryptAuthenticated3x256(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuthenticated3x256 encrypts data with integrity using Triple Ouroboros (256-bit variant).

func EncryptAuthenticated3x256Cfg

func EncryptAuthenticated3x256Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuthenticated3x256Cfg is the Cfg variant of EncryptAuthenticated3x256: threads cfg through every Cfg-aware accessor in the Triple Ouroboros authenticated pipeline. Body otherwise identical to EncryptAuthenticated3x256, including the part2-reserves-tag layout and the MAC-over-concatenated-payloads invariant.

func EncryptAuthenticated3x512

func EncryptAuthenticated3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuthenticated3x512 encrypts data with integrity using Triple Ouroboros (512-bit variant).

func EncryptAuthenticated3x512Cfg

func EncryptAuthenticated3x512Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuthenticated3x512Cfg is the Cfg variant of EncryptAuthenticated3x512: threads cfg through every Cfg-aware accessor in the Triple Ouroboros authenticated pipeline. Body otherwise identical to EncryptAuthenticated3x512, including the part2-reserves-tag layout and the MAC-over-concatenated-payloads invariant.

func EncryptAuthenticated128

func EncryptAuthenticated128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuthenticated128 encrypts data with integrity protection using 128-bit hash.

Pipeline: data → COBS encode → build payload [COBS][0x00][fill] → MAC(payload) → append tag → embed [payload][tag] into container.

The MAC covers the entire payload including fill bytes.

func EncryptAuthenticated128Cfg

func EncryptAuthenticated128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuthenticated128Cfg is the Cfg variant of EncryptAuthenticated128: threads cfg through every Cfg-aware accessor in the Single Ouroboros authenticated pipeline. Body otherwise identical to EncryptAuthenticated128, including the MAC- over-payload-with-fill-bytes layout and the appended-tag wire shape.

func EncryptAuthenticated256

func EncryptAuthenticated256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuthenticated256 encrypts data with integrity protection using 256-bit hash.

Pipeline: data → COBS encode → build payload [COBS][0x00][fill] → MAC(payload) → append tag → embed [payload][tag] into container.

The MAC covers the entire payload including fill bytes.

func EncryptAuthenticated256Cfg

func EncryptAuthenticated256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuthenticated256Cfg is the Cfg variant of EncryptAuthenticated256: threads cfg through every Cfg-aware accessor in the Single Ouroboros authenticated pipeline. Body otherwise identical to EncryptAuthenticated256, including the MAC- over-payload-with-fill-bytes layout and the appended-tag wire shape.

func EncryptAuthenticated512

func EncryptAuthenticated512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuthenticated512 encrypts data with integrity protection using 512-bit hash.

Pipeline: data → COBS encode → build payload [COBS][0x00][fill] → MAC(payload) → append tag → embed [payload][tag] into container.

The MAC covers the entire payload including fill bytes.

func EncryptAuthenticated512Cfg

func EncryptAuthenticated512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, macFunc MACFunc) ([]byte, error)

EncryptAuthenticated512Cfg is the Cfg variant of EncryptAuthenticated512: threads cfg through every Cfg-aware accessor in the Single Ouroboros authenticated pipeline. Body otherwise identical to EncryptAuthenticated512, including the MAC- over-payload-with-fill-bytes layout and the appended-tag wire shape.

func EncryptStream

func EncryptStream(noiseSeed, dataSeed, startSeed any, src io.Reader, dst io.Writer, chunkSize int) error

EncryptStream is the width-less plain-stream Encrypt entry point. Reads from src in up-to-chunkSize-byte windows, encrypts each non-empty window via the matching width-suffixed Single Message path, and writes the resulting wire chunk to dst. Empty src input emits nothing (the Single Message path rejects empty plaintext; the streaming helper preserves that semantic by simply not emitting any chunk).

Dispatches by concrete pointer type of the supplied seeds; mixing widths returns an error matching Encrypt / Decrypt.

func EncryptStream3x

func EncryptStream3x(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 any, src io.Reader, dst io.Writer, chunkSize int) error

EncryptStream3x is the width-less Triple-Ouroboros plain-stream Encrypt entry point. Behaviour parity with EncryptStream modulo the 7-seed dispatch path.

func EncryptStream3x128

func EncryptStream3x128(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, chunkSize int, emit func(chunk []byte) error) error

EncryptStream3x128 encrypts data in chunks using Triple Ouroboros (128-bit variant).

func EncryptStream3x128Cfg

func EncryptStream3x128Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, chunkSize int, emit func(chunk []byte) error) error

EncryptStream3x128Cfg is the Cfg variant of EncryptStream3x128.

func EncryptStream3x256

func EncryptStream3x256(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, chunkSize int, emit func(chunk []byte) error) error

EncryptStream3x256 encrypts data in chunks using Triple Ouroboros (256-bit variant).

func EncryptStream3x256Cfg

func EncryptStream3x256Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, chunkSize int, emit func(chunk []byte) error) error

EncryptStream3x256Cfg is the Cfg variant of EncryptStream3x256.

func EncryptStream3x512

func EncryptStream3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, chunkSize int, emit func(chunk []byte) error) error

EncryptStream3x512 encrypts data in chunks using Triple Ouroboros (512-bit variant).

func EncryptStream3x512Cfg

func EncryptStream3x512Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, chunkSize int, emit func(chunk []byte) error) error

EncryptStream3x512Cfg is the Cfg variant of EncryptStream3x512.

func EncryptStream128

func EncryptStream128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, chunkSize int, emit func(chunk []byte) error) error

EncryptStream128 encrypts data in chunks using 128-bit hash seeds.

func EncryptStream128Cfg

func EncryptStream128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, chunkSize int, emit func(chunk []byte) error) error

EncryptStream128Cfg is the Cfg variant of EncryptStream128: drives each chunk through Encrypt128Cfg so per-encryptor NonceBits / BarrierFill / BitSoup / LockSoup / LockSeed overrides are honoured chunk-by-chunk. Body otherwise identical.

func EncryptStream256

func EncryptStream256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, chunkSize int, emit func(chunk []byte) error) error

EncryptStream256 encrypts data in chunks using 256-bit hash seeds.

func EncryptStream256Cfg

func EncryptStream256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, chunkSize int, emit func(chunk []byte) error) error

EncryptStream256Cfg is the Cfg variant of EncryptStream256.

func EncryptStream512

func EncryptStream512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, chunkSize int, emit func(chunk []byte) error) error

EncryptStream512 encrypts data in chunks using 512-bit hash seeds.

func EncryptStream512Cfg

func EncryptStream512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, chunkSize int, emit func(chunk []byte) error) error

EncryptStream512Cfg is the Cfg variant of EncryptStream512.

func EncryptStreamAuth

func EncryptStreamAuth(noiseSeed, dataSeed, startSeed any, src io.Reader, dst io.Writer, mac MACFunc, chunkSize int) error

EncryptStreamAuth is the width-less single-Ouroboros Streaming AEAD Encrypt entry point. Generates a fresh 32-byte CSPRNG streamID, writes it as the wire prefix, then drains src in chunkSize windows and emits each encrypted chunk through the matching Single Message per-chunk implementation. The terminating chunk carries finalFlag = true; an empty src draws and emits the streamID prefix followed by a single zero-length terminating chunk.

Mirrors the binding-side encrypt_stream_auth helpers in shape and in error semantics — chunk-by-chunk dispatch through the EncryptStreamAuthenticated* / DecryptStreamAuthenticated* family rather than per-chunk EncryptAuth.

func EncryptStreamAuth3x

func EncryptStreamAuth3x(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 any, src io.Reader, dst io.Writer, mac MACFunc, chunkSize int) error

EncryptStreamAuth3x is the width-less Triple-Ouroboros Streaming AEAD Encrypt entry point. Behaviour parity with EncryptStreamAuth modulo the 7-seed per-chunk dispatch path.

func EncryptStreamAuth3x128

func EncryptStreamAuth3x128(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, chunkSize int, macFunc MACFunc, emit func(chunk []byte) error) error

EncryptStreamAuth3x128 mirrors EncryptStreamAuth128 for the Triple Ouroboros (7-seed) variant at 128-bit hash width.

func EncryptStreamAuth3x128Cfg

func EncryptStreamAuth3x128Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, chunkSize int, macFunc MACFunc, emit func(chunk []byte) error) error

EncryptStreamAuth3x128Cfg is the Cfg variant of EncryptStreamAuth3x128.

func EncryptStreamAuth3x256

func EncryptStreamAuth3x256(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, chunkSize int, macFunc MACFunc, emit func(chunk []byte) error) error

EncryptStreamAuth3x256 mirrors EncryptStreamAuth128 for Triple Ouroboros (7-seed) at 256-bit hash width.

func EncryptStreamAuth3x256Cfg

func EncryptStreamAuth3x256Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, chunkSize int, macFunc MACFunc, emit func(chunk []byte) error) error

EncryptStreamAuth3x256Cfg is the Cfg variant of EncryptStreamAuth3x256.

func EncryptStreamAuth3x512

func EncryptStreamAuth3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, chunkSize int, macFunc MACFunc, emit func(chunk []byte) error) error

EncryptStreamAuth3x512 mirrors EncryptStreamAuth128 for Triple Ouroboros (7-seed) at 512-bit hash width.

func EncryptStreamAuth3x512Cfg

func EncryptStreamAuth3x512Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, chunkSize int, macFunc MACFunc, emit func(chunk []byte) error) error

EncryptStreamAuth3x512Cfg is the Cfg variant of EncryptStreamAuth3x512.

func EncryptStreamAuth128

func EncryptStreamAuth128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, chunkSize int, macFunc MACFunc, emit func(chunk []byte) error) error

EncryptStreamAuth128 is the wide-stream entry point for Streaming AEAD using 128-bit hash seeds. Generates a fresh 32-byte stream anchor, emits it as the first wire chunk, then loops over data in chunks of chunkSize bytes calling EncryptStreamAuthenticated128 per chunk with the running cumulative pixel offset and finalFlag = true on the last chunk.

Empty input is permitted: the helper emits the stream prefix followed by a single terminating chunk built from a 0-byte plaintext with finalFlag = true.

func EncryptStreamAuth128Cfg

func EncryptStreamAuth128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, chunkSize int, macFunc MACFunc, emit func(chunk []byte) error) error

EncryptStreamAuth128Cfg is the Cfg variant of EncryptStreamAuth128: drives each chunk through EncryptStreamAuthenticated128Cfg so per-encryptor NonceBits / BarrierFill / BitSoup / LockSoup / LockSeed overrides are honoured chunk-by-chunk. Body otherwise identical.

func EncryptStreamAuth256

func EncryptStreamAuth256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, chunkSize int, macFunc MACFunc, emit func(chunk []byte) error) error

EncryptStreamAuth256 mirrors EncryptStreamAuth128 for 256-bit hash seeds.

func EncryptStreamAuth256Cfg

func EncryptStreamAuth256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, chunkSize int, macFunc MACFunc, emit func(chunk []byte) error) error

EncryptStreamAuth256Cfg is the Cfg variant of EncryptStreamAuth256.

func EncryptStreamAuth512

func EncryptStreamAuth512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, chunkSize int, macFunc MACFunc, emit func(chunk []byte) error) error

EncryptStreamAuth512 mirrors EncryptStreamAuth128 for 512-bit hash seeds.

func EncryptStreamAuth512Cfg

func EncryptStreamAuth512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, chunkSize int, macFunc MACFunc, emit func(chunk []byte) error) error

EncryptStreamAuth512Cfg is the Cfg variant of EncryptStreamAuth512.

func EncryptStreamAuthenticated3x128

func EncryptStreamAuthenticated3x128(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool) ([]byte, error)

EncryptStreamAuthenticated3x128 encrypts a single Streaming AEAD chunk using Triple Ouroboros (128-bit variant). Streaming-binding components mirror EncryptStreamAuthenticated128: streamID, cumulativePixelOffset, and finalFlag enter the MAC input alongside the concatenated thirds; the flag byte rides on wire as the last byte inside third 2 of the encrypted container.

func EncryptStreamAuthenticated3x128Cfg

func EncryptStreamAuthenticated3x128Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed128, data []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool) ([]byte, error)

EncryptStreamAuthenticated3x128Cfg is the Cfg variant of EncryptStreamAuthenticated3x128: threads cfg through every Cfg-aware accessor in the Triple Ouroboros Streaming AEAD pipeline. Body otherwise identical, including the part2-reserves-tag-and-flag layout and the MAC-over-concatenated-payloads-plus-binding invariant.

func EncryptStreamAuthenticated3x256

func EncryptStreamAuthenticated3x256(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool) ([]byte, error)

EncryptStreamAuthenticated3x256 encrypts a single Streaming AEAD chunk using Triple Ouroboros (256-bit variant). Streaming-binding components mirror EncryptStreamAuthenticated256: streamID, cumulativePixelOffset, and finalFlag enter the MAC input alongside the concatenated thirds; the flag byte rides on wire as the last byte inside third 2 of the encrypted container.

func EncryptStreamAuthenticated3x256Cfg

func EncryptStreamAuthenticated3x256Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed256, data []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool) ([]byte, error)

EncryptStreamAuthenticated3x256Cfg is the Cfg variant of EncryptStreamAuthenticated3x256: threads cfg through every Cfg-aware accessor in the Triple Ouroboros Streaming AEAD pipeline. Body otherwise identical, including the part2-reserves-tag-and-flag layout and the MAC-over-concatenated-payloads-plus-binding invariant.

func EncryptStreamAuthenticated3x512

func EncryptStreamAuthenticated3x512(noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool) ([]byte, error)

EncryptStreamAuthenticated3x512 encrypts a single Streaming AEAD chunk using Triple Ouroboros (512-bit variant). Streaming-binding components mirror EncryptStreamAuthenticated512: streamID, cumulativePixelOffset, and finalFlag enter the MAC input alongside the concatenated thirds; the flag byte rides on wire as the last byte inside third 2 of the encrypted container.

func EncryptStreamAuthenticated3x512Cfg

func EncryptStreamAuthenticated3x512Cfg(cfg *Config, noiseSeed, dataSeed1, dataSeed2, dataSeed3, startSeed1, startSeed2, startSeed3 *Seed512, data []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool) ([]byte, error)

EncryptStreamAuthenticated3x512Cfg is the Cfg variant of EncryptStreamAuthenticated3x512: threads cfg through every Cfg-aware accessor in the Triple Ouroboros Streaming AEAD pipeline. Body otherwise identical, including the part2-reserves-tag-and-flag layout and the MAC-over-concatenated-payloads-plus-binding invariant.

func EncryptStreamAuthenticated128

func EncryptStreamAuthenticated128(noiseSeed, dataSeed, startSeed *Seed128, data []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool) ([]byte, error)

EncryptStreamAuthenticated128 encrypts a single Streaming AEAD chunk with integrity protection using 128-bit hash seeds.

Pipeline: data → COBS encode → build payload [COBS][0x00][fill] → MAC(payload || streamID || uint64_le(cumulativePixelOffset) || flag) → embed [payload][tag]flag into container.

streamID is the 32-byte CSPRNG-fresh anchor generated once per stream by the caller and reused across every chunk's MAC input. cumulativePixelOffset is the running sum Σ(W_j × H_j) over chunks j < i; the first chunk uses 0. finalFlag is true on the terminating chunk and false otherwise; the decoder recovers the flag byte before MAC verification and signals end-of-stream when it matches 0xFF.

Empty plaintext is permitted only when finalFlag is true (the empty-stream terminating chunk case); empty plaintext with finalFlag = false is rejected with the same shape as the Single Message authenticated path.

func EncryptStreamAuthenticated128Cfg

func EncryptStreamAuthenticated128Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed128, data []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool) ([]byte, error)

EncryptStreamAuthenticated128Cfg is the Cfg variant of EncryptStreamAuthenticated128: threads cfg through every Cfg-aware accessor in the Single Ouroboros Streaming AEAD pipeline. Body otherwise identical, including the MAC-input layout (payload || streamID || uint64_le(cumulativePixelOffset) || flag) and the on-wire [payload][tag]flag container body.

func EncryptStreamAuthenticated256

func EncryptStreamAuthenticated256(noiseSeed, dataSeed, startSeed *Seed256, data []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool) ([]byte, error)

EncryptStreamAuthenticated256 encrypts a single Streaming AEAD chunk with integrity protection using 256-bit hash seeds.

Pipeline: data → COBS encode → build payload [COBS][0x00][fill] → MAC(payload || streamID || uint64_le(cumulativePixelOffset) || flag) → embed [payload][tag]flag into container.

streamID is the 32-byte CSPRNG-fresh anchor generated once per stream by the caller and reused across every chunk's MAC input. cumulativePixelOffset is the running sum Σ(W_j × H_j) over chunks j < i; the first chunk uses 0. finalFlag is true on the terminating chunk and false otherwise; the decoder recovers the flag byte before MAC verification and signals end-of-stream when it matches 0xFF.

Empty plaintext is permitted only when finalFlag is true (the empty-stream terminating chunk case); empty plaintext with finalFlag = false is rejected with the same shape as the Single Message authenticated path.

func EncryptStreamAuthenticated256Cfg

func EncryptStreamAuthenticated256Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed256, data []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool) ([]byte, error)

EncryptStreamAuthenticated256Cfg is the Cfg variant of EncryptStreamAuthenticated256: threads cfg through every Cfg-aware accessor in the Single Ouroboros Streaming AEAD pipeline. Body otherwise identical, including the MAC-input layout (payload || streamID || uint64_le(cumulativePixelOffset) || flag) and the on-wire [payload][tag]flag container body.

func EncryptStreamAuthenticated512

func EncryptStreamAuthenticated512(noiseSeed, dataSeed, startSeed *Seed512, data []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool) ([]byte, error)

EncryptStreamAuthenticated512 encrypts a single Streaming AEAD chunk with integrity protection using 512-bit hash seeds.

Pipeline: data → COBS encode → build payload [COBS][0x00][fill] → MAC(payload || streamID || uint64_le(cumulativePixelOffset) || flag) → embed [payload][tag]flag into container.

streamID is the 32-byte CSPRNG-fresh anchor generated once per stream by the caller and reused across every chunk's MAC input. cumulativePixelOffset is the running sum Σ(W_j × H_j) over chunks j < i; the first chunk uses 0. finalFlag is true on the terminating chunk and false otherwise; the decoder recovers the flag byte before MAC verification and signals end-of-stream when it matches 0xFF.

Empty plaintext is permitted only when finalFlag is true (the empty-stream terminating chunk case); empty plaintext with finalFlag = false is rejected with the same shape as the Single Message authenticated path.

func EncryptStreamAuthenticated512Cfg

func EncryptStreamAuthenticated512Cfg(cfg *Config, noiseSeed, dataSeed, startSeed *Seed512, data []byte, macFunc MACFunc, streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool) ([]byte, error)

EncryptStreamAuthenticated512Cfg is the Cfg variant of EncryptStreamAuthenticated512: threads cfg through every Cfg-aware accessor in the Single Ouroboros Streaming AEAD pipeline. Body otherwise identical, including the MAC-input layout (payload || streamID || uint64_le(cumulativePixelOffset) || flag) and the on-wire [payload][tag]flag container body.

func GetBarrierFill

func GetBarrierFill() int

GetBarrierFill returns the current barrier fill value. Returns 1 if no override is set (default).

func GetBitSoup

func GetBitSoup() int32

GetBitSoup returns the current bit soup mode (0 = byte-level, non-zero = bit-level). See SetBitSoup.

func GetLockSeed

func GetLockSeed() int32

GetLockSeed returns the current dedicated-lockSeed activation flag (0 = off, 1 = on). See SetLockSeed.

func GetLockSoup

func GetLockSoup() int32

GetLockSoup returns the current Lock Soup overlay mode (0 = off, non-zero = on). See SetLockSoup.

func GetMaxWorkers

func GetMaxWorkers() int

GetMaxWorkers returns the current maximum worker limit. Returns 0 if no limit is set (default: uses all available CPUs).

func GetNonceBits

func GetNonceBits() int

GetNonceBits returns the current nonce size in bits.

func MakeAreionSoEM256Hash

func MakeAreionSoEM256Hash(key ...[32]byte) (HashFunc256, BatchHashFunc256, [32]byte)

MakeAreionSoEM256Hash returns a fresh (single, batched) hash pair suitable for Seed256.Hash and Seed256.BatchHash, plus the 32-byte fixed key the pair is bound to. With no argument the key is freshly generated via crypto/rand; passing a single caller-supplied [32]byte uses that key instead — meant for the persistence-restore path (encrypt today, decrypt tomorrow). Both arms share the same fixed key so per-pixel hashes computed via the batched dispatch match the single-call path bit-exact (the invariant required by BatchHashFunc256).

Construction (matches the cached-wrapper README example for Areion-SoEM-256): the fixed key occupies bytes [0..32) of the 64-byte SoEM subkey arrangement; per-pixel seed components fill bytes [32..64) as 4 × little-endian uint64. The SoEM-256 PRF is then applied to the 32-byte data input.

Usage (random key, save it for cross-process persistence):

ns, _ := itb.NewSeed256(2048, nil) // Hash set below
hashFn, batchFn, hashKey := itb.MakeAreionSoEM256Hash()
ns.Hash, ns.BatchHash = hashFn, batchFn
saveKey(hashKey)

Usage (explicit key, restored from storage):

hashFn, batchFn, _ := itb.MakeAreionSoEM256Hash(savedKey)
ns.Hash, ns.BatchHash = hashFn, batchFn

On x86_64 hardware with VAES + AVX-512 the BatchHash path routes per-pixel hashing four pixels per call through AreionSoEM256x4, yielding ~2× throughput over the single-call path on this primitive.

func MakeAreionSoEM256HashWithKey

func MakeAreionSoEM256HashWithKey(fixedKey [32]byte) (HashFunc256, BatchHashFunc256)

MakeAreionSoEM256HashWithKey is the explicit-key counterpart of MakeAreionSoEM256Hash. Use this on the persistence-restore path when the 32-byte fixed key has been saved across processes — the returned (single, batched) pair will reproduce the same per-pixel hashes as the original encrypt-side closure.

func MakeAreionSoEM512Hash

func MakeAreionSoEM512Hash(key ...[64]byte) (HashFunc512, BatchHashFunc512, [64]byte)

MakeAreionSoEM512Hash returns the 512-bit counterpart of MakeAreionSoEM256Hash, plus the 64-byte fixed key the pair is bound to. Same construction principle: 64-byte fixed key in bytes [0..64) of the 128-byte SoEM-512 subkey arrangement, per-pixel seed components in bytes [64..128) as 8 × little-endian uint64. Bit-exact parity invariant identical to the 256-bit case. Variadic key arg and saved-key flow identical to MakeAreionSoEM256Hash.

func MakeAreionSoEM512HashWithKey

func MakeAreionSoEM512HashWithKey(fixedKey [64]byte) (HashFunc512, BatchHashFunc512)

MakeAreionSoEM512HashWithKey is the explicit-key counterpart of MakeAreionSoEM512Hash. Same role as MakeAreionSoEM256HashWithKey scaled to the 64-byte fixed key of Areion-SoEM-512.

func ParseChunkLen

func ParseChunkLen(data []byte) (int, error)

ParseChunkLen reads a chunk header and returns the total chunk size in bytes. The chunk wire format is identical to a single-chunk ITB ciphertext:

[16-byte nonce][2-byte width BE][2-byte height BE][W*H*8 container]

Returns an error when the supplied buffer is shorter than the fixed header size, the dimensions are zero / overflow / exceed the container cap, or the buffer does not contain enough trailing bytes for the announced container body.

Streaming consumers use ParseChunkLen to walk a concatenated stream of ITB ciphertexts on disk or over the wire one chunk at a time without buffering the entire stream in memory: read the fixed header, call ParseChunkLen to learn the chunk size, read that many bytes, hand them to Decrypt{128,256,512} (or the matching Decrypt3x* / DecryptAuthenticated* / etc.), repeat. The FFI surface re-exports the same function as ITB_ParseChunkLen.

func ParseChunkLenCfg

func ParseChunkLenCfg(cfg *Config, data []byte) (int, error)

ParseChunkLenCfg is the Cfg variant of ParseChunkLen: consults [currentNonceSizeCfg] and [headerSizeCfg] so a non-nil cfg with an explicit NonceBits override is honoured at the chunk-header parse site. Body otherwise identical.

func SetBarrierFill

func SetBarrierFill(n int)

SetBarrierFill sets the CSPRNG barrier fill margin added to the container side. Valid values: 1, 2, 4, 8, 16, 32. Default is 1. Panics on invalid input — barrier misconfiguration is a security-critical bug. Asymmetric: the receiver does not need the same value as the sender. Thread-safe (atomic). Affects all subsequent Encrypt calls.

func SetBitSoup

func SetBitSoup(mode int32)

SetBitSoup configures plaintext split granularity for the whole process.

mode == 0 → byte-level split (default, shipped behaviour).
mode != 0 → bit-level split ("bit soup"; opt-in reserve mode).

Applies uniformly to every Triple Ouroboros variant — Encrypt3x128 / Decrypt3x128, the 256- / 512-bit mirrors, EncryptAuthenticated3x128 / DecryptAuthenticated3x128 and their mirrors, and the streaming variants EncryptStream3x128 / DecryptStream3x128 and mirrors. On Single Ouroboros — Encrypt128 / Decrypt128 and the 256/512 mirrors plus authenticated and streaming counterparts — non-zero mode engages the bit-permutation overlay path. The Single dispatcher OR-gates [bitSoupEnabled] and [lockSoupEnabled] (either flag alone is sufficient to activate the overlay); the flags themselves remain independent at the setter level — there is no SetBitSoup → SetLockSoup cascade. See SetLockSoup for the documented LockSoup → BitSoup cascade in the opposite direction. The ciphertext wire format is identical in all modes: [nonce][W][H][pixels].

Note: also automatically enabled when SetLockSoup is set to a non-zero value, because the Lock Soup overlay layers on top of bit soup.

Deployment discipline: set the mode once at process startup before any encrypt or decrypt call; callers must agree on the mode across both sides of the channel. Encrypt-decrypt with mismatched modes produces either a length-prefix error or byte-level garbage (detectable via authenticated variants' MAC check or caller-side integrity validation).

Bit soup relocates the SAT-cryptanalysis barrier from the computational layer to the instance-formulation layer. Under Partial KPA + realistic protocol traffic, the joint per-snake SAT instance is information-theoretically under-determined at the crib coverage realistic protocols supply — a property of the observations available to the attacker, not of the solver applied to them. Improvements in solver performance do not convert an under-determined instance into a determined one. This is orthogonal to, not stronger than, computational hardness.

func SetGCPercent

func SetGCPercent(pct int) int

SetGCPercent configures the Go runtime's GC trigger percentage. The default is 100 (GC fires at +100% heap growth); lower values trigger GC more aggressively. Pass -1 (or any negative value) to query the current value without changing it; the previous value is returned. Setter calls override any ITB_GOGC env var set at libitb load time.

func SetLockSeed

func SetLockSeed(n int)

SetLockSeed enables or disables the dedicated lockSeed for bit-permutation derivation. Valid values: 0 = off (default, bit-permutation derives from noiseSeed), 1 = on. Panics on any other value.

Auto-couples Lock Soup on the on-direction: when n == 1 this also calls SetLockSoup(1), which through its existing coupling engages SetBitSoup(1) too — the dedicated lockSeed has no observable effect on the wire output unless the bit-permutation overlay is engaged, so coupling the two flags spares callers a second setter call. The off-direction does not auto-disable the overlay; callers that explicitly enabled Lock Soup / Bit Soup alongside LockSeed and want to drop only LockSeed call SetLockSeed(0) without losing the underlying overlay.

Two-tier consumption:

• The encryptor constructor in the easy sub-package reads this flag at New / New3 time via SnapshotGlobals; encryptors built after this call get a dedicated lockSeed allocated and wired into cfg.LockSeedHandle automatically.
• The legacy itb root entry points (Encrypt{N} / Decrypt{N} / Encrypt3x{N} / Decrypt3x{N} and friends) do NOT consume this flag directly — they consult only Seed128.AttachedLockSeed / Seed256.AttachedLockSeed / Seed512.AttachedLockSeed for the dedicated-seed path. Callers that want LockSeed on the legacy path call Seed128.AttachLockSeed / etc. on the noiseSeed; the global flag still auto-enables the bit-permutation overlay (so the output IS bit-soup-permuted) but the keying material falls back to noiseSeed when no attach has happened.

Thread-safe (atomic). Affects encryptors constructed AFTER this call; existing encryptors are pinned at their construction snapshot.

func SetLockSoup

func SetLockSoup(mode int32)

SetLockSoup configures the Lock Soup keyed-permutation overlay for the whole process.

mode == 0 → off (default; ciphertext bit-identical to plain bit soup).
mode != 0 → on (per-chunk PRF-keyed bit-permutation; automatically
            engages [SetBitSoup] as well — Lock Soup layers on top of
            bit soup, so non-zero Lock Soup implies non-zero bit soup).

Applies uniformly to every Triple Ouroboros variant — Encrypt3x128 / Decrypt3x128, the 256- / 512-bit mirrors, EncryptAuthenticated3x128 / DecryptAuthenticated3x128 and their mirrors — and to every Single Ouroboros variant: Encrypt128 / Decrypt128, the 256/512 mirrors, authenticated and streaming counterparts. Both sides of the channel must use the same mode; mismatched modes produce wrong-seed-style garbage (no error oracle, plausible-decryption invariant preserved).

Deployment discipline: set the mode once at process startup before any encrypt or decrypt call; callers must agree on the mode across both sides of the channel.

Lock Soup raises the bit soup attacker-enumeration cost from the public-encoding floor (+18.1 bits via startPixel triple on Triple, +0 on Single because the single snake carries the whole plaintext) to +33 bits per crib chunk on Triple, +64 bits per crib chunk on Single, of additional keyed permutation entropy. This is an opt-in defense-reserve mode that makes any SAT-tractable recovery path infeasible even for below-spec primitives.

func SetMaxWorkers

func SetMaxWorkers(n int)

SetMaxWorkers sets the maximum number of parallel workers for pixel processing. Pass 0 to use all available CPUs (default). Valid range: 0 to 256. Values above 256 are clamped. Negative values are treated as 0 (all CPUs). This affects all subsequent Encrypt/Decrypt calls across all hash widths.

func SetMemoryLimit

func SetMemoryLimit(limit int64) int64

SetMemoryLimit configures the Go runtime's heap-size soft limit (bytes). Pass -1 (or any negative value) to query the current limit without changing it; the previous limit is returned. Setter calls override any ITB_GOMEMLIMIT env var set at libitb load time.

func SetNonceBits

func SetNonceBits(n int)

SetNonceBits sets the nonce size in bits. Valid values: 128, 256, 512. Panics on invalid input — nonce misconfiguration is a security-critical bug. Both sender and receiver must use the same value. Thread-safe (atomic). Affects all subsequent Encrypt calls.

Types

type BatchHashFunc128

type BatchHashFunc128 func(data *[4][]byte, seeds [4][2]uint64) [4][2]uint64

BatchHashFunc128 is the 4-way batched 128-bit hash interface alongside HashFunc128. Primitives whose SIMD kernel processes four independent (data, seed) tuples per call expose this — e.g. the ZMM-batched SipHash-2-4 / AES-CMAC kernels on amd64 with AVX-512 + VAES.

Bit-exact parity invariant: each lane output BatchHashFunc128(data, seeds)[i] matches the serial HashFunc128(data[i], seeds[i][0], seeds[i][1]) reference. Implementations violating this break the PRF assumption on the batched dispatch path.

type BatchHashFunc256

type BatchHashFunc256 func(data *[4][]byte, seeds [4][4]uint64) [4][4]uint64

BatchHashFunc256 is the 4-way batched 256-bit hash interface alongside HashFunc256. Primitives whose SIMD kernel processes four independent (data, seed) tuples per call expose this — e.g. the ZMM-batched Areion-SoEM-256 / BLAKE3 / BLAKE2s / ChaCha20 kernels on amd64 with AVX-512 + VAES.

Bit-exact parity invariant: each lane output BatchHashFunc256(data, seeds)[i] matches the serial HashFunc256(data[i], seeds[i]) reference. Implementations violating this break the PRF assumption on the batched dispatch path.

type BatchHashFunc512

type BatchHashFunc512 func(data *[4][]byte, seeds [4][8]uint64) [4][8]uint64

BatchHashFunc512 is the 4-way batched 512-bit hash interface alongside HashFunc512. Primitives whose SIMD kernel processes four independent (data, seed) tuples per call expose this — e.g. the ZMM-batched Areion-SoEM-512 / BLAKE2b-512 kernels on amd64 with AVX-512 + VAES.

Bit-exact parity invariant: each lane output BatchHashFunc512(data, seeds)[i] matches the serial HashFunc512(data[i], seeds[i]) reference. Implementations violating this break the PRF assumption on the batched dispatch path.

type Blob128

type Blob128 struct {
	Mode int

	KeyN  []byte
	KeyD  []byte
	KeyS  []byte
	KeyL  []byte
	KeyD1 []byte
	KeyD2 []byte
	KeyD3 []byte
	KeyS1 []byte
	KeyS2 []byte
	KeyS3 []byte

	NS  *Seed128
	DS  *Seed128
	SS  *Seed128
	LS  *Seed128
	DS1 *Seed128
	DS2 *Seed128
	DS3 *Seed128
	SS1 *Seed128
	SS2 *Seed128
	SS3 *Seed128

	MACKey  []byte
	MACName string
}

Blob128 is the 128-bit width counterpart of Blob512. Hash key fields are []byte (variable length): 16 bytes for aescmac, empty for siphash24. See Blob512 for the full API contract; the surface mirrors symmetrically across widths apart from the key type.

func (*Blob128) Export

func (b *Blob128) Export(
	keyN, keyD, keyS []byte,
	ns, ds, ss *Seed128,
	opts ...Blob128Opts,
) ([]byte, error)

Export — Single Ouroboros, 128-bit width. See Blob512.Export.

func (*Blob128) Export3

func (b *Blob128) Export3(
	keyN []byte,
	keyD1, keyD2, keyD3 []byte,
	keyS1, keyS2, keyS3 []byte,
	ns, ds1, ds2, ds3, ss1, ss2, ss3 *Seed128,
	opts ...Blob128Opts,
) ([]byte, error)

Export3 — Triple Ouroboros, 128-bit width. See Blob512.Export3.

func (*Blob128) Import

func (b *Blob128) Import(data []byte) error

Import — Single Ouroboros, 128-bit width. See Blob512.Import.

func (*Blob128) Import3

func (b *Blob128) Import3(data []byte) error

Import3 — Triple Ouroboros, 128-bit width. See Blob512.Import3.

type Blob128Opts

type Blob128Opts struct {
	KeyL    []byte
	LS      *Seed128
	MACKey  []byte
	MACName string
}

Blob128Opts is the 128-bit width counterpart of Blob512Opts. KeyL is a variable-length byte slice (empty for siphash24, 16 bytes for aescmac).

type Blob256

type Blob256 struct {
	Mode int

	KeyN  [32]byte
	KeyD  [32]byte
	KeyS  [32]byte
	KeyL  [32]byte
	KeyD1 [32]byte
	KeyD2 [32]byte
	KeyD3 [32]byte
	KeyS1 [32]byte
	KeyS2 [32]byte
	KeyS3 [32]byte

	NS  *Seed256
	DS  *Seed256
	SS  *Seed256
	LS  *Seed256
	DS1 *Seed256
	DS2 *Seed256
	DS3 *Seed256
	SS1 *Seed256
	SS2 *Seed256
	SS3 *Seed256

	MACKey  []byte
	MACName string
}

Blob256 is the 256-bit width counterpart of Blob512. Hash key fields are [32]byte (areion256, blake3, blake2s, blake2b256, chacha20 — all 32-byte fixed key). See Blob512 for the full API contract; the surface mirrors symmetrically across widths.

func (*Blob256) Export

func (b *Blob256) Export(
	keyN, keyD, keyS [32]byte,
	ns, ds, ss *Seed256,
	opts ...Blob256Opts,
) ([]byte, error)

Export — Single Ouroboros, 256-bit width. See Blob512.Export.

func (*Blob256) Export3

func (b *Blob256) Export3(
	keyN [32]byte,
	keyD1, keyD2, keyD3 [32]byte,
	keyS1, keyS2, keyS3 [32]byte,
	ns, ds1, ds2, ds3, ss1, ss2, ss3 *Seed256,
	opts ...Blob256Opts,
) ([]byte, error)

Export3 — Triple Ouroboros, 256-bit width. See Blob512.Export3.

func (*Blob256) Import

func (b *Blob256) Import(data []byte) error

Import — Single Ouroboros, 256-bit width. See Blob512.Import.

func (*Blob256) Import3

func (b *Blob256) Import3(data []byte) error

Import3 — Triple Ouroboros, 256-bit width. See Blob512.Import3.

type Blob256Opts

type Blob256Opts struct {
	KeyL    [32]byte
	LS      *Seed256
	MACKey  []byte
	MACName string
}

Blob256Opts is the 256-bit width counterpart of Blob512Opts.

type Blob512

type Blob512 struct {
	Mode int

	// Hash key bytes — populated for the slots actually used by
	// the active Mode. Other slots stay zero.
	KeyN  [64]byte // shared (Single + Triple)
	KeyD  [64]byte // Single only
	KeyS  [64]byte // Single only
	KeyL  [64]byte // optional dedicated lockSeed (any mode)
	KeyD1 [64]byte // Triple only
	KeyD2 [64]byte
	KeyD3 [64]byte
	KeyS1 [64]byte
	KeyS2 [64]byte
	KeyS3 [64]byte

	// Seed components — *Seed512 with .Components populated.
	// Hash and BatchHash are nil after Import; the caller wires
	// them from the saved Key* bytes.
	NS  *Seed512 // shared
	DS  *Seed512 // Single only
	SS  *Seed512 // Single only
	LS  *Seed512 // optional dedicated lockSeed (nil if absent)
	DS1 *Seed512 // Triple only
	DS2 *Seed512
	DS3 *Seed512
	SS1 *Seed512
	SS2 *Seed512
	SS3 *Seed512

	// Optional MAC material. Caller rebuilds the closure with
	// macs.Make(MACName, MACKey).
	MACKey  []byte
	MACName string
}

Blob512 carries native-API encryptor material (512-bit width) across processes. Public fields are populated after Blob512.Import or Blob512.Import3; the caller wires Hash / BatchHash closures from the saved Key* bytes through the appropriate 512-bit factory.

[Blob512.Mode] indicates which fields are populated: 1 (Single) fills NS / DS / SS plus the optional LS; 3 (Triple) fills NS / DS1 / DS2 / DS3 / SS1 / SS2 / SS3 plus the optional LS. Triple-only fields stay zero in Single mode and vice versa; Mode is the authoritative discriminator.

Not safe for concurrent invocation — Export / Import calls on the same Blob512 instance must be serialised by the caller.

func (*Blob512) Export

func (b *Blob512) Export(
	keyN, keyD, keyS [64]byte,
	ns, ds, ss *Seed512,
	opts ...Blob512Opts,
) ([]byte, error)

Export packs Single-Ouroboros material (3 seeds + 3 hash keys) plus the captured globals into a JSON blob. Optional dedicated lockSeed and MAC material ride in the variadic Blob512Opts trailing argument (zero or one element accepted).

func (*Blob512) Export3

func (b *Blob512) Export3(
	keyN [64]byte,
	keyD1, keyD2, keyD3 [64]byte,
	keyS1, keyS2, keyS3 [64]byte,
	ns, ds1, ds2, ds3, ss1, ss2, ss3 *Seed512,
	opts ...Blob512Opts,
) ([]byte, error)

Export3 packs Triple-Ouroboros material (1 noise + 3 data + 3 start seeds + 7 matching hash keys) plus the captured globals. Optional LockSeed and MAC ride in the variadic Blob512Opts.

func (*Blob512) Import

func (b *Blob512) Import(data []byte) error

Import parses a Single-Ouroboros blob produced by Blob512.Export, resets the receiver, and populates Mode + KeyN/KeyD/KeyS + NS/DS/SS + optional KeyL/LS + optional MACKey/MACName. Captured globals are applied unconditionally via SetNonceBits / SetBarrierFill / SetBitSoup / SetLockSoup before populating the struct.

Returns ErrBlobModeMismatch when the blob carries Mode=3 (call Import3 instead), ErrBlobMalformed on parse / shape failure, ErrBlobVersionTooNew when the blob's "v" exceeds this build's schema version.

func (*Blob512) Import3

func (b *Blob512) Import3(data []byte) error

Import3 is the Triple-Ouroboros counterpart of Blob512.Import. Same error contract; populates the Triple-mode field set.

type Blob512Opts

type Blob512Opts struct {
	KeyL    [64]byte // zero array if no lockSeed
	LS      *Seed512 // nil if no lockSeed
	MACKey  []byte   // nil / empty if no MAC
	MACName string   // empty if no MAC
}

Blob512Opts carries the optional dedicated lockSeed and MAC material for Blob512.Export / Blob512.Export3. Zero-valued fields signal "absent" — pass an empty struct, or omit the opts argument entirely, when no LockSeed and no MAC are in use.

type Config

type Config struct {
	NonceBits      int         // 0 = inherit; otherwise 128 / 256 / 512
	BarrierFill    int         // 0 = inherit; otherwise 1 / 2 / 4 / 8 / 16 / 32
	BitSoup        int32       // -1 = inherit; 0 = off; non-zero = on
	LockSoup       int32       // -1 = inherit; 0 = off; non-zero = on
	LockSeed       int32       // -1 = inherit; 0 = off; 1 = on
	LockSeedHandle interface{} // nil unless LockSeed == 1; *Seed{128,256,512}
}

Config carries per-encryptor overrides for the global-state settings that are safe to scope per encryptor: nonce size, barrier fill, bit soup, lock soup, and lock seed. The MaxWorkers global stays process-wide and is not represented here — effectiveWorkers is consulted from many internal paths and threading per-encryptor would expand the refactor without proportional benefit.

Sentinel-valued fields signal "inherit the current global state at access time"; non-sentinel values signal that the encryptor has explicitly set the field. The sentinel value differs per field:

• NonceBits: 0 = inherit; otherwise 128 / 256 / 512 (in bits).
• BarrierFill: 0 = inherit; otherwise 1 / 2 / 4 / 8 / 16 / 32.
• BitSoup: -1 = inherit; 0 = off; non-zero = on.
• LockSoup: -1 = inherit; 0 = off; non-zero = on.
• LockSeed: -1 = inherit; 0 = off; 1 = on (dedicated lockSeed drives bit-permutation derivation instead of noiseSeed).

LockSeedHandle is not a Config knob in the value sense — it is the pointer to the dedicated lockSeed object the encryptor constructor allocates when LockSeed becomes 1. Internal Cfg-suffixed bit-soup accessors consult this handle to route bit-permutation derivation to the dedicated seed; the value-typed LockSeed flag indicates only whether the dedicated seed is active.

The struct is unexported. The legacy public entry points (Encrypt512 etc.) pass nil to the Cfg-variant entry points and inherit the global state, preserving pre-refactor behaviour bit-exactly.

func SnapshotGlobals

func SnapshotGlobals() *Config

SnapshotGlobals returns a Config initialised from the current process-global setter state. The encryptor constructor invokes this at New / New3 time so the encryptor's effective Config matches the global state at construction. Subsequent mutations of either side (global setters or encryptor setters) do not cross — the encryptor owns its own Config copy and mutates only that.

LockSeedHandle is left nil; the constructor populates it after snapshotting when the resulting LockSeed flag is 1.

Every snapshotted field carries the global's actual value (not the inherit sentinel) — pinning the encryptor to the global state at New time. Subsequent global mutations therefore do not leak into existing encryptors; only encryptors constructed AFTER the global mutation see the new value.

type HashFunc128

type HashFunc128 func(data []byte, seed0, seed1 uint64) (lo, hi uint64)

HashFunc128 is the pluggable 128-bit hash function interface.

The function accepts arbitrary-length data and two uint64 seed values, returning two uint64 outputs (128-bit total). The 128-bit intermediate state enables effective key sizes up to 1024 bits through ChainHash128.

PRF-grade hash functions are required (see Definition 2 in SCIENCE.md).

Example wrappers:

// SipHash-2-4 (natural 128-bit keyed hash)
func sipHash128(data []byte, seed0, seed1 uint64) (uint64, uint64) {
    return siphash.Hash128(seed0, seed1, data)
}

// AES-CMAC (128-bit, AES-NI hardware acceleration)
func aesCMAC128(data []byte, seed0, seed1 uint64) (uint64, uint64) {
    var key [16]byte
    binary.LittleEndian.PutUint64(key[:8], seed0)
    binary.LittleEndian.PutUint64(key[8:], seed1)
    // compute CMAC...
    return lo, hi
}

type HashFunc256

type HashFunc256 func(data []byte, seed [4]uint64) [4]uint64

HashFunc256 is the pluggable 256-bit hash function interface.

The function accepts arbitrary-length data and a [4]uint64 seed (256 bits), returning a [4]uint64 output. The 256-bit intermediate state enables effective key sizes up to 2048 bits through ChainHash256.

PRF-grade hash functions are required (see Definition 2 in SCIENCE.md).

Example wrapper:

// BLAKE3 keyed (256-bit, AVX-512 acceleration)
func blake3Hash256(data []byte, seed [4]uint64) [4]uint64 {
    var key [32]byte
    binary.LittleEndian.PutUint64(key[0:], seed[0])
    binary.LittleEndian.PutUint64(key[8:], seed[1])
    binary.LittleEndian.PutUint64(key[16:], seed[2])
    binary.LittleEndian.PutUint64(key[24:], seed[3])
    h := blake3.DeriveKey(key, data)
    var out [4]uint64
    for i := range out {
        out[i] = binary.LittleEndian.Uint64(h[i*8:])
    }
    return out
}

type HashFunc512

type HashFunc512 func(data []byte, seed [8]uint64) [8]uint64

HashFunc512 is the pluggable 512-bit hash function interface.

The function accepts arbitrary-length data and a [8]uint64 seed (512 bits), returning a [8]uint64 output. The 512-bit intermediate state enables effective key sizes up to 2048 bits (with current MaxKeyBits) through ChainHash512.

PRF-grade hash functions are required (see Definition 2 in SCIENCE.md).

Example wrapper:

// BLAKE2b-512 keyed (512-bit native key and output)
func blake2b512(data []byte, seed [8]uint64) [8]uint64 {
    var key [64]byte
    for i := 0; i < 8; i++ {
        binary.LittleEndian.PutUint64(key[i*8:], seed[i])
    }
    h, _ := blake2b.New512(key[:])
    h.Write(data)
    var digest [64]byte
    h.Sum(digest[:0])
    var out [8]uint64
    for i := range out {
        out[i] = binary.LittleEndian.Uint64(digest[i*8:])
    }
    return out
}

type MACFunc

type MACFunc func(data []byte) []byte

MACFunc is the pluggable MAC function interface.

The function must accept a byte slice and return a fixed-size tag. The MAC key management is the caller's responsibility — the MACFunc closure should capture the key.

The tag is computed over the entire encrypted payload (COBS + null terminator + random padding), not just the plaintext. Given a secure MAC function, flipping any data bit in the container causes MAC failure, preventing the CCA spatial pattern that would otherwise distinguish padding from data regions (see SCIENCE.md Section 4.3).

Example wrappers:

// HMAC-SHA256 (crypto/hmac + crypto/sha256)
func hmacSHA256(key []byte) itb.MACFunc {
    return func(data []byte) []byte {
        h := hmac.New(sha256.New, key)
        h.Write(data)
        return h.Sum(nil)
    }
}

// BLAKE3 MAC (github.com/zeebo/blake3)
func blake3MAC(key []byte) itb.MACFunc {
    return func(data []byte) []byte {
        h := blake3.DeriveKey(key, data)
        return h[:32]
    }
}

type Seed128

type Seed128 struct {
	Components []uint64
	Hash       HashFunc128
	// BatchHash is the optional 4-way batched counterpart of Hash. When
	// non-nil and ITB's runtime detects that both noiseSeed and dataSeed
	// of an Encrypt128 / Decrypt128 invocation expose BatchHash,
	// processChunk128 dispatches per-pixel hashing four pixels at a
	// time via BatchChainHash128 instead of one pixel per ChainHash128
	// call. The Hash field remains the bit-exact reference; BatchHash
	// must agree with Hash on every input (see seed128_batch.go for the
	// parity invariant). nil disables batched dispatch and preserves
	// the legacy single-call code path.
	BatchHash BatchHashFunc128
	// contains filtered or unexported fields
}

Seed128 holds a dynamically-sized symmetric key with a pluggable 128-bit hash function.

Key size is len(Components) * 64 bits. Components are consumed 2 per round by ChainHash128, giving 128-bit intermediate state. Effective security: min(keyBits, 128 * numRounds). For 1024-bit key (16 components, 8 rounds): effective security = 1024 bits.

func NewSeed128

func NewSeed128(bits int, hashFunc HashFunc128) (*Seed128, error)

NewSeed128 creates a new 128-bit seed with cryptographically random components.

bits must be a multiple of 128, in range [512, 2048]. Components count must be even (2 per ChainHash128 round).

Example:

seed, err := itb.NewSeed128(1024, sipHash128)

func SeedFromComponents128

func SeedFromComponents128(hashFunc HashFunc128, components ...uint64) (*Seed128, error)

SeedFromComponents128 creates a 128-bit seed from existing uint64 values.

components length must be in range [8, 32] and even.

Example:

seed, err := itb.SeedFromComponents128(sipHash128,
    0xc07724706ed0758b, 0x0489964ee29ad754,
    0x97819a4b77e0fd0a, 0xd9b9322f08f9eb5c,
    0x9d8dc0b866e92b87, 0xaf7f4a99914da68b,
    0x51101868dab807ae, 0xbc6e07a2a5067689,
)

func (*Seed128) AttachLockSeed

func (s *Seed128) AttachLockSeed(ls *Seed128)

AttachLockSeed installs ls as the dedicated lockSeed for this noiseSeed. Subsequent Encrypt / Decrypt / EncryptAuthenticated / DecryptAuthenticated / EncryptStream / DecryptStream calls that take this seed as the noise slot route bit-permutation derivation through ls instead of through the receiver — the noise-injection channel still consumes the receiver's components and Hash, while the bit-permutation channel consumes BOTH ls's Components AND ls's Hash function, without changing any public Encrypt / Decrypt signature. The PRF primitive on the bit-permutation channel may therefore differ from the noise-injection channel's primitive within the same native width (the *Seed128 type signature here enforces width match), yielding keying-material isolation AND algorithm diversity for defence-in-depth on the overlay path.

Anti-conflation safeguards (each panics rather than silently degrading the entropy isolation):

• Self-attach (ls == ns) panics with ErrLockSeedSelfAttach: bit-permutation derivation would still consume the receiver's state, defeating the isolation purpose.
• Component-aliasing (ls.Components and the receiver's Components share the same backing array — typically because ls was built by copying the slice header rather than the underlying data) panics with ErrLockSeedComponentAliasing: a shared backing array means every encrypt-time mutation of either Components slice silently mutates the other, defeating the entropy isolation between the noise-injection and bit-permutation channels. The check is pointer-aliasing on the slice's first element, not value-equality — deep-copied slices that happen to carry identical uint64 values are not caught here.
• Post-Encrypt re-attach (this seed has been used in a successful Encrypt) panics with ErrLockSeedAfterEncrypt: switching the dedicated lockSeed mid-session breaks decryptability of pre-switch ciphertext.

Idempotent for the same ls (re-attaching the same pointer after validation does not panic). Both seeds remain fully independent objects — AttachLockSeed does not modify ls and does not copy any state between the two; it merely records a single pointer field on the receiver.

Not safe for concurrent invocation with an in-flight Encrypt / Decrypt on the same noiseSeed — caller serialises the attach sequence before dispatching parallel encrypt traffic.

func (*Seed128) AttachedLockSeed

func (s *Seed128) AttachedLockSeed() *Seed128

AttachedLockSeed returns the dedicated lockSeed previously installed via Seed128.AttachLockSeed, or nil when no lockSeed has been attached. Used internally by the bit-permutation derivation builders to route through the dedicated seed when present, and by serialization paths to extract the attached lockSeed alongside the noiseSeed for persistence.

func (*Seed128) BatchChainHash128

func (s *Seed128) BatchChainHash128(buf *[4][]byte) [4][2]uint64

BatchChainHash128 runs the four-way batched ChainHash128 via s.BatchHash. Output [i] matches serial ChainHash128(data[i]) under the same Components. Caller ensures s.BatchHash != nil (processChunk128 checks this before invoking).

func (*Seed128) Bits

func (s *Seed128) Bits() int

Bits returns the key size in bits.

func (*Seed128) ChainHash128

func (s *Seed128) ChainHash128(buf []byte) (uint64, uint64)

ChainHash128 computes chained hash across all seed components with 128-bit state.

Each round consumes 2 components and the previous 128-bit output:

(hLo, hHi) = Hash128(data, s[0], s[1])
(hLo, hHi) = Hash128(data, s[2] ^ hLo, s[3] ^ hHi)
...

func (*Seed128) DetachLockSeed

func (s *Seed128) DetachLockSeed()

DetachLockSeed removes a previously-installed dedicated lockSeed pointer from this noiseSeed. After the call AttachedLockSeed returns nil and the bit-permutation derivation falls back to noiseSeed-driven keying material on subsequent encrypt calls.

Panics with ErrLockSeedAfterEncrypt when called on a seed that has already produced ciphertext — the post-Encrypt invariant that protects pre-switch ciphertext from later detach is the same one that protects against mid-session attach (mirrors Seed128.AttachLockSeed).

Safe to call when no lockSeed is attached (no-op).

func (*Seed128) MinPixels

func (s *Seed128) MinPixels() int

MinPixels returns minimum pixel count ensuring encoding ambiguity (56^P) exceeds key space (2^keyBits). Formula: ceil(keyBits / log2(56)). Used by Encrypt/Decrypt and Stream functions (Core ITB / MAC + Silent Drop).

func (*Seed128) MinPixelsAuth

func (s *Seed128) MinPixelsAuth() int

MinPixelsAuth returns minimum pixel count ensuring encoding ambiguity (7^P) exceeds key space (2^keyBits) even under CCA. Formula: ceil(keyBits / log2(7)). Used by EncryptAuthenticated/DecryptAuthenticated (MAC + Reveal possible).

func (*Seed128) MinSide

func (s *Seed128) MinSide() int

MinSide returns minimum square container side length.

type Seed256

type Seed256 struct {
	Components []uint64
	Hash       HashFunc256
	// BatchHash is the optional 4-way batched counterpart of Hash. When
	// non-nil and ITB's runtime detects that both noiseSeed and dataSeed
	// of an Encrypt256 / Decrypt256 invocation expose BatchHash,
	// processChunk256 dispatches per-pixel hashing four pixels at a
	// time via BatchChainHash256 instead of one pixel per ChainHash256
	// call. The Hash field remains the bit-exact reference; BatchHash
	// must agree with Hash on every input (see seed256_batch.go for the
	// parity invariant). nil disables batched dispatch and preserves
	// the legacy single-call code path.
	BatchHash BatchHashFunc256
	// contains filtered or unexported fields
}

Seed256 holds a dynamically-sized symmetric key with a pluggable 256-bit hash function.

Components are consumed 4 per round by ChainHash256, giving 256-bit intermediate state. For 2048-bit key (32 components, 8 rounds): effective security = 2048 bits.

func NewSeed256

func NewSeed256(bits int, hashFunc HashFunc256) (*Seed256, error)

NewSeed256 creates a new 256-bit seed with cryptographically random components.

bits must be a multiple of 256, in range [512, 2048]. Components count must be a multiple of 4 (4 per ChainHash256 round).

Example:

seed, err := itb.NewSeed256(2048, blake3Hash256)

func SeedFromComponents256

func SeedFromComponents256(hashFunc HashFunc256, components ...uint64) (*Seed256, error)

SeedFromComponents256 creates a 256-bit seed from existing uint64 values.

components length must be in range [8, 32] and a multiple of 4.

func (*Seed256) AttachLockSeed

func (s *Seed256) AttachLockSeed(ls *Seed256)

AttachLockSeed installs ls as the dedicated lockSeed for this noiseSeed. Subsequent Encrypt / Decrypt / EncryptAuthenticated / DecryptAuthenticated / EncryptStream / DecryptStream calls that take this seed as the noise slot route bit-permutation derivation through ls instead of through the receiver — the noise-injection channel still consumes the receiver's components and Hash, while the bit-permutation channel consumes BOTH ls's Components AND ls's Hash function, without changing any public Encrypt / Decrypt signature. The PRF primitive on the bit-permutation channel may therefore differ from the noise-injection channel's primitive within the same native width (the *Seed256 type signature here enforces width match), yielding keying-material isolation AND algorithm diversity for defence-in-depth on the overlay path.

Anti-conflation safeguards (each panics rather than silently degrading the entropy isolation):

• Self-attach (ls == ns) panics with ErrLockSeedSelfAttach: bit-permutation derivation would still consume the receiver's state, defeating the isolation purpose.
• Component-aliasing (ls.Components and the receiver's Components share the same backing array — typically because ls was built by copying the slice header rather than the underlying data) panics with ErrLockSeedComponentAliasing: a shared backing array means every encrypt-time mutation of either Components slice silently mutates the other, defeating the entropy isolation between the noise-injection and bit-permutation channels. The check is pointer-aliasing on the slice's first element, not value-equality — deep-copied slices that happen to carry identical uint64 values are not caught here.
• Post-Encrypt re-attach (this seed has been used in a successful Encrypt) panics with ErrLockSeedAfterEncrypt: switching the dedicated lockSeed mid-session breaks decryptability of pre-switch ciphertext.

Idempotent for the same ls (re-attaching the same pointer after validation does not panic). Both seeds remain fully independent objects — AttachLockSeed does not modify ls and does not copy any state between the two; it merely records a single pointer field on the receiver.

Not safe for concurrent invocation with an in-flight Encrypt / Decrypt on the same noiseSeed — caller serialises the attach sequence before dispatching parallel encrypt traffic.

func (*Seed256) AttachedLockSeed

func (s *Seed256) AttachedLockSeed() *Seed256

AttachedLockSeed returns the dedicated lockSeed previously installed via Seed256.AttachLockSeed, or nil when no lockSeed has been attached. Used internally by the bit-permutation derivation builders to route through the dedicated seed when present, and by serialization paths to extract the attached lockSeed alongside the noiseSeed for persistence.

func (*Seed256) BatchChainHash256

func (s *Seed256) BatchChainHash256(buf *[4][]byte) [4][4]uint64

BatchChainHash256 runs the four-way batched ChainHash256 via s.BatchHash. Output [i] matches serial ChainHash256(data[i]) under the same Components. Caller ensures s.BatchHash != nil (processChunk256 checks this before invoking).

func (*Seed256) Bits

func (s *Seed256) Bits() int

Bits returns the key size in bits.

func (*Seed256) ChainHash256

func (s *Seed256) ChainHash256(buf []byte) [4]uint64

ChainHash256 computes chained hash across all seed components with 256-bit state.

Each round consumes 4 components and the previous 256-bit output:

h = Hash256(data, [s[0], s[1], s[2], s[3]])
h = Hash256(data, [s[4]^h[0], s[5]^h[1], s[6]^h[2], s[7]^h[3]])
...

func (*Seed256) DetachLockSeed

func (s *Seed256) DetachLockSeed()

DetachLockSeed removes a previously-installed dedicated lockSeed pointer from this noiseSeed. See Seed128.DetachLockSeed for the full contract.

func (*Seed256) MinPixels

func (s *Seed256) MinPixels() int

MinPixels returns minimum pixel count ensuring encoding ambiguity (56^P) exceeds key space (2^keyBits). Formula: ceil(keyBits / log2(56)).

func (*Seed256) MinPixelsAuth

func (s *Seed256) MinPixelsAuth() int

MinPixelsAuth returns minimum pixel count ensuring encoding ambiguity (7^P) exceeds key space (2^keyBits) even under CCA. Formula: ceil(keyBits / log2(7)).

func (*Seed256) MinSide

func (s *Seed256) MinSide() int

MinSide returns minimum square container side length.

type Seed512

type Seed512 struct {
	Components []uint64
	Hash       HashFunc512
	// BatchHash is the optional 4-way batched counterpart of Hash. See
	// seed512_batch.go for the parity invariant and BatchHashFunc512
	// type. nil disables batched dispatch and preserves the legacy
	// single-call code path; non-nil routes processChunk512 through
	// BatchChainHash512 four pixels at a time.
	BatchHash BatchHashFunc512
	// contains filtered or unexported fields
}

Seed512 holds a dynamically-sized symmetric key with a pluggable 512-bit hash function.

Components are consumed 8 per round by ChainHash512, giving 512-bit intermediate state. For 2048-bit key (32 components, 4 rounds): effective security = 2048 bits.

func NewSeed512

func NewSeed512(bits int, hashFunc HashFunc512) (*Seed512, error)

NewSeed512 creates a new 512-bit seed with cryptographically random components.

bits must be a multiple of 512, in range [512, 2048]. Components count must be a multiple of 8 (8 per ChainHash512 round).

Example:

seed, err := itb.NewSeed512(2048, blake2b512)

func SeedFromComponents512

func SeedFromComponents512(hashFunc HashFunc512, components ...uint64) (*Seed512, error)

SeedFromComponents512 creates a 512-bit seed from existing uint64 values.

components length must be in range [8, 32] and a multiple of 8.

func (*Seed512) AttachLockSeed

func (s *Seed512) AttachLockSeed(ls *Seed512)

AttachLockSeed installs ls as the dedicated lockSeed for this noiseSeed. Subsequent Encrypt / Decrypt / EncryptAuthenticated / DecryptAuthenticated / EncryptStream / DecryptStream calls that take this seed as the noise slot route bit-permutation derivation through ls instead of through the receiver — the noise-injection channel still consumes the receiver's components and Hash, while the bit-permutation channel consumes BOTH ls's Components AND ls's Hash function, without changing any public Encrypt / Decrypt signature. The PRF primitive on the bit-permutation channel may therefore differ from the noise-injection channel's primitive within the same native width (the *Seed512 type signature here enforces width match), yielding keying-material isolation AND algorithm diversity for defence-in-depth on the overlay path.

Anti-conflation safeguards (each panics rather than silently degrading the entropy isolation):

• Self-attach (ls == ns) panics with ErrLockSeedSelfAttach: bit-permutation derivation would still consume the receiver's state, defeating the isolation purpose.
• Component-aliasing (ls.Components and the receiver's Components share the same backing array — typically because ls was built by copying the slice header rather than the underlying data) panics with ErrLockSeedComponentAliasing: a shared backing array means every encrypt-time mutation of either Components slice silently mutates the other, defeating the entropy isolation between the noise-injection and bit-permutation channels. The check is pointer-aliasing on the slice's first element, not value-equality — deep-copied slices that happen to carry identical uint64 values are not caught here.
• Post-Encrypt re-attach (this seed has been used in a successful Encrypt) panics with ErrLockSeedAfterEncrypt: switching the dedicated lockSeed mid-session breaks decryptability of pre-switch ciphertext.

Idempotent for the same ls (re-attaching the same pointer after validation does not panic). Both seeds remain fully independent objects — AttachLockSeed does not modify ls and does not copy any state between the two; it merely records a single pointer field on the receiver.

Not safe for concurrent invocation with an in-flight Encrypt / Decrypt on the same noiseSeed — caller serialises the attach sequence before dispatching parallel encrypt traffic.

func (*Seed512) AttachedLockSeed

func (s *Seed512) AttachedLockSeed() *Seed512

AttachedLockSeed returns the dedicated lockSeed previously installed via Seed512.AttachLockSeed, or nil when no lockSeed has been attached. Used internally by the bit-permutation derivation builders to route through the dedicated seed when present, and by serialization paths to extract the attached lockSeed alongside the noiseSeed for persistence.

func (*Seed512) BatchChainHash512

func (s *Seed512) BatchChainHash512(buf *[4][]byte) [4][8]uint64

BatchChainHash512 runs the four-way batched ChainHash512 via s.BatchHash. Output [i] matches serial ChainHash512(data[i]) under the same Components. Caller ensures s.BatchHash != nil (processChunk512 checks this before invoking).

func (*Seed512) Bits

func (s *Seed512) Bits() int

Bits returns the key size in bits.

func (*Seed512) ChainHash512

func (s *Seed512) ChainHash512(buf []byte) [8]uint64

ChainHash512 computes chained hash across all seed components with 512-bit state.

Each round consumes 8 components and the previous 512-bit output:

h = Hash512(data, [s[0], s[1], ..., s[7]])
h = Hash512(data, [s[8]^h[0], s[9]^h[1], ..., s[15]^h[7]])
...

func (*Seed512) DetachLockSeed

func (s *Seed512) DetachLockSeed()

DetachLockSeed removes a previously-installed dedicated lockSeed pointer from this noiseSeed. See Seed128.DetachLockSeed for the full contract.

func (*Seed512) MinPixels

func (s *Seed512) MinPixels() int

MinPixels returns minimum pixel count ensuring encoding ambiguity (56^P) exceeds key space (2^keyBits). Formula: ceil(keyBits / log2(56)).

func (*Seed512) MinPixelsAuth

func (s *Seed512) MinPixelsAuth() int

MinPixelsAuth returns minimum pixel count ensuring encoding ambiguity (7^P) exceeds key space (2^keyBits) even under CCA. Formula: ceil(keyBits / log2(7)).

func (*Seed512) MinSide

func (s *Seed512) MinSide() int

MinSide returns minimum square container side length.