mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-30 07:37:36 +00:00
Johnathan Corgan
f8d79c2d8c
The configuration reference, the shipped fips.yaml and two code comments said that setting dns.bind_addr to "::" exposes the responder to mesh peers. On Linux, macOS and FreeBSD with the daemon's own TUN, queries arriving on the mesh interface are dropped, so a wildcard bind in fact serves the host's other networks, and every host on them that can reach the port. They now say that, and that mesh peers are served on Windows, with an application-supplied TUN, or when the daemon logs at start that the mesh interface index is unresolved. The reference and fips.yaml also say that a reply goes to the query's source by the routing table, so a host on one of those networks that forges a mesh source address has the reply sent into the mesh from this node's mesh address. The macOS WireGuard container example published the container's DNS port on every host interface. It is now published on 127.0.0.1 only, which is all the macOS resolver it serves needs.
140 lines
5.2 KiB
Markdown
140 lines
5.2 KiB
Markdown
# WireGuard Sidecar For macOS
|
|
|
|
This example lets macOS reach the FIPS mesh through a local Docker container.
|
|
|
|
## Files
|
|
|
|
- `fips-on.sh`: user-facing startup wrapper
|
|
- `fips-host.sh`: small privileged helper for macOS networking
|
|
- `fips-off.sh`: teardown wrapper
|
|
- `entrypoint-sidecar.sh`: container startup logic
|
|
- `identity/fips.key` and `identity/fips.pub`: generated persistent sidecar identity
|
|
- `fips.yaml`: FIPS node config used inside the container
|
|
|
|
## Prerequisites
|
|
|
|
`fips-on.sh` generates the sidecar identity with `fipsctl` from the `fips-test:latest` image, which this example's `docker-compose.yml` does not build. Build it once from the repo root before the first run:
|
|
|
|
```bash
|
|
./testing/scripts/build.sh
|
|
```
|
|
|
|
## Configure Peers
|
|
|
|
Before first use, replace the placeholder bootstrap peer in `fips.yaml` with a real peer for the mesh you want to join.
|
|
|
|
## Startup Flow
|
|
|
|
```text
|
|
macOS user fips-on.sh Docker / wireguard-sidecar fips-host.sh (sudo)
|
|
| | | |
|
|
| ./fips-on.sh | | |
|
|
|---------------> | | |
|
|
| | generate fips.key | |
|
|
| | generate client keys | |
|
|
| |----------------------->| bind-mount identity/ |
|
|
| | start/recreate container |
|
|
| |----------------------->| entrypoint starts |
|
|
| | | generate server keys |
|
|
| | | wait for client.pub |
|
|
| | | bring up wg0 |
|
|
| | poll `wg show wg0` | |
|
|
| |<-----------------------| |
|
|
| | sudo fips-host.sh on | |
|
|
| |------------------------------------------------->|
|
|
| | | write /etc/wireguard |
|
|
| | | wg-quick up fips0 |
|
|
| | | write /etc/resolver/fips |
|
|
| | | flush DNS |
|
|
| |<-------------------------------------------------|
|
|
| ready | | |
|
|
```
|
|
|
|
## What `fips-on.sh` Does
|
|
|
|
1. Creates `identity/` and `identity/wireguard/` if needed.
|
|
2. Generates `identity/fips.key` and `identity/fips.pub` with `fipsctl keygen --dir /etc/fips` if the sidecar does not already have a persistent identity.
|
|
3. Generates the host WireGuard client keypair if missing.
|
|
4. Fixes ownership on the generated client key files so the Docker bind mount stays readable on macOS.
|
|
5. Starts `wireguard-sidecar` with `docker compose up -d --build --force-recreate`.
|
|
6. Waits until the container has created and brought up `wg0`.
|
|
7. Calls the privileged helper to configure host networking:
|
|
- writes `/etc/wireguard/fips0.conf`
|
|
- runs `wg-quick up fips0`
|
|
- writes `/etc/resolver/fips`
|
|
- flushes macOS DNS caches
|
|
|
|
## What Happens In The Container
|
|
|
|
`entrypoint-sidecar.sh`:
|
|
|
|
1. Generates the server WireGuard keypair on first run.
|
|
2. Waits briefly for `identity/wireguard/client.pub` from the host.
|
|
3. Writes the container-side `wg0` config.
|
|
4. Brings up `wg0` on UDP port `51820`.
|
|
5. Starts `fips --config /etc/fips/fips.yaml` using the bind-mounted `identity/fips.key`.
|
|
6. Enables forwarding and NAT66 from `wg0` toward `fips0` for FIPS
|
|
`fd00::/8` destinations only.
|
|
|
|
Only FIPS traffic for `fd00::/8` is forwarded through the sidecar. Regular
|
|
internet traffic still uses the macOS host network and does not route through
|
|
`wg0` or `fips0`.
|
|
|
|
The container's DNS port 5354 is published on `127.0.0.1` only, for the macOS
|
|
resolver that `/etc/resolver/fips` points at, and not to the network.
|
|
|
|
## Sidecar FIPS Identity
|
|
|
|
`fips-on.sh` generates `identity/fips.key` and `identity/fips.pub` on first run by calling:
|
|
|
|
```bash
|
|
docker run --rm \
|
|
--entrypoint fipsctl \
|
|
-v "$PWD/identity:/etc/fips" \
|
|
fips-test:latest \
|
|
keygen --dir /etc/fips
|
|
```
|
|
|
|
That key is then bind-mounted into `/etc/fips/fips.key`, so the sidecar keeps
|
|
the same FIPS identity even though `fips-on.sh` uses `docker compose up
|
|
--force-recreate`.
|
|
|
|
Delete `identity/fips.key` if you want the next `./fips-on.sh` run to create a
|
|
fresh sidecar identity.
|
|
|
|
## Why `sudo` Is Still Needed
|
|
|
|
Only `fips-host.sh` needs root, because macOS requires it for:
|
|
|
|
- `/etc/wireguard/fips0.conf`
|
|
- `/etc/resolver/fips`
|
|
- `wg-quick up/down`
|
|
- DNS cache flushes
|
|
|
|
Everything else runs as the normal user.
|
|
|
|
## Teardown
|
|
|
|
Run:
|
|
|
|
```bash
|
|
./fips-off.sh
|
|
```
|
|
|
|
This:
|
|
|
|
1. Calls `sudo ./fips-host.sh off` to remove the host WireGuard and DNS config.
|
|
2. Stops the Docker container.
|
|
|
|
## Generated Files
|
|
|
|
These are local runtime artifacts under `identity/` and should not be committed:
|
|
|
|
- `identity/fips.key`
|
|
- `identity/fips.pub`
|
|
- `identity/wireguard/client.key`
|
|
- `identity/wireguard/client.pub`
|
|
- `identity/wireguard/server.key`
|
|
- `identity/wireguard/server.pub`
|
|
- `identity/wireguard/wg0.conf`
|