michael
268b986bb9
Byte-exact cereal binary layout, RFC 8439 ChaCha20-Poly1305, RFC 7914 scrypt defaults; tokio transport preserving the original's observable behavior (contract B1-B3, B5 quirks included). Parity evidence: golden C++ vectors in tests/vectors.rs and loopback behavior tests; both cross-directions verified against the unmodified C++ binaries. Source: https://git.0xfeedc0de.com/michael/OmniVox
57 lines
2.0 KiB
Markdown
57 lines
2.0 KiB
Markdown
# 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. |