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

Files

T

ArjenandGitHub f624013b83 feat(openwrt): open !FIPS access SSID layer (#126 )

Access layer for phones and laptops to reach FIPS routers on OpenWrt,
stacked on the 802.11s mesh backhaul from #123. Squashed from five
commits by Arjen (Origami74); their original messages follow.

* feat(openwrt): open !FIPS access SSID — fips-ap-setup helper, default transport binding, how-to

Client access layer for phones and laptops: every FIPS router
broadcasts the same open SSID ('!FIPS' — the leading '!' sorts it to
the top of alphabetically ordered network pickers), forming one
standard ESS. Clients save it once and roam between all FIPS routers
natively, with FIPS's Noise IK handshake as the only security layer:

- fips-ap-setup: opt-in UCI helper that creates the 'fips-ap0' open AP
(encryption none — security type must be uniform across routers or
clients treat the ESS as different saved networks), an isolated
network with a static ULA /64, RA-only odhcpd addressing (stateless
SLAAC, no DHCP — the minimum that satisfies Android's provisioning
check; no internet by design, so phones keep cellular as default
route), and a locked-down fips_ap firewall zone (no path to br-lan
or the WAN; only ICMPv6, mDNS, and the FIPS transports reachable).
'remove' subcommand undoes it. Radio setup stays opt-in; a package
must not commandeer radios on install.
- fips.yaml: ship 'ap0'/'ap1' Ethernet-transport entries commented out
(matching the 802.11s mesh backhaul) so a stock install that never
creates fips-ap* logs no per-boot "interface missing" bind warning;
fips-ap-setup uncomments the matching block when it creates the
interface and re-comments it on remove.
- Regression test: extend shipped_openwrt_config_parses to assert the
ap0/ap1 entries ship commented out and still parse once uncommented,
alongside mesh0/mesh1.
- Packaging: install the helper in ipk/apk/buildroot (three synced
copies), extend CI structural checks and shellcheck targets.
- docs/how-to/set-up-open-access-ssid.md: full guide, including the
one-time 'no internet, stay connected' acceptance (stored per SSID,
covers every FIPS router) and the security-type-uniformity
constraint.

* docs(openwrt): correct open-SSID/mesh security framing — peering is open by design

The fips-ap-setup/fips-mesh-setup comments and both how-tos claimed a
stranger "cannot pass the FIPS handshake" / "their frames die at the
handshake" / the handshake surface "drops them". That is wrong: FIPS
peer admission is open. An inbound handshake from any net-new identity
is promoted (node::handlers::handshake::promote_connection), gated only
by the daemon's max-peers cap — there is no allowlist, no PSK, and the
AuthChallenge path is not wired to admission. The Noise IK handshake
provides authentication (no impersonation of another identity, no MITM),
not authorization.

Restate the model accurately in all five places: a stranger on the open
SSID (or the open mesh) can associate AND form a FIPS peer link — that
is the point of open access. Containment is the isolated fips_ap zone
(no path to br-lan or the WAN) plus the max-peers cap, not the
handshake. Clarify that AP client isolation is an L2 control only: a
peered stranger is an overlay peer like any other, so the FIPS overlay,
not L2, is the trust boundary between clients.

* feat(openwrt): serve DHCPv4 on the access SSID from a fixed roamable subnet

RA-only addressing satisfied Android's provisioning check but left
anything expecting IPv4 with a self-assigned address and a "no IP"
complaint. dnsmasq now leases out of 10.21.<N>.0/24 (N = radio index;
prefix echoes FIPS port 2121), deliberately identical on every router:
a roaming client keeps its lease across the ESS, and dnsmasq's
authoritative mode — the OpenWrt default, pinned by the helper — ACKs
the renew a foreign router never issued. Lease collisions across
routers surface as a NAK on renew and the client re-DHCPs.

The dhcp section's 'dhcpv4 server' is read by both dnsmasq (default
images) and odhcpd (only with maindhcp), so either arrangement serves.
A DHCPv4/udp-67 accept rule joins the fips_ap zone; DHCPv6 stays off,
the ULA RA stays as-is, and nothing depends on an upstream. The zone
remains isolated — no forwardings, no internet.

