julian
7db5cfa0e4
The string protocol (UDP 60001) has no password field but can fire relays
("11" = relay 1 on), bypassing relay_pw entirely. Proven on hardware: an
unauthenticated packet opened a relay. harden() had left it enabled "for
status reads".
- #status() now reads via the authenticated binary command (relay cmd 0x00)
instead of the string protocol, so the string protocol is no longer needed.
- harden() disables the string protocol (udp2.p=255). BEST-EFFORT: firmware
V3.6J's config API silently refuses to disable udp2 (the device web UI can),
so it's not part of the blocking verify -- harden() re-checks and returns a
warning instead of throwing. After a web-UI disable, the attack is dead and
binary control/status still work (verified on hardware).
- HardenResult gains an optional `warnings[]`; the assign route surfaces them
to the admin and logs them.
- Corrected the false comment claiming relay_pw stops an attacker (it is
defence-in-depth on plaintext UDP, not a boundary).
- Thread localAddress through the driver's UDP/HTTP calls so a multi-homed
host sources device traffic from the device-facing NIC.
- Device web login (webUser/webPassword) is no longer redacted from setup
state -- it's an operational credential for the admin-only device area;
pushPassword/relayPassword stay machine-only.
Wiki: document the vuln + fix, the firmware caveat, and the out-of-band
actuation gap (the log captures host actions only; reconciliation vs. an
independent witness is the real control and is not yet built).
146 lines
9.6 KiB
Markdown
146 lines
9.6 KiB
Markdown
---
|
||
type: entity
|
||
tags: [parking, hardware, access-control, relay]
|
||
sources: []
|
||
updated: 2026-06-14
|
||
---
|
||
|
||
# Dingtian Relay Controller
|
||
|
||
A network **relay + input** board (the unit on hand is the **4-channel** variant: 4 relays + 4
|
||
inputs). Chosen to drive the entry/exit lane because — unlike the [[uhppote-controller]] — its
|
||
**inputs are independent of its relays**, which solves the [[access-controller-button-flow]]
|
||
blocker (a button on an input does not auto-open a relay; the host decides).
|
||
|
||
SDK: `dingtian/4ch/sdk_v2_0_0/` (programming manual, examples). MIT-compatible use; no vendor
|
||
runtime needed.
|
||
|
||
## ⚠️ The one gotcha: `input_link_relay`
|
||
|
||
By **default the device links each input to auto-fire its matching relay** (`input_link_relay: 1`,
|
||
`on_action_on: [[0],[1],…]` in the config) — i.e. the *same* auto-open problem as the UHPPOTE.
|
||
The difference: **it is configurable.** Set `input_link_relay: 0` (or clear the action mappings)
|
||
so an input only *reports* and the host commands the relay. **This config step is mandatory** for
|
||
the ticket-first entry flow. See [[autonomous-direction]].
|
||
|
||
## Protocol (Dingtian string — what we use)
|
||
|
||
Transport options: UDP/TCP string, UDP binary, HTTP CGI, Modbus, MQTT. We use **HTTP + UDP** —
|
||
see [[dingtian-vs-mqtt]].
|
||
|
||
- **Relay control — UDP *binary*, port 60000 (authenticated):** the driver's `pulseOpen` sends a
|
||
binary "write relay with jogging" frame carrying the `relay_pw` (the only relay option with a
|
||
password). Frame (verified on hardware):
|
||
`FF AA <session> 03 <pwLo> <pwHi> <relayByte> <jogLo> <jogHi>` — relayByte bit0=on, bits1-7=
|
||
channel-1; jog is 100 ms units, LSB-first; password 16-bit LSB-first (0 = none). The relay jogs
|
||
ON then auto-releases, so we never time a close ([[barrier-not-a-door]]). *(The simpler string
|
||
protocol — `1`+ch on, `2`+ch off, `11*` jog — works too but has no auth; we use it only for the
|
||
read-only status query.)*
|
||
- **Status / inputs — send `00`** → `「relays」:「inputs」:「count」`, e.g. **`0000:1111:4`** (4ch:
|
||
relays off, inputs high). `0` = OFF/Low, `1` = ON/High. Poll-based.
|
||
- **Input push — `input_link_url`:** device **HTTP POSTs to a host URL on input change** — the
|
||
push path for button events without a broker.
|
||
- **Discovery:** UDP multicast `224.0.2.11:60000`, send `\x05\xAA` (devices reply). Defaults:
|
||
IP `192.168.1.100`, UDP `60000` (binary) / `60001` (string).
|
||
- Binary protocol (port 60000) adds optional **password** + multicast; bitmask relay/input maps.
|
||
|
||
## Driver & config API
|
||
|
||
The `dingtian` driver ([[device-registry]]) implements three capabilities:
|
||
`AccessControlDevice` (relay pulse/latch over UDP), `InputDevice` (read inputs + poll-based
|
||
press/release events ~50 ms), and `PreconditionDevice` (below). Config fields include a separate
|
||
**`httpPort`** — the device's web/config API is on a configurable HTTP port (default **80**),
|
||
distinct from the UDP control port 60001.
|
||
|
||
### Precondition: input_link_relay must be OFF
|
||
|
||
The driver reads the device's JSON config (`GET /api/v2/config.cgi`) and **checks
|
||
`input_link_relay`**; if enabled it reports a fixable issue, and `fixPreconditions()` writes the
|
||
correction (`POST /api/v2/config_set.cgi`) — setting the flag to 0 and clearing `on_action_on`,
|
||
preserving everything else (network, etc.). This is the generic [[device-registry|precondition]]
|
||
capability: the app doesn't own full device config (that's the vendor web UI), only the few
|
||
settings our flow depends on.
|
||
|
||
> **Write gotcha (cost real debugging):** the GET config payload **omits** a `"command"` field, but
|
||
> the set endpoint **requires `"command":"setconfig"`** injected right after `"status"`. Without it
|
||
> the POST returns/looks like success but silently does nothing (and the device may reset). With it,
|
||
> POST returns `{"status":0}` and the change sticks. JSON node order must be preserved.
|
||
|
||
## Input push (no polling) — the chosen architecture
|
||
|
||
The device **pushes** button events to the backend; the backend decides. **No polling.** The
|
||
driver's `configureInputPush()` writes the device's `input_link_url` config to point each input at
|
||
the backend: input N HTTP-GETs `…/api/devices/dingtian/<deviceId>/input/<N>/on` (and `/off`) on
|
||
press/release. The backend ([[fastify]] route `routes/devices.ts`) translates each push into an
|
||
internal device event ([[device-input-flow]]); the entry flow then prints a ticket and commands
|
||
the relay via UDP. See [[device-input-flow]] for the full path + trust model.
|
||
|
||
> The input-poll path in the driver (`onInput`) remains as a dev/fallback aid, but **push is the
|
||
> real path** — lower latency, and it can be authenticated (the device supports Basic/Digest +
|
||
> HTTPS on the push), unlike the open UDP control direction.
|
||
|
||
### What it pushes vs. doesn't (logging)
|
||
|
||
- **Inputs (buttons): YES, pushed.** Input changes are HTTP-pushed via `input_link_url` and now
|
||
land in the host's signed [[append-only-event-chain]] as `input_received` events (bus →
|
||
`EventLog`). That is the audit trail for "a button fired."
|
||
- **Relay / barrier opens: NO push, no log.** The device has **no event log of its own** and does
|
||
not report when a relay fires — relay control is one-way UDP that the *host* initiates. So
|
||
"the barrier opened" is not something to scrape from the device. The host records what it
|
||
*commanded* (a future `barrier_open_command` event); a relay open with **no matching signed
|
||
host event is itself the anomaly** to alarm on ([[threat-model]]). Do not treat the Dingtian as
|
||
a log source — it is a dumb relay+input board; the host is the source of truth.
|
||
|
||
## Hardening (`harden()`) — and why HTTP auth is not a boundary here
|
||
|
||
On assign the driver runs `harden()` (the [[device-registry|HardenableDevice]] capability):
|
||
1. **`relay_pw`** — set a random relay password so binary relay commands (UDP 60000) need it.
|
||
2. **Disable EVERY other channel** — set `p:255` on the string protocol (udp2), rs485, can,
|
||
tcp×2, mqtt; keep **only** UDP1 binary, which carries `relay_pw` for both control AND status.
|
||
3. **Rotate the `admin`/`admin` web login** — `GET /userset.cgi?<old_u>&<old_p>&<new_u>&<new_p>&`
|
||
(response `&0&…&` = success, verified on hardware). The new password is stored back in
|
||
config (`webUser`/`webPassword`) so a re-run can rotate again (the device checks the *old*
|
||
creds). This step is **best-effort** — a failure logs and does not fail the assign.
|
||
|
||
> ⚠️ **The string protocol (udp2) is a password-less relay-fire path — the original `harden()`
|
||
> left it ENABLED "for status reads", which was a real hole.** The Dingtian string protocol has
|
||
> NO password field and can fire relays (`"11"` = relay 1 on, `"21"` = off, `"11*"` = jog).
|
||
> **Proven on hardware**: sending `"11"` to UDP 60001 with no credentials opened relay 1,
|
||
> completely bypassing `relay_pw`. Fixes: (a) status reads moved to the **authenticated binary
|
||
> read** (relay command `0x00`) so the string protocol is no longer needed; (b) `harden()` now
|
||
> sets `udp2.p=255` to disable it. **Firmware caveat (V3.6J):** the CONFIG API silently refuses
|
||
> to disable udp2 — it accepts the write, reboots, and clamps it back — even though the device's
|
||
> **web UI can** disable it. So the udp2 disable is **best-effort + warns** (it is NOT part of the
|
||
> blocking verify); if it doesn't stick, `harden()` returns a warning telling the admin to flip
|
||
> UDP2 off in the device web UI. Verified: after the web-UI disable, the `"11"` attack gets no
|
||
> reply and the relay stays off, while authenticated binary control/status still work.
|
||
|
||
> ⚠️ **The device CGI API is UNAUTHENTICATED.** Verified on hardware: `GET /api/v2/config.cgi`,
|
||
> `/`, and even `/userset.cgi` all return **200 with no credentials**. The `admin`/`admin` login
|
||
> gates only the interactive **browser UI** — the CGI control plane (read/write full config, fire
|
||
> relays, change the password) bypasses it entirely. The `http` config block has **no** setting to
|
||
> require Basic/Digest on inbound requests; the only inbound gate is `session_en`, which **bricks
|
||
> the config-read API on this firmware** (the factory-reset incident — *do not enable it*). So
|
||
> **rotating the login is cosmetic** (stops a casual browser reaching settings); it is **not** a
|
||
> boundary. On this flat, no-VLAN network the device control plane is effectively open — the
|
||
> **signed event log is the real anti-fraud guarantee**. See [[device-input-flow]].
|
||
|
||
> ⚠️ **`session_en` must stay OFF.** Enabling the HTTP CGI session check makes the config-read API
|
||
> drop connections (ECONNRESET), locking out the API the driver depends on — recoverable only by
|
||
> factory reset. `harden()` deliberately never touches it.
|
||
|
||
## Status — VERIFIED on hardware (DT-R004, sw V3.1.5461A, 10.0.10.172)
|
||
|
||
- ✅ status read (`0000:1111:4`), relay pulse, input press/release events (active-LOW, idle HIGH).
|
||
- ✅ **`input_link_relay` disabled via the driver** → pressing an input reports the event and
|
||
**fires NO relay** (`0000` after presses). The [[access-controller-button-flow]] blocker is
|
||
**solved**.
|
||
- ✅ **Input HTTP-push end to end** — configured the device via `configureInputPush()`, then real
|
||
button presses (all 4 inputs) **pushed to the backend** (`/input/N/on` + `/off` per press,
|
||
source = the device IP). No polling. Host-in-the-loop entry (`button → backend → ticket →
|
||
backend opens relay`) is real.
|
||
- ✅ **Web-login rotation** — `userset.cgi` rotates `admin`/`admin` (response `&0&/&`; wrong old
|
||
password → `&2&/&`). Confirmed the device validates the old creds. **Also confirmed the CGI API
|
||
needs NO auth** (config dump + `userset.cgi` return 200 unauthenticated) → rotation is cosmetic.
|
||
- ⬜ Next: wire the actual entry flow (input event → signed event + print ticket → `pulseOpen`).
|