186 lines
4.6 KiB
Markdown
186 lines
4.6 KiB
Markdown
# FIPS_DEPLOYMENT.md
|
|
|
|
## 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.
|
|
|
|
Tier-1 objective:
|
|
|
|
- Keep `nsigner` transport simple (`--listen tcp:127.0.0.1:PORT` or `--listen tcp:[::1]: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.
|
|
- Automatic caller->npub enrichment from FIPS session metadata.
|
|
|
|
---
|
|
|
|
## 2. Architecture
|
|
|
|
Two cooperating layers:
|
|
|
|
1. **Signer process layer** (`nsigner`)
|
|
- Listens on loopback TCP only.
|
|
- 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.
|
|
|
|
Conceptually:
|
|
|
|
`client app -> local FIPS endpoint -> FIPS mesh -> remote FIPS endpoint -> 127.0.0.1:PORT -> nsigner`
|
|
|
|
---
|
|
|
|
## 3. Prerequisites
|
|
|
|
On signer host/qube:
|
|
|
|
- Built `nsigner` binary.
|
|
- FIPS installed and running.
|
|
- Local firewall policy that keeps signer listener local-only.
|
|
|
|
On caller host/qube:
|
|
|
|
- FIPS installed and peered with signer host/qube.
|
|
- A client implementation that speaks `nsigner` framed JSON-RPC (see `documents/CLIENT_IMPLEMENTATION.md`).
|
|
|
|
Operational assumptions:
|
|
|
|
- Operator controls both endpoints.
|
|
- Manual verification of peer identity is performed in FIPS tooling before enabling signer traffic.
|
|
|
|
---
|
|
|
|
## 4. Start signer in Tier-1 TCP mode
|
|
|
|
Run `nsigner` in loopback TCP listen mode:
|
|
|
|
```bash
|
|
./build/nsigner --listen tcp:127.0.0.1:8080
|
|
```
|
|
|
|
Or IPv6 loopback:
|
|
|
|
```bash
|
|
./build/nsigner --listen tcp:[::1]:8080
|
|
```
|
|
|
|
Behavior notes:
|
|
|
|
- Non-loopback values are rejected by design.
|
|
- 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.
|
|
|
|
---
|
|
|
|
## 5. FIPS substrate wiring pattern
|
|
|
|
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.
|
|
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.
|
|
- `nsigner` receives framed request and returns framed response.
|
|
|
|
---
|
|
|
|
## 6. Minimal validation flow
|
|
|
|
### 6.1 Liveness check
|
|
|
|
From caller side, send a framed `get_public_key` request through the FIPS-backed endpoint.
|
|
|
|
Request JSON:
|
|
|
|
```json
|
|
{"id":"1","method":"get_public_key","params":[]}
|
|
```
|
|
|
|
Expected response:
|
|
|
|
```json
|
|
{"id":"1","result":"<hex_pubkey>"}
|
|
```
|
|
|
|
### 6.2 Signing check
|
|
|
|
Send `sign_event` with explicit role selector:
|
|
|
|
```json
|
|
{
|
|
"id": "2",
|
|
"method": "sign_event",
|
|
"params": ["<event_json>", {"role":"main"}]
|
|
}
|
|
```
|
|
|
|
Expected result: signed event JSON in `result`.
|
|
|
|
### 6.3 Negative check (policy)
|
|
|
|
Trigger a request path that requires prompt/denial and confirm client handles policy denial as a normal result path.
|
|
|
|
---
|
|
|
|
## 7. Security guardrails
|
|
|
|
- Keep listener loopback-only in Tier-1.
|
|
- 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.
|
|
- Preserve interactive approval where required by policy.
|
|
|
|
---
|
|
|
|
## 8. Troubleshooting
|
|
|
|
### 8.1 `invalid tcp listen target`
|
|
|
|
Cause:
|
|
- `--listen` argument does not match `tcp:HOST:PORT` or `tcp:[::1]:PORT`.
|
|
|
|
Fix:
|
|
- Use explicit loopback host and valid numeric port.
|
|
|
|
### 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`)
|
|
|
|
Cause:
|
|
- Client sent line-delimited/raw JSON instead of framed JSON.
|
|
|
|
Fix:
|
|
- Send 4-byte big-endian length prefix followed by exact UTF-8 JSON payload bytes.
|
|
|
|
### 8.4 FIPS path up, signer path down
|
|
|
|
Cause:
|
|
- FIPS session exists but forwarding/service mapping to signer loopback endpoint is missing.
|
|
|
|
Fix:
|
|
- Verify substrate service routing config and local endpoint mapping.
|
|
|
|
---
|
|
|
|
## 9. Next hardening steps (post Tier-1)
|
|
|
|
- Add automated two-node validation script for operator smoke checks.
|
|
- Add optional identity enrichment from FIPS session metadata (`peer_npub`).
|
|
- Introduce remote TCP mode only with mandatory TLS + authenticated caller key flow.
|