v0.0.7 - Allow TCP non-loopback IPv4/IPv6 binds for FIPS reachability
This commit is contained in:
Laan Tungir
@@ -2,17 +2,17 @@
|
||||
|
||||
## 1. Scope
|
||||
|
||||
This runbook covers a practical Tier-1 deployment of `nsigner` over a loopback TCP listener, with connectivity provided by FIPS as the network substrate.
|
||||
This runbook covers a practical Tier-1 deployment of `nsigner` over a TCP listener, with connectivity provided by FIPS as the network substrate.
|
||||
|
||||
Tier-1 objective:
|
||||
|
||||
- Keep `nsigner` transport simple (`--listen tcp:127.0.0.1:PORT` or `--listen tcp:[::1]:PORT`).
|
||||
- Keep `nsigner` transport simple (`--listen tcp:IPv4:PORT` or `--listen tcp:[IPv6]:PORT`).
|
||||
- Use FIPS to carry traffic between peers.
|
||||
- Do not add FIPS runtime dependencies into `nsigner`.
|
||||
|
||||
Out of scope in this document:
|
||||
|
||||
- Remote non-loopback TCP exposure (`--allow-remote`, TLS) planned for later phase.
|
||||
- Mandatory transport-level TLS/authentication hardening (still planned for a later phase).
|
||||
- Automatic caller->npub enrichment from FIPS session metadata.
|
||||
|
||||
---
|
||||
@@ -22,17 +22,17 @@ Out of scope in this document:
|
||||
Two cooperating layers:
|
||||
|
||||
1. **Signer process layer** (`nsigner`)
|
||||
- Listens on loopback TCP only.
|
||||
- Listens on operator-selected TCP endpoint (IPv4 or IPv6).
|
||||
- Uses existing 4-byte big-endian framed JSON-RPC protocol.
|
||||
- Keeps existing policy/prompt behavior.
|
||||
|
||||
2. **Network substrate layer** (FIPS)
|
||||
- Establishes peer connectivity between nodes/qubes.
|
||||
- Carries application traffic to a local loopback endpoint on each side.
|
||||
- Carries application traffic to the configured signer TCP endpoint.
|
||||
|
||||
Conceptually:
|
||||
|
||||
`client app -> local FIPS endpoint -> FIPS mesh -> remote FIPS endpoint -> 127.0.0.1:PORT -> nsigner`
|
||||
`client app -> local FIPS endpoint -> FIPS mesh -> remote FIPS endpoint -> signer TCP endpoint -> nsigner`
|
||||
|
||||
---
|
||||
|
||||
@@ -58,21 +58,21 @@ Operational assumptions:
|
||||
|
||||
## 4. Start signer in Tier-1 TCP mode
|
||||
|
||||
Run `nsigner` in loopback TCP listen mode:
|
||||
Run `nsigner` in TCP listen mode:
|
||||
|
||||
```bash
|
||||
./build/nsigner --listen tcp:127.0.0.1:8080
|
||||
./build/nsigner --listen tcp:[::]:8080
|
||||
```
|
||||
|
||||
Or IPv6 loopback:
|
||||
Or bind to a specific FIPS ULA address:
|
||||
|
||||
```bash
|
||||
./build/nsigner --listen tcp:[::1]:8080
|
||||
./build/nsigner --listen tcp:[fd00::1234]:8080
|
||||
```
|
||||
|
||||
Behavior notes:
|
||||
|
||||
- Non-loopback values are rejected by design.
|
||||
- Bind target is operator-controlled; pick the narrowest reachable address that satisfies your topology.
|
||||
- No TUI hotkey loop is required in TCP mode; process serves requests until terminated.
|
||||
- Caller identity is shown as a TCP endpoint descriptor in activity/prompt context.
|
||||
|
||||
@@ -82,14 +82,14 @@ Behavior notes:
|
||||
|
||||
Because FIPS deployment topologies vary, use this generic pattern:
|
||||
|
||||
1. Bind `nsigner` on loopback in signer environment.
|
||||
2. Configure FIPS service/forwarding so remote authenticated peer traffic is delivered to that loopback endpoint.
|
||||
1. Bind `nsigner` on a deliberate signer endpoint (`[::]:PORT` for broad reach, or specific `fd..` for tighter scope).
|
||||
2. Configure FIPS service/forwarding so remote authenticated peer traffic is delivered to that signer endpoint.
|
||||
3. On caller side, direct client traffic to the local FIPS ingress endpoint for that remote service.
|
||||
|
||||
Validation checklist:
|
||||
|
||||
- FIPS session is established between caller and signer nodes.
|
||||
- Transport path from caller -> signer loopback endpoint succeeds.
|
||||
- Transport path from caller -> configured signer endpoint succeeds.
|
||||
- `nsigner` receives framed request and returns framed response.
|
||||
|
||||
---
|
||||
@@ -134,7 +134,7 @@ Trigger a request path that requires prompt/denial and confirm client handles po
|
||||
|
||||
## 7. Security guardrails
|
||||
|
||||
- Keep listener loopback-only in Tier-1.
|
||||
- Prefer binding to a specific FIPS IPv6 ULA (`fd..`) rather than wildcard (`[::]`) when possible.
|
||||
- Do not expose signer port directly on LAN/WAN.
|
||||
- Keep FIPS peer allowlist tight; avoid broad trust domains.
|
||||
- Treat FIPS connectivity as transport, not authorization bypass.
|
||||
@@ -147,20 +147,12 @@ Trigger a request path that requires prompt/denial and confirm client handles po
|
||||
### 8.1 `invalid tcp listen target`
|
||||
|
||||
Cause:
|
||||
- `--listen` argument does not match `tcp:HOST:PORT` or `tcp:[::1]:PORT`.
|
||||
- `--listen` argument does not match `tcp:HOST:PORT` or `tcp:[IPv6]:PORT`.
|
||||
|
||||
Fix:
|
||||
- Use explicit loopback host and valid numeric port.
|
||||
- Use valid numeric port and valid IPv4/IPv6 literal host.
|
||||
|
||||
### 8.2 `non-loopback TCP bind denied`
|
||||
|
||||
Cause:
|
||||
- Attempt to bind non-loopback target in Tier-1 mode.
|
||||
|
||||
Fix:
|
||||
- Switch to `127.x.x.x` or `::1` target.
|
||||
|
||||
### 8.3 Framing parse failures (`parse_error`)
|
||||
### 8.2 Framing parse failures (`parse_error`)
|
||||
|
||||
Cause:
|
||||
- Client sent line-delimited/raw JSON instead of framed JSON.
|
||||
@@ -168,7 +160,7 @@ Cause:
|
||||
Fix:
|
||||
- Send 4-byte big-endian length prefix followed by exact UTF-8 JSON payload bytes.
|
||||
|
||||
### 8.4 FIPS path up, signer path down
|
||||
### 8.3 FIPS path up, signer path down
|
||||
|
||||
Cause:
|
||||
- FIPS session exists but forwarding/service mapping to signer loopback endpoint is missing.
|
||||
|
||||
Reference in New Issue
Block a user