* feat(openwrt): enable mDNS rendezvous from fips-ap-setup

Phone FIPS apps cannot open raw-Ethernet sockets, so DNS-SD is how they
find the router's daemon — but node.rendezvous.lan defaults to off. Ship
the lan block commented in fips.yaml (consistent with the apN transport
entries) and have fips-ap-setup uncomment it when creating the access
SSID. The awk match is scoped to node.rendezvous because
transports.ethernet carries a 'lan' entry at the same indent. The switch
is daemon-wide, so 'remove' deliberately leaves it on rather than guess
whether other transports rely on it.

* fix(openwrt): bind UDP dual-stack [::]:2121 so access-SSID clients reach it

The shipped router config bound the UDP transport "0.0.0.0:2121" (IPv4
wildcard) while the mDNS LAN advert announces every interface address,
including the router's IPv6 link-local — which phones on the !FIPS
access SSID rightly prefer (their cellular default route swallows v4,
and fd00::/8 is captured by the Myco mesh TUN). Result: the client's
Noise msg1 arrives on an unbound v6 port and is silently lost; the
handshake resends and times out.

Symptom chain (observed on-device): mDNS resolve OK, platform push OK,
"Sent Noise handshake message 1" to [fe80::…%N]:2121, four resends, no
reply, 30 s stale-timeout.

OpenWrt is Linux (bindv6only=0), so "[::]" accepts IPv4 via v4-mapped
addresses too — nothing is lost. packaging/common is deliberately left
on "0.0.0.0" for now: Windows defaults IPV6_V6ONLY=1, where "[::]"
would drop v4 instead.

2026-07-22 20:02:20 -07:00

files

