# omnivox-rs

Rust port of [OmniVox](https://git.0xfeedc0de.com/michael/OmniVox), a
templated encrypted TCP client-server library — **wire-compatible
byte-for-byte** with the original C++ implementation. A Rust client talks
to a C++ server and vice versa.

- Async TCP built on tokio
- ChaCha20-Poly1305 authenticated encryption (RFC 8439)
- scrypt key derivation (RFC 7914, `N = 2^17, r = 8, p = 1`)
- Byte-exact cereal `BinaryOutputArchive` field layout
- Zero `unsafe`

## Wire format

Framing is a `u32` little-endian length prefix. Each message is a
`AeadPacket`: `nonce[12] || tag[16] || u64 len || ciphertext`. Payloads
implement the `Cereal` trait, which reproduces cereal's raw-LE field
encoding (see `PARITY-CONTRACT.md` for the normative spec).

## Usage

```rust
use omnivox::{OmniVox, Cereal, CodecError, Decision, derive_encrypt_key};
```

Create an `OmniVox<T>` where `T: Cereal`, set the key (both peers must
agree), then use `start_server` / `connect_to_server` / `send_to_client`
/ `send_to_server`. Runnable ports of the original demo apps live in
`examples/`.

## Parity

`PARITY-CONTRACT.md` is the definition of done: it names the unit of
parity, the accepted differences, and the original's quirks this port
deliberately preserves (B1–B3, B5) rather than silently fixing. Parity
evidence:

- `tests/vectors.rs` — golden vectors generated by the C++ CryptoPP +
  cereal stack (`reference/cppgen.cpp`); keys, serialization bytes, and
  AEAD ciphertext/tags must match exactly.
- `tests/loopback.rs` — runtime behavior clauses of the contract.
- Differential cross-tests: this crate's binaries were verified talking
  to the unmodified C++ binaries in both directions over loopback.

## Build & test

```bash
cargo test          # note: the scrypt vectors use N=2^17 (~1 s, 128 MiB per derivation)
cargo clippy --all-targets
cargo run --example omnivox-server   # terminal 1
cargo run --example omnivox-client   # terminal 2
```

## License

GPL-3.0-or-later, matching the original OmniVox.