Skip to content

Appliance enrollment (accepted Phase 5 correction)

Phase 5 onboarding is operator-accepted. The qualification record is a historical checkpoint; current status is in the Server ledger.

One operator-generated, six-character code enrolls one independent Server with full appliance API access, including existing/future decoded streams, raw IQ, diagnostics and controls. It does not bypass receiver/job ownership, add an OS shell or activate Phase 6 ingestion. Existing narrow credentials remain narrow.

Protocol and lifecycle decisions

/ws/pair, rfsentry-pair-v2, is a bounded native bootstrap exchange on the configured appliance API TLS listener. Normal control/record/IQ TLS verification is unchanged. Only the fixed bootstrap client quarantines an initially untrusted certificate; it accepts no trust/credentials until PAKE confirmation. Browser certificate verification is never disabled. Native pairing omits Origin and rejects any browser Origin; ordinary control/record/IQ browser requests retain the existing exact appliance-origin checks.

Use pinned BoringSSL SPAKE2+ P256/SHA256/HKDF-SHA256/HMAC-SHA256 (RFC 9383), including its scrypt registration profile, behind a C++20 opaque wrapper with prefixed symbols. OpenSSL remains the TLS implementation. Qualification includes the independent RFC Appendix C vector and malformed/key-confirmation/context tests. No custom elliptic-curve/password primitive is introduced.

The Server is the prover; the appliance is the verifier. Their fixed role names are bound by registration. Canonical context binds protocol/suite, both stable UUIDs, full-appliance authority, the grant nonce, canonical appliance endpoint, the actual TLS leaf-certificate SHA-256 and a 64-byte TLS exporter computed on each side of that same connection. Version 2 also binds the Server CSR, persistent enrollment public key, exact requested SANs and appliance root fingerprint. Never accept an exporter supplied by the peer instead of computing it locally. Shares are 65 bytes; confirmations are 32 bytes.

Temporary grants expire after five minutes, permit at most five initiated attempts, and are replaced by a new rfsentry-jobctl pair-create. There is one active grant and bounded cryptographic work; it expires on gateway restart. Code creation and grant/credential revocation require operator/full control permission. No grant is job-specific, and no discovery or pairing operation wakes hardware. Codes are shown only in the authorized command response, not URLs or diagnostic logs. Discovery advertisements carry only public identity.

After verifying the appliance confirmation, the Server derives a strong token from the PAKE key with a distinct credential KDF label. It saves the pending registration/token/trust privately before sending its confirmation. The appliance verifies that confirmation, signs the proved CSR through its network-isolated constrained issuer, and atomically persists the token hash, enrollment public key, approved SAN set and explicit full-appliance grant associated with this Server UUID. It then consumes the code and replies with the public leaf/chain. No Server TLS/enrollment private key leaves that Server, and no appliance CA private key enters a network-facing service. A lost commit reply is recoverable using the privately saved token and verified normal TLS; it does not require exposing another code or copying an operator credential. Pending state is bounded and secret-redacted. Successful enrollment commits the Server registration only after normal authenticated identity verification.

Credential publication distinguishes a confirmed failure before publication from an uncertain result after rename. A post-rename failure returns certificate-publication-uncertain with credentialCommitted: null; it never authorizes deletion of the pending token or enrollment key. The appliance reconciles the current file under its writer lock, preserves revision/digest checks for concurrent edits, and retries file/directory synchronization before admitting a changed credential. Unchanged, previously durable credentials can continue during that recovery. Retry, reload and startup use the observed configuration; they do not overwrite it with an older candidate. An uncertain publication retires its one-time code, while verified recovery reuses the saved token and signing key. A synchronization failure is never reported as success.

Enrollment and renewal issuer I/O runs on one C++ worker with four total queued/running/completed slots. A 35-second whole-request deadline includes queue time and partial socket transfers. The worker owns no libwebsockets peer pointer or pairing lock. The reactor rechecks request/connection identity, credential generation, cancellation and expiry before applying or delivering completion; queued certificate replies are also fenced at delivery. Issuer response identities must match the approved request and trust root. Unrelated control and record delivery continue while the issuer is waiting. One fresh code also rotates an existing grant for that same Server UUID: replace only its full-access credential atomically, preserve its registration/policies, and invalidate old authenticated connections. Other Server grants and narrow readers remain unchanged. Explicit revocation remains available separately.

After PAKE confirmation, a definitive issuer/credential-write rejection is returned on that same exporter-bound connection with a bounded safe error code, message, matching CSR request ID and credentialCommitted=false. The Server accepts it only after verifying the appliance proof. Its pending state then retains the reason, discards the unused token/enrollment key and requires a code-bearing retry after correction. An interrupted exchange without that definitive response remains resumable: absence of a reply never proves the appliance did not commit. A confirmed rejection does not consume the code or replace any prior grant. Browser/API pending status exposes only public fields.

Administration defaults to anonymous HTTPS on 0.0.0.0:8445 for fresh installs, as explicitly selected by the operator. Anonymous-mode mutations still require an exact Origin and bounded same-site CSRF session. Authentication/roles are opt-in; enabling them creates a valid administrator atomically. Legacy instance migration preserves its prior auth/listener policy, identity and credentials.

The independent Server generates a provisional private authority and listener key in C++, even without a paired appliance. Pairing replaces only the public listener chain with an appliance-issued leaf, while retaining the local key. The running Server activates that chain immediately for new connections while established administration connections complete on their existing TLS session. The appliance browser proxy verifies paired Servers through the appliance root, not a renewable Server leaf pin; unrelated self-signed Servers still require explicit certificate review. Clients install the appliance root once from /trust/; it validates the appliance and every Server it approves. A separate Server-held enrollment key renews the same approved identities even after the prior leaf expires. Name expansion, enrollment-key loss or revocation requires explicit re-pairing.

Qualification

The onboarding record preserves source-specific results, regressions and limitations. Current Server acceptance is separate from future platform/trust gates. Run the existing isolated onboarding and installed qualification workflows for affected source; a protocol description is not proof.