feat(openwrt): open !FIPS access SSID layer (#126 )

2026-07-22 20:02:20 -07:00

build-ipk.sh

feat(openwrt): open !FIPS access SSID layer (#126 )

2026-07-22 20:02:20 -07:00

Makefile

feat(openwrt): open !FIPS access SSID layer (#126 )

2026-07-22 20:02:20 -07:00

README.md

feat(openwrt): 802.11s open-mesh backhaul support

2026-07-16 05:48:04 +00:00

README.md

FIPS OpenWrt Package

This directory is an OpenWrt feed package that builds and installs FIPS on any OpenWrt 22.03+ router via the standard opkg package system.

For ad-hoc deployment without the build system, see deploy/native/ instead.

Package contents

Installed path	Purpose
`/usr/bin/fips`	Mesh daemon
`/usr/bin/fipsctl`	CLI control tool (`fipsctl show peers`, `fipsctl show links`, …)
`/usr/bin/fipstop`	Live TUI dashboard
`/usr/bin/fips-gateway`	Outbound LAN gateway service (not started by default)
`/usr/bin/fips-mesh-setup`	Opt-in helper — creates an open 802.11s mesh interface for router↔router backhaul
`/etc/init.d/fips`	procd service for the daemon (auto-start, crash respawn)
`/etc/init.d/fips-gateway`	procd service for the gateway (disabled by default)
`/etc/fips/fips.yaml`	Node configuration (edit before first start)
`/etc/fips/firewall.sh`	Firewall helper — accepts traffic on `fips0`
`/etc/dnsmasq.d/fips.conf`	Forwards `.fips` DNS queries to the daemon
`/etc/sysctl.d/fips-bridge.conf`	`br_netfilter` settings for Ethernet transport
`/etc/sysctl.d/fips-gateway.conf`	`proxy_ndp` and IPv6 forwarding for the gateway
`/etc/hotplug.d/net/99-fips`	Applies firewall rules when `fips0` comes up
`/etc/uci-defaults/90-fips-setup`	First-boot kernel module and firewall setup
`/lib/upgrade/keep.d/fips`	Preserves `/etc/fips/` across `sysupgrade`

Requirements

Build host

Requirement	Notes
OpenWrt SDK 22.03+	Older versions lack fw4 / nftables support
Rust host toolchain	Enable in `make menuconfig` → Advanced → Rust, or install rustup
Rust target for your router	Added automatically by the Makefile via `rustup target add`

Router

Requirement	Notes
`kmod-tun`	Required for `fips0` TUN interface
`kmod-br-netfilter`	Required for Ethernet transport on bridge member ports

Both kernel modules are listed as package dependencies (DEPENDS) and will be installed automatically by opkg.

Target architectures

The Makefile maps the OpenWrt ARCH variable to the correct Rust musl target:

OpenWrt `ARCH`	Rust target
`aarch64`	`aarch64-unknown-linux-musl`
`x86_64`	`x86_64-unknown-linux-musl`
`mipsel`	`mipsel-unknown-linux-musl`
`mips`	`mips-unknown-linux-musl`
`arm`	`arm-unknown-linux-musleabihf`

To add a missing architecture, add an ifeq block in Makefile mapping the OpenWrt ARCH value to the Rust target triple.

Building with the OpenWrt SDK

1. Obtain the SDK

Download the SDK for your router's target from downloads.openwrt.org and extract it.

2. Add this package

Copy or symlink this directory into the SDK's package/ tree:

# From inside the SDK root:
ln -s /path/to/fips/packaging/openwrt package/fips

Or add the FIPS repository as a feed in feeds.conf:

src-git-full fips https://github.com/jmcorgan/fips.git

Then update and install feeds:

./scripts/feeds update fips
./scripts/feeds install -a -p fips

3. Build

make package/fips/compile V=s

The resulting .ipk is placed in bin/packages/<arch>/.

4. Pin the source version

For reproducible production builds, replace PKG_SOURCE_VERSION:=master in Makefile with a specific commit SHA and set PKG_MIRROR_HASH to the correct hash (or keep skip for development):

PKG_SOURCE_VERSION:=bf117dfabc123...  # full 40-char SHA
PKG_MIRROR_HASH:=skip

Installing on the router

scp bin/packages/<arch>/fips_0.1.0-1_<arch>.ipk root@192.168.1.1:/tmp/
ssh root@192.168.1.1 opkg install /tmp/fips_0.1.0-1_<arch>.ipk

First-time configuration

Edit /etc/fips/fips.yaml on the router before starting the daemon:

ssh root@192.168.1.1
vi /etc/fips/fips.yaml

The default config enables:

Persistent identity (key generated on first start, saved to /etc/fips/fips.key)
TUN interface fips0
DNS responder on 127.0.0.1:5354
UDP transport on 0.0.0.0:2121

For Ethernet transport, uncomment the ethernet: section and set the correct physical interface names for your router. Always use physical port names (eth0, eth1, or DSA port names like wan/lan1), never bridge names (br-lan). The shipped default WAN port is eth0 (OpenWrt 24); on OpenWrt 25 (DSA) boards the WAN port is named wan — the .apk package ships that default. Run ip link show to confirm the names on your board. See deploy/native/README.md for details.

Service management

/etc/init.d/fips start
/etc/init.d/fips stop
/etc/init.d/fips restart
/etc/init.d/fips enable    # start at boot (already enabled by opkg postinstall)
/etc/init.d/fips disable

Outbound LAN gateway (optional)

The fips-gateway service is installed but disabled by default. It turns the router into an outbound gateway that bridges LAN clients onto the FIPS mesh. Enable only after configuring a gateway: section in /etc/fips/fips.yaml:

/etc/init.d/fips-gateway enable
/etc/init.d/fips-gateway start

See docs/tutorials/deploy-fips-gateway.md in the source tree for the full walkthrough.

Inspection and logs

# Node-level status overview
fipsctl show status

# Peer table
fipsctl show peers

# Transport links
fipsctl show links

# Active end-to-end sessions
fipsctl show sessions

# Live TUI dashboard
fipstop

# Daemon logs (OpenWrt syslog)
logread | grep fips

See docs/reference/cli-fipsctl.md for the full subcommand list.

Upgrading

Install the new .ipk over the existing one:

opkg install --force-reinstall fips_<new-version>_<arch>.ipk

The config in /etc/fips/fips.yaml and the identity key /etc/fips/fips.key are preserved by opkg (the yaml is installed as a conffile; the key is not a package file). Both survive sysupgrade via /lib/upgrade/keep.d/fips.