rutcpduplex
Native Rust port of tcpduplex: encrypted full-duplex messaging over TCP using X25519 ECDH, AES-256-GCM, length-prefixed records, and concurrent read/write loops.
Protocol-compatible with the Go library:
- Go
tcpduplex↔ Rustrutcpduplex - Rust
rutcpduplex↔ Gotcpduplex
This is not TLS and does not replace certificate-based authentication on the public internet. It suits private networks, constrained environments, or protocols where you control both peers.
Requirements
- Rust 1.75+ (edition 2021)
- Optional: Go 1.22+ for Go ↔ Rust interoperability tests
Install
Or in Cargo.toml:
[]
= "0.1"
Features
- Duplex
Connwithsend/receive, bounded queues, max message size - Optional
on_messagecallback delivery path Config: dial/handshake timeouts, protocol version, queue depths, PSK + peer fingerprint hooksServer:listen+servewith per-connection handler- Submodules
protocol(framing),crypto(handshake + AES-GCM),transfer(encrypted resumable file transfers)
Quick start
Client
use dial;
let conn = dial?;
conn.send?;
let msg = conn.receive?;
println!;
conn.close?;
Server (manual accept)
use TcpListener;
use serve_conn;
let ln = bind?;
let = ln.accept?;
let conn = serve_conn?;
let msg = conn.receive?;
conn.send?;
conn.close?;
Server helper
use Server;
let srv = listen?;
srv.serve?;
PSK
use ;
let mut cfg = default_config;
cfg.handshake = HandshakeAuth ;
let conn = dial_with_config?;
Encrypted file transfer
use ;
use Arc;
// sender
send_file?;
// receiver
let meta = receive_file?;
While a transfer is running, do not use the same Conn for other send/receive traffic (frames share MsgText).
Wire format (summary)
- Handshake (plaintext) — Magic
TDX1,uint16BE protocol version, 32-byte X25519 public key. Client sends first; server replies with the same negotiated version and its public key. - Records —
uint32BE length (includes 1-byte type + sealed blob), type byte (MsgText,MsgPing,MsgPong,MsgClose), thennonce ‖ ciphertext ‖ tagfrom AES-256-GCM.
Key derivation matches Go tcpduplex:
- No PSK:
SHA256(shared_secret) - With PSK:
SHA256(shared_secret ‖ 0x00 ‖ len(psk) BE ‖ psk)
Examples
Building and testing
Go ↔ Rust compatibility tests (requires Go toolchain):
Project structure
rutcpduplex/
├── src/
│ ├── lib.rs # crate root
│ ├── config.rs # Config / HandshakeAuth
│ ├── conn.rs # duplex Conn
│ ├── dial.rs # dial / serve_conn
│ ├── server.rs # Server helper
│ ├── errors.rs
│ ├── fingerprint.rs
│ ├── protocol/ # framing + versioning
│ ├── crypto/ # ECDH handshake + AES-GCM session
│ └── transfer/ # resumable encrypted transfers
├── examples/
├── tests/
│ ├── integration.rs
│ ├── go_compat_tests.rs
│ └── go_compat/ # Go peer helper
├── Cargo.toml
├── LICENSE
└── README.md
Security notes
- Symmetric keys derive from ECDH; with
pre_shared_key, material is mixed on both sides — peers must agree on the secret. - Fingerprint pinning checks the peer’s ephemeral X25519 public key from the handshake (not a long-term identity certificate).
- For authentication + integrity + PKI on hostile networks, prefer TLS (or QUIC).
License
MIT — same family of licensing as other hdmain projects. The original Go tcpduplex repository did not include a LICENSE file at the time of this port; this crate is published under the MIT License.
See also
- Go library: https://github.com/hdmain/tcpduplex