101 lines
3.6 KiB
Markdown
101 lines
3.6 KiB
Markdown
# Direct Worker WSS TLS / PKI
|
|
|
|
Archived status: this document captures a direct-worker WSS trust design track
|
|
and is no longer the primary reference for node-to-node transport. The active
|
|
fabric transport model is QUIC-only between nodes; see
|
|
`docs/architecture/DISTRIBUTED_FABRIC_NODE_PROTOCOL_PLAN.md`,
|
|
`docs/architecture/FABRIC_FIRST_TRANSPORT_AND_STRESS_PLAN.md`, and
|
|
`docs/architecture/SECURE_ACCESS_FABRIC_TARGET.md`.
|
|
|
|
Status: P3.4 trust-model design/prep complete.
|
|
|
|
This document defines the production trust model for direct worker WSS. It does
|
|
not implement mesh, relay nodes, VPN, QUIC, WebRTC, or a new RDP runtime.
|
|
|
|
Detailed P3.4 production certificate lifecycle, worker identity binding, client
|
|
trust, rotation, revocation, and future smoke plan are defined in
|
|
`docs/architecture/PRODUCTION_DIRECT_WORKER_WSS_TRUST.md`.
|
|
|
|
## Goal
|
|
|
|
Direct worker WSS is the preferred RDP realtime data-plane path. In production,
|
|
the Access Client must only use direct worker WSS when both conditions are true:
|
|
|
|
- the backend advertises the candidate as production trusted
|
|
- normal TLS certificate validation succeeds
|
|
|
|
The backend gateway remains the safe fallback/debug path.
|
|
|
|
## Trust Modes
|
|
|
|
Backend config `DATA_PLANE_DIRECT_WORKER_TLS_TRUST_MODE` supports:
|
|
|
|
- `smoke_insecure`: development/smoke only; candidate metadata is
|
|
`smoke_only=true` and `production_trusted=false`
|
|
- `public_ca`: worker certificate chains to an OS/publicly trusted CA;
|
|
candidate metadata is `production_trusted=true`
|
|
- `platform_ca`: worker certificate chains to a platform-managed CA;
|
|
candidate metadata is `production_trusted=true`
|
|
|
|
Optional `DATA_PLANE_DIRECT_WORKER_TLS_CA_REF` labels the platform CA or trust
|
|
bundle version in candidate metadata, for example `rap-platform-ca:v1`.
|
|
|
|
## Backend Enforcement
|
|
|
|
In production (`APP_ENV=production` or `APP_ENV=prod`):
|
|
|
|
- backend must not advertise `direct_worker_wss` candidates when
|
|
`DATA_PLANE_DIRECT_WORKER_TLS_TRUST_MODE=smoke_insecure`
|
|
- backend still advertises `backend_gateway` fallback when configured
|
|
- direct candidates include trust metadata only when they are data-capable
|
|
|
|
Candidate metadata:
|
|
|
|
```json
|
|
{
|
|
"runtime_transport": "json_v1",
|
|
"traffic_ready": true,
|
|
"tls_trust_mode": "platform_ca",
|
|
"production_trusted": true,
|
|
"smoke_only": false,
|
|
"tls_ca_ref": "rap-platform-ca:v1"
|
|
}
|
|
```
|
|
|
|
## Windows Client Enforcement
|
|
|
|
Client config `environment=production` or `prod` means:
|
|
|
|
- smoke-only direct candidates are skipped
|
|
- candidates without production trust metadata are skipped
|
|
- `allow_insecure_direct_data_plane_tls_for_smoke` is ignored for direct worker
|
|
WSS
|
|
- the client falls back to backend gateway instead of weakening TLS
|
|
|
|
In development/smoke:
|
|
|
|
- `allow_insecure_direct_data_plane_tls_for_smoke=true` may bypass certificate
|
|
validation only for smoke-only direct candidates
|
|
- this bypass must not be used as a production trust mechanism
|
|
|
|
## Worker Requirements
|
|
|
|
The worker direct WSS endpoint already requires:
|
|
|
|
- `RDP_WORKER_DATA_PLANE_TLS_CERT_FILE`
|
|
- `RDP_WORKER_DATA_PLANE_TLS_KEY_FILE`
|
|
- `RDP_WORKER_DATA_PLANE_PUBLIC_KEY_FILE` or
|
|
`RDP_WORKER_DATA_PLANE_PUBLIC_KEY_PEM`
|
|
|
|
Production workers should use certificates issued for their advertised direct
|
|
WSS hostname/IP subject alternative names. Platform-managed deployments should
|
|
prefer a dedicated platform CA and rotation workflow.
|
|
|
|
## Remaining Work
|
|
|
|
- implement app-local platform CA trust bundle handling in Windows clients
|
|
- automate worker certificate issuance/rotation
|
|
- rotate backend data-plane signing keys
|
|
- add live test-stand proof with `platform_ca` production-trusted direct WSS
|
|
- later integrate node-agent certificate enrollment
|