mirror of https://github.com/jmcorgan/fips.git synced 2026-07-30 19:46:15 +00:00

Files

T

Johnathan Corgan 6c90cf6c02 Implement Tor transport with operator visibility

Add TorTransport in src/transport/tor/ supporting three operating modes:

Outbound (socks5 mode):
- Non-blocking SOCKS5 connect via tokio-socks with per-destination
  circuit isolation (IsolateSOCKSAuth)
- TorAddr enum for .onion and clearnet address types
- Connection pool with per-connection receive tasks, reuses TCP
  stream FMP framing
- connect_async()/connection_state_sync()/promote_connection() follow
  the same non-blocking polling pattern as TCP transport

Inbound (directory mode — recommended for production):
- Tor manages the onion service via HiddenServiceDir in torrc
- FIPS reads .onion address from hostname file at startup
- No control port needed — enables Tor Sandbox 1 (seccomp-bpf)
- Accept loop mirrors TCP pattern with DirectoryServiceConfig

Monitoring (control_port mode and optional in directory mode):
- Async control port client supporting TCP and Unix socket connections
  via Box<dyn AsyncRead/Write> trait objects
- AUTHENTICATE with cookie or password auth
- 8 GETINFO queries: bootstrap, circuits, traffic, liveness, version,
  dormant state, SOCKS listeners
- Background monitoring task polls every 10s, caches TorMonitoringInfo
  in Arc<RwLock> for synchronous query access
- Bootstrap milestone logging (25/50/75/100%), stall warning (>60s),
  network liveness transitions, dormant mode entry
- Directory mode optionally connects to control port when control_addr
  is configured (non-fatal on failure)

Operator visibility:
- show_transports query exposes tor_mode, onion_address, tor_monitoring
  (bootstrap, circuit_established, traffic, liveness, version, dormant)
- fipstop transport detail view: Tor mode, onion address, SOCKS5/control
  errors, connection stats, Tor daemon status section
- fipstop table view: tor(mode) label with truncated onion address hint

Security hardening:
- Per-destination circuit isolation via IsolateSOCKSAuth
- Unix socket default for control port (/run/tor/control)
- Reference torrc with HiddenServiceDir, VanguardsLiteEnabled,
  ConnectionPadding, DoS protections (PoW + intro rate limiting)

Config:
- TorConfig with socks5, control_port, and directory modes
- DirectoryServiceConfig: hostname_file, bind_addr
- control_addr, control_auth, cookie_path, connect_timeout,
  max_inbound_connections

Testing:
- 69 unit + integration tests with mock SOCKS5 and control servers
- Docker tests: socks5-outbound (clearnet via Tor) and directory-mode
  (HiddenServiceDir onion service)

Documentation:
- Transport layer design doc: Tor architecture, directory mode
- Configuration doc: Tor config tables and examples

2026-03-15 16:19:54 +00:00

5.1 KiB

Raw Blame History

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

DNS hostname support in peer addresses for UDP and TCP transports — addresses can now use host:port with either IP addresses or DNS hostnames (e.g., "peer1.example.com:2121"). DNS resolution with 60-second cache for UDP, one-shot resolution at connect time for TCP.
Tor transport with three operating modes:
- socks5 mode: outbound connections to .onion, clearnet IP, and clearnet hostname addresses via SOCKS5 proxy with per-destination circuit isolation (IsolateSOCKSAuth)
- directory mode: inbound via Tor-managed HiddenServiceDir onion service, enables Tor Sandbox 1 (seccomp-bpf)
- control_port mode: Tor daemon monitoring via async control port client with cookie and password authentication
- Optional control port monitoring in directory mode when control_addr is configured
- Docker integration tests for SOCKS5 outbound and directory-mode inbound
Tor operator visibility:
- Background monitoring task polling Tor daemon status every 10s
- show_transports query exposes tor_mode, onion_address, and tor_monitoring (bootstrap, circuits, liveness, traffic, version)
- fipstop Tor transport detail view with daemon status, connection stats, and truncated onion address in table view
- Bootstrap milestone logging (25/50/75/100%), stall warning, network liveness transitions, dormant mode alerts

[0.1.0] - 2026-03-12

Added (Initial Release)

Session Layer (FSP)

End-to-end encrypted datagram service between mesh nodes addressed by Nostr npub
Noise XK sessions with mutual authentication, replay protection, and forward secrecy
Automatic session rekeying with configurable time/message thresholds and drain window for in-flight packets
Port multiplexing for multiple services over a single session
Session-layer metrics: sender/receiver reports with RTT, jitter, delivery ratio, and burst loss tracking
Passive RTT measurement via spin bit

IPv6 Adapter

IPv6 adapter interface allowing tunneling TCP/IPv6 through FIPS mesh for traditional IP applications (TUN interface)
DNS resolver allowing IP applications to reach nodes by npub.fips name
Host-to-npub static mappings: resolve hostname.fips via host map populated from peer config aliases and /etc/fips/hosts file

Mesh Layer (FMP)

Self-organized core mesh routing protocol with adaptive least cost forwarding
Noise IK hop-by-hop link encryption with mutual authentication and replay protection between peer nodes
Distributed spanning tree construction with cost-based parent selection and adaptive reconfiguration
Destination route discovery via bloom filter-based directed search protocol
Path MTU discovery with per-link MTU tracking and MtuExceeded error signaling
Link-layer MMP: SRTT, jitter, one-way delay trends, packet loss, and ETX metrics
Link-layer heartbeat with configurable liveness timeout for dead peer detection
Epoch-based peer restart detection
Automatic link rekeying with K-bit epoch coordination and drain window
Static peer auto-reconnect with exponential backoff
Multi-address peers with transport priority-based failover
Msg1 rate limiting for handshake DoS protection

Mesh Peer Transports

UDP overlay transport with inbound and static outbound peer configuration
TCP overlay transport with listening port and static outbound peer support
Ethernet/WiFi transport (MAC address based, no IP stack) with optional automatic peer discovery and auto-connect

Operator Tooling

Ephemeral or persistent node identity with key file management
Unix domain control socket for runtime observability
fipsctl CLI tool for control socket interaction and node management
Comprehensive node and transport statistics via control socket
fipstop TUI monitoring tool with real-time session, peer, and transport configuration and metrics display

Packaging and Deployment

Debian/Ubuntu .deb packaging via cargo-deb
Systemd service packaging with tarball installer
OpenWRT package with opkg feed and init script
Docker sidecar deployment for containerized services
Build version metadata: git commit hash, dirty flag, and target triple embedded in all binaries via --version

Testing and CI

Comprehensive unit and integration tests covering all protocol layers and transports
Docker test harness with static and stochastic topologies
Chaos testing with simulated severe network conditions: latency, packet loss, reordering, and peer churn
CI with GitHub Actions: x86_64 and aarch64, integration test matrix, nextest JUnit reporting
Local CI runner script (testing/ci-local.sh)

Project

Design documentation suite covering all protocol layers
CHANGELOG.md following Keep a Changelog format
Repository mirrored to ngit

5.1 KiB Raw Blame History