mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-22 07:48:26 +00:00
Update README for current platform, transport, and example state
- Correct the transport matrix: UDP, TCP, and Tor work on Windows (previously shown as unsupported). Add an OpenWrt column with BLE disabled due to missing libdbus on the target. - Mention the `.fips` DNS resolver and outbound LAN gateway in the Features list, and add the gateway bullet under What works today. - Reframe the Linux DNS resolver setup: the `.deb` package now auto-configures the available backend; the manual resolvectl snippet is shown for tarball and manual installs. - Expand the Examples section to list all three example deployments (Nostr relay sidecar, K8s sidecar, macOS WireGuard sidecar) rather than only the macOS one. - Refresh Project Structure to include the `fips-gateway` binary, the full packaging list (macOS .pkg, Windows ZIP, OpenWrt ipk, AUR in addition to Debian and systemd tarball), and the examples directory. - Mention macOS `.pkg` and Windows ZIP/service packaging in the packaging line of What works today.
This commit is contained in:
64
README.md
64
README.md
@@ -44,8 +44,12 @@ endpoints.
|
|||||||
end-to-end session encryption (XK), with periodic rekey for forward secrecy
|
end-to-end session encryption (XK), with periodic rekey for forward secrecy
|
||||||
- **Nostr-native identity** — secp256k1 keypairs as node addresses, no
|
- **Nostr-native identity** — secp256k1 keypairs as node addresses, no
|
||||||
registration or central authority
|
registration or central authority
|
||||||
- **IPv6 adaptation** — TUN interface maps npubs to fd00::/8 addresses for
|
- **IPv6 adaptation** — TUN interface maps npubs to fd00::/8 addresses
|
||||||
unmodified IP applications; static hostname mapping (`/etc/fips/hosts`)
|
for unmodified IP applications; built-in `.fips` DNS resolver with
|
||||||
|
optional static hostname mapping (`/etc/fips/hosts`)
|
||||||
|
- **Outbound LAN gateway** — optional `fips-gateway` daemon lets
|
||||||
|
unmodified LAN hosts reach `.fips` destinations via a
|
||||||
|
DNS-allocated virtual IP pool and kernel nftables NAT
|
||||||
- **Metrics Measurement Protocol** — per-link RTT, loss, jitter, and goodput
|
- **Metrics Measurement Protocol** — per-link RTT, loss, jitter, and goodput
|
||||||
measurement with mesh size estimation
|
measurement with mesh size estimation
|
||||||
- **ECN congestion signaling** — hop-by-hop CE flag relay with RFC 3168 IPv6
|
- **ECN congestion signaling** — hop-by-hop CE flag relay with RFC 3168 IPv6
|
||||||
@@ -68,18 +72,21 @@ supported (see transport matrix below).
|
|||||||
|
|
||||||
### Transport support by platform
|
### Transport support by platform
|
||||||
|
|
||||||
| Transport | Linux | macOS | Windows |
|
| Transport | Linux | macOS | Windows | OpenWrt |
|
||||||
|-----------|:-----:|:-----:|:-------:|
|
|-----------|:-----:|:-----:|:-------:|:-------:|
|
||||||
| UDP | ✅ | ✅ | ❌ |
|
| UDP | ✅ | ✅ | ✅ | ✅ |
|
||||||
| TCP | ✅ | ✅ | ❌ |
|
| TCP | ✅ | ✅ | ✅ | ✅ |
|
||||||
| Ethernet | ✅ | ✅ | ❌ |
|
| Ethernet | ✅ | ✅ | ❌ | ✅ |
|
||||||
| Tor | ✅ | ✅ | ❌ |
|
| Tor | ✅ | ✅ | ✅ | ✅ |
|
||||||
| BLE | ✅ | ❌ | ❌ |
|
| BLE | ✅ | ❌ | ❌ | ❌ |
|
||||||
|
|
||||||
On **Linux**, the BLE transport requires BlueZ and libdbus. On
|
On **Linux**, the BLE transport requires BlueZ and libdbus. On
|
||||||
Debian/Ubuntu: `sudo apt install bluez libdbus-1-dev`. Then build with
|
Debian/Ubuntu: `sudo apt install bluez libdbus-1-dev`. Then build with
|
||||||
BLE enabled: `cargo build --release --features ble`.
|
BLE enabled: `cargo build --release --features ble`.
|
||||||
|
|
||||||
|
On **OpenWrt**, BLE is disabled because libdbus is not available on
|
||||||
|
the target. All other transports work and ship in the default ipk.
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
After building, choose one of the following methods to install.
|
After building, choose one of the following methods to install.
|
||||||
@@ -261,7 +268,11 @@ for the full reference.
|
|||||||
FIPS includes a DNS resolver (enabled by default, port 5354) that maps
|
FIPS includes a DNS resolver (enabled by default, port 5354) that maps
|
||||||
`.fips` names to fd00::/8 IPv6 addresses.
|
`.fips` names to fd00::/8 IPv6 addresses.
|
||||||
|
|
||||||
**Linux** (systemd-resolved):
|
**Linux**: The `.deb` package auto-detects and configures whichever
|
||||||
|
resolver is present (systemd dns-delegate, systemd-resolved, dnsmasq,
|
||||||
|
or NetworkManager with dnsmasq); no manual setup is needed. For
|
||||||
|
manual or tarball installs, point your resolver at `127.0.0.1:5354`
|
||||||
|
for the `fips` domain — e.g., with systemd-resolved:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
sudo resolvectl dns fips0 127.0.0.1:5354
|
sudo resolvectl dns fips0 127.0.0.1:5354
|
||||||
@@ -322,13 +333,20 @@ including static topology tests and stochastic chaos simulation.
|
|||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
|
|
||||||
- [examples/wireguard-sidecar-macos/](examples/wireguard-sidecar-macos/) -
|
- [examples/sidecar-nostr-relay/](examples/sidecar-nostr-relay/) —
|
||||||
Run a local WireGuard sidecar on macOS so `.fips` traffic can reach the mesh
|
Run a [strfry](https://github.com/hoytech/strfry) Nostr relay
|
||||||
through Docker.
|
reachable exclusively over the FIPS mesh. The relay container shares
|
||||||
|
the FIPS sidecar's network namespace and is isolated from the host
|
||||||
The macOS WireGuard sidecar only forwards FIPS IPv6 traffic destined for
|
network.
|
||||||
`fd00::/8` from `wg0` to `fips0`. Regular internet traffic does not transit the
|
- [examples/k8s-sidecar/](examples/k8s-sidecar/) — Run FIPS as a
|
||||||
sidecar and continues to use the host network normally.
|
Kubernetes Pod sidecar. The sidecar creates `fips0` in the Pod's
|
||||||
|
shared network namespace so every other container in the Pod gets
|
||||||
|
mesh access without modification.
|
||||||
|
- [examples/wireguard-sidecar-macos/](examples/wireguard-sidecar-macos/) —
|
||||||
|
Reach the FIPS mesh from a macOS host through a local Docker
|
||||||
|
container over a WireGuard tunnel. Only traffic destined for
|
||||||
|
`fd00::/8` transits the sidecar; regular internet traffic continues
|
||||||
|
to use the host network.
|
||||||
|
|
||||||
## Documentation
|
## Documentation
|
||||||
|
|
||||||
@@ -345,8 +363,9 @@ If you want to contribute, start with:
|
|||||||
## Project Structure
|
## Project Structure
|
||||||
|
|
||||||
```text
|
```text
|
||||||
src/ Rust source (library + fips/fipsctl/fipstop binaries)
|
src/ Rust source (library + fips/fipsctl/fipstop/fips-gateway binaries)
|
||||||
packaging/ Debian, systemd tarball, and shared packaging files
|
packaging/ Debian, macOS .pkg, Windows ZIP, OpenWrt ipk, AUR, systemd tarball
|
||||||
|
examples/ Deployment examples (Nostr relay, K8s sidecar, macOS WireGuard)
|
||||||
docs/design/ Protocol design specifications
|
docs/design/ Protocol design specifications
|
||||||
testing/ Docker-based integration test harnesses
|
testing/ Docker-based integration test harnesses
|
||||||
```
|
```
|
||||||
@@ -363,14 +382,17 @@ Ethernet, Tor, and Bluetooth (BLE) with a small live mesh of deployed nodes.
|
|||||||
- Noise IK (link layer) and Noise XK (session layer) encryption
|
- Noise IK (link layer) and Noise XK (session layer) encryption
|
||||||
- Periodic Noise rekey with hitless cutover for forward secrecy (FMP + FSP)
|
- Periodic Noise rekey with hitless cutover for forward secrecy (FMP + FSP)
|
||||||
- Persistent node identity with key file management
|
- Persistent node identity with key file management
|
||||||
- IPv6 TUN adapter with DNS resolution of `.fips` names
|
- IPv6 TUN adapter with built-in `.fips` DNS resolver and multi-backend
|
||||||
|
auto-configuration (systemd dns-delegate, systemd-resolved, dnsmasq,
|
||||||
|
NetworkManager)
|
||||||
- Static hostname mapping (`/etc/fips/hosts`) with auto-reload
|
- Static hostname mapping (`/etc/fips/hosts`) with auto-reload
|
||||||
- Per-link metrics (RTT, loss, jitter, goodput) and mesh size estimation
|
- Per-link metrics (RTT, loss, jitter, goodput) and mesh size estimation
|
||||||
- ECN congestion signaling (hop-by-hop CE relay, IPv6 CE marking, kernel drop detection)
|
- ECN congestion signaling (hop-by-hop CE relay, IPv6 CE marking, kernel drop detection)
|
||||||
- UDP, TCP, Ethernet, Tor, and BLE transports (BLE via L2CAP CoC with per-link MTU negotiation)
|
- UDP, TCP, Ethernet, Tor, and BLE transports (BLE via L2CAP CoC with per-link MTU negotiation)
|
||||||
|
- Outbound LAN gateway for unmodified hosts via DNS-allocated virtual IPs and nftables NAT
|
||||||
- Runtime inspection and peer management via `fipsctl` and `fipstop`
|
- Runtime inspection and peer management via `fipsctl` and `fipstop`
|
||||||
- Reproducible builds with toolchain pinning and SOURCE_DATE_EPOCH
|
- Reproducible builds with toolchain pinning and SOURCE_DATE_EPOCH
|
||||||
- Linux (Debian, systemd tarball, OpenWrt, AUR) and macOS packaging
|
- Linux (Debian, systemd tarball, OpenWrt, AUR), macOS (`.pkg`), and Windows (ZIP, service) packaging
|
||||||
- Docker-based integration and chaos testing
|
- Docker-based integration and chaos testing
|
||||||
|
|
||||||
### Near-term priorities
|
### Near-term priorities
|
||||||
|
|||||||
Reference in New Issue
Block a user