From ecdadbbef8481a236097a3abc946046d956abf2c Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Fri, 20 Nov 2026 14:58:39 -0600 Subject: [PATCH] LAN pairing (firmware 4.0.1): client key, pair(), lan_clients() - transport/client_identity: this computer's TLS client key and self-signed certificate, shared with benchpod (client.key/client.crt next to known_pods.json, made on first use); BENCHPOD_CLIENT_KEY_PEM or BENCHPOD_CLIENT_CERT/_KEY for CI. Every 8443 connection presents it. - BenchPod.pair(), lan_clients(add/remove/clear), set_lan_pairing(); LanClients/LanClient. pair() over USB pins the pod's LAN certificate. - The serial transport answers lan_clients and lan_tls through the console, so pairing works while the USB network adapter is off. - PodNotPairedError (BP0081, a PodLockedError); BP0082. Catalog and feature map synced from the firmware. - New dependency: cryptography>=41 (key and certificate generation). Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci/README.md | 24 +++ packages/embeddedci/pyproject.toml | 1 + .../src/embeddedci/benchpod/__init__.py | 6 +- .../src/embeddedci/benchpod/client.py | 76 ++++++- .../embeddedci/benchpod/error_catalog.json | 136 +++++++----- .../src/embeddedci/benchpod/errors.py | 10 + .../src/embeddedci/benchpod/feature_map.json | 10 +- .../src/embeddedci/benchpod/results.py | 31 +++ .../benchpod/transport/client_identity.py | 198 ++++++++++++++++++ .../embeddedci/benchpod/transport/serial.py | 97 ++++++++- .../src/embeddedci/benchpod/transport/tls.py | 9 + packages/embeddedci/tests/api_surface.json | 24 +++ packages/embeddedci/tests/test_error_codes.py | 3 + packages/embeddedci/tests/test_lan_pairing.py | 147 +++++++++++++ 14 files changed, 715 insertions(+), 57 deletions(-) create mode 100644 packages/embeddedci/src/embeddedci/benchpod/transport/client_identity.py create mode 100644 packages/embeddedci/tests/test_lan_pairing.py diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index b4a3a79..cf94cf7 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -315,6 +315,27 @@ cloud connection; over plaintext Ethernet or Wi-Fi the pod refuses (`PodLockedEr `set_lan_tls_cert` needs a network connection (it uploads the bundle); after it and after `regenerate_lan_tls()` the SDK pins the new certificate for the address it used. +### LAN pairing + +From firmware 4.0.1 the pod answers only status to a computer on Ethernet or Wi-Fi that is not +paired with it: anything else raises `PodNotPairedError` (`BP0081`, a `PodLockedError`). Pair this +computer once over the pod's USB cable, or through the cloud as an organization owner or admin: + +```python +BenchPod("usb").pair() # the USB network adapter, or the console when it is off +BenchPod("embeddedci:bench-01").pair() +``` + +`benchpod setup` does the same. The SDK presents this computer's TLS client key on every +connection to port 8443: `client.key` and `client.crt` next to `known_pods.json`, made on first use +and shared with `benchpod` and the MCP server. A CI runner passes its own with +`BENCHPOD_CLIENT_KEY_PEM` (or `BENCHPOD_CLIENT_CERT` and `BENCHPOD_CLIENT_KEY`). Over USB, +`pair()` also pins the pod's LAN certificate for its LAN address. + +`bp.lan_clients()` lists the paired computers (`LanClient.this` marks this one); +`lan_clients(add=..., spki_sha256=...)`, `remove=...` (a name, or 8+ hex digits of a key) and +`clear=True` change the list over USB or the cloud only. `set_lan_pairing(False)` turns pairing off. + ### Console log level How much the pod prints on its USB console (firmware newer than 3.10.12, feature `log_level`). @@ -359,6 +380,8 @@ macs = bp.mac_addresses() # MacAddresses(eth_mac='02:35:c7:76:b7:9b', wifi_ | `BENCHPOD_LIFT_DAC_LIMITS` | pytest sessions | `1` clears the pod's DAC output limits for the session and restores the same limits at the end, even when tests fail (only with the output stage switched off) | | `BENCHPOD_TLS` | network connections | `auto` (default), `on` or `off`: TLS to the pod's LAN API on 8443, see [TLS on the LAN](#tls-on-the-lan) | | `BENCHPOD_TLS_CA` | network connections over TLS | PEM file of CA certificates: verify the pod's certificate and host name instead of pinning it | +| `BENCHPOD_CLIENT_KEY_PEM` | network connections over TLS | This computer's TLS client certificate and key, PEM, for [LAN pairing](#lan-pairing) (a CI secret; `benchpod lan-clients add --new-key` prints one) instead of `client.key`/`client.crt` | +| `BENCHPOD_CLIENT_CERT`, `BENCHPOD_CLIENT_KEY` | network connections over TLS | The same as two files | | `BENCHPOD_STALL_TIMEOUT` | flashing | seconds with no SWD traffic before a flash attempt is aborted and retried (default 60) | | `BENCHPOD_SENSOR_LIBRARY` | no `version` argument / `--benchpod-sensor-library` | sensor library version: `latest` or a release such as `0.2.0` (default: the version the SDK pins), see [Emulated sensors](#emulated-sensors) | | `BENCHPOD_LEASE` | connecting | a lease id to join instead of taking a new lease (set by `benchpod ci` for its child processes), see [Device leases](#device-leases) | @@ -2610,6 +2633,7 @@ few built from other shapes); `to_dict()` goes the other way where a type is sen | `ResetState` | `reset_target`, `set_reset`, `reset_state` | `asserted`, `supported` | | `MacAddresses` | `mac_addresses` | `eth_mac`, `wifi_mac` (None while not known), `has_wifi`, `source` (`pod`, `server` or empty) | | `LanTls` | `lan_tls`, `set_lan_tls_https_only`, `regenerate_lan_tls`, `set_lan_tls_cert` | `port`, `https_only`, `sessions`, `origin` (`generated`/`user`), `key`, `subject`, `san`, `not_after`, `sha256` (what clients pin), `error` (no certificate) | +| `LanClients` | `lan_clients`, `pair` | `pairing` (computers on the LAN must be paired), `count`, `max`, `clients` (`LanClient`: `name`, `spki_sha256`, `this`), `has(spki_sha256)` | | `UsbCcStatus` | `usb_cc` | `orientation`, `advertised`, `advertised_current` (A), `cc1_voltage`, `cc2_voltage` (V) | | `PullState` | `pull_state`, `set_pull` | `la`, `enabled`, `direction`, `ohms`, `available`, `supported`, `strength` (digital v3r4) | | `LaPinState` | `la_pins`, `configure_gpio`, `la_dir` | `la`, `function`, `gpio`, `level`, `pull`, `pull_ohms`, `pull_on`, `pull_dirs`, `dir`, `warn`, `warnings`, `in_use` | diff --git a/packages/embeddedci/pyproject.toml b/packages/embeddedci/pyproject.toml index 66ed061..54ec1db 100644 --- a/packages/embeddedci/pyproject.toml +++ b/packages/embeddedci/pyproject.toml @@ -27,6 +27,7 @@ classifiers = [ ] dependencies = [ "pyserial>=3.5", + "cryptography>=41", ] [project.optional-dependencies] diff --git a/packages/embeddedci/src/embeddedci/benchpod/__init__.py b/packages/embeddedci/src/embeddedci/benchpod/__init__.py index d86064e..486c2fe 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/__init__.py +++ b/packages/embeddedci/src/embeddedci/benchpod/__init__.py @@ -113,6 +113,7 @@ def test_boots(benchpod_target, firmware): # fixtures from the pytest plugin PodLeasedError, PodLeaseLostError, PodLockedError, + PodNotPairedError, PullConflictError, ReplyTooLargeError, PullDirectionError, @@ -142,7 +143,7 @@ def test_boots(benchpod_target, firmware): # fixtures from the pytest plugin from .lowlevel import LowLevel from .power import PowerProfile, PowerProfileSession from .replay import DacHandle, Fault, ReplayHandle, Segment -from .results import Capture, CorrelatedCapture, LaCapture, LanTls, MacAddresses, Trigger +from .results import Capture, CorrelatedCapture, LaCapture, LanClient, LanClients, LanTls, MacAddresses, Trigger from .transport.tls import delete_pin as forget_lan_tls, trust_lan_tls from .server_api import ServerApi, ServerApiError, ServerPermissionDeniedError from .state import ( @@ -359,6 +360,9 @@ def test_boots(benchpod_target, firmware): # fixtures from the pytest plugin "ServerApiError", "ServerPermissionDeniedError", "PodLockedError", + "PodNotPairedError", + "LanClient", + "LanClients", "PodBusyError", "PodLeasedError", "PodLeaseLostError", diff --git a/packages/embeddedci/src/embeddedci/benchpod/client.py b/packages/embeddedci/src/embeddedci/benchpod/client.py index 44f9447..1bb7313 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/client.py +++ b/packages/embeddedci/src/embeddedci/benchpod/client.py @@ -110,7 +110,7 @@ from .lowlevel import LowLevel from .power import PowerProfile, PowerProfileSession from .replay import DacHandle, Fault, ReplayHandle, normalize_fault -from .results import Capture, CorrelatedCapture, LaCapture, LanTls, MacAddresses, Trigger +from .results import Capture, CorrelatedCapture, LaCapture, LanClient, LanClients, LanTls, MacAddresses, Trigger from .wiring import Signal, Wiring from .state import ( AdcRangeState, @@ -134,6 +134,8 @@ from .transport import Transport, open_transport from .transport.cloud import CloudTransport from .transport.tcp import TcpTransport +from .transport import client_identity +from .transport import tls as _tls from . import pod_lease as _pod_lease if TYPE_CHECKING: # pragma: no cover @@ -1329,6 +1331,78 @@ def lan_tls(self) -> "LanTls": :class:`UnsupportedFeatureError` on older firmware.""" return LanTls.from_reply(self.command({"cmd": "lan_tls"})) + # -- LAN pairing ---------------------------------------------------------- + + def lan_clients(self, *, add: Optional[str] = None, spki_sha256: Optional[str] = None, + remove: Optional[str] = None, clear: bool = False) -> "LanClients": + """The computers paired with the pod for use over Ethernet and Wi-Fi (firmware 4.0.1+). + + Over the LAN the pod answers only status to a computer that is not paired + (:class:`PodNotPairedError`). ``add`` (a name) with ``spki_sha256`` pairs a key, + ``remove`` unpairs the computers with that name or the one key starting with those hex + digits (8 or more), ``clear`` unpairs all; each change needs USB (the console or the USB + network) or the cloud (an organization owner or admin), never the LAN. Returns the list; + :attr:`LanClient.this` marks this computer. To pair this computer, :meth:`pair`.""" + req: Dict[str, Any] = {"cmd": "lan_clients"} + if add is not None: + if not spki_sha256: + raise ValueError("lan_clients(add=...) needs spki_sha256") + req.update(add=client_identity.sanitize_name(add), spki_sha256=spki_sha256.lower()) + elif remove is not None: + req["remove"] = str(remove) + elif clear: + req["clear"] = True + data = self.command(req) + mine = self._client_key_hash() + clients = list((data or {}).get("clients") or []) + total = int((data or {}).get("count") or 0) + while 0 < len(clients) < total: # the pod sends 12 a reply + more = self.command({"cmd": "lan_clients", "offset": len(clients)}) + page = list((more or {}).get("clients") or []) + if not page: + break + clients.extend(page) + if isinstance(data, dict): + data = dict(data, clients=clients) + return LanClients.from_reply(data, mine) + + def pair(self, name: Optional[str] = None) -> "LanClients": + """Pair this computer with the pod (firmware 4.0.1+), so it may drive the pod over Ethernet + and Wi-Fi, not only read its status. Run it once over USB (``BenchPod("usb")``: the USB + network adapter or the console) or the cloud (``"embeddedci:"``, as an + organization owner or admin); ``benchpod setup`` does the same. ``name`` defaults to this + computer's host name. Over USB it also pins the pod's LAN certificate for its LAN address, + so later LAN connections check they reach this very pod. Returns the list.""" + key = client_identity.client_key_hash() + out = self.lan_clients(add=name or client_identity.pairing_name(), spki_sha256=key) + self._pin_lan_certificate() + return out + + def set_lan_pairing(self, on: bool) -> bool: + """Turn LAN pairing on (the default) or off (every computer on the network may use the pod, + as before firmware 4.0.1). Over USB or the cloud only. Returns the new setting.""" + data = self.command({"cmd": "lan_policy", "pairing": bool(on)}) + return bool((data or {}).get("pairing")) + + def _client_key_hash(self) -> str: + try: + return client_identity.client_key_hash() + except Exception: + return "" + + def _pin_lan_certificate(self) -> None: + """After pairing over USB: pin the pod's certificate for its LAN address (best effort).""" + try: + sha = str((self.command({"cmd": "lan_tls"}) or {}).get("sha256") or "") + ip = str((self._transport.status() or {}).get("ip") or "") + except Exception: + return + if len(sha) == 64 and ip and not _tls.is_usb_link(ip): + try: + _tls.set_pin(ip, sha) + except (OSError, ValueError): + pass + def set_lan_tls_https_only(self, on: bool) -> "LanTls": """Turn HTTPS-only on (plaintext 8080 refused on Ethernet and Wi-Fi; the USB link keeps it) or off. Turning it off needs a TLS, USB or cloud connection: over plaintext Ethernet or Wi-Fi diff --git a/packages/embeddedci/src/embeddedci/benchpod/error_catalog.json b/packages/embeddedci/src/embeddedci/benchpod/error_catalog.json index 5067f29..9144759 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/error_catalog.json +++ b/packages/embeddedci/src/embeddedci/benchpod/error_catalog.json @@ -1,7 +1,7 @@ { "_generated": "GENERATED by tools/gen_errors.py from errors/catalog.toml. DO NOT EDIT: edit the catalog.", "version": 1, - "catalog_sha256": "8f18331e99506bc37019f0613a1361febb68316d985bbcb04e1ab7343071dc83", + "catalog_sha256": "2b61a8def1e0a7a3620fe675720cd1b93371f942e3618a4ab46cdb60e99c5544", "docs_url": "https://embeddedci.com/docs/errors#{code}", "codes": { "BP0001": { @@ -466,7 +466,7 @@ "BP0030": { "name": "client_too_old", "area": "protocol", - "since": "next", + "since": "4.0.0", "message": "Update the BenchPod SDK, MCP or CLI: this firmware needs client API {min_client_api} or newer (this client sent {client_api})", "cause": "The firmware on the pod changed a reply or a message in a way that clients built for client API {client_api} would misread, so it refuses their commands instead of giving them answers they get wrong. The firmware speaks client API {api} and takes {min_client_api} or newer. A client that sends no client_api counts as 0. These still run for any client: ping, status, diag, identity_public, lease_release, ota_status, ota_begin, ota_data, ota_end, ota_commit, ota_abort, ota_selftest and blob_status, so a client can see the levels, let go of the pod, and update the pod's firmware and blobs or roll them back.", "args": { @@ -484,7 +484,7 @@ "BP0031": { "name": "la_pin_in_use", "area": "io", - "since": "next", + "since": "4.0.0", "message": "LA{la} is in use by {owner}", "cause": "Each LA channel has one owner at a time: a GPIO, a UART, SWD, SPI or I2C session, a step train or an emulated sensor. {owner} holds LA{la}, so the pod refuses to give it to anything else until that owner lets it go. function is the owner's function (gpio, uart_tx, i2c_sda, ...), and instance the emulated sensor's name, empty for anything else.", "args": { @@ -503,7 +503,7 @@ "BP0032": { "name": "la_pull_down_engaged", "area": "io", - "since": "next", + "since": "4.0.0", "message": "LA{la} has its {ohms} pull-down on, which {function} cannot work with ({reason})", "cause": "A pull-down holds the line low. An open-drain bus (I2C), an idle-high UART line or SWDIO needs the line to rest high, so the pod refuses to start {function} on LA{la} while its pull-down is on.", "args": { @@ -522,7 +522,7 @@ "BP0033": { "name": "la_pull_down_conflict", "area": "io", - "since": "next", + "since": "4.0.0", "message": "LA{la} is used by {function}, which cannot work with the {ohms} pull-down ({reason})", "cause": "A pull-down holds the line low. {function} on LA{la} needs the line to rest high, so the pod refuses to switch the pull-down on under it.", "args": { @@ -541,7 +541,7 @@ "BP0034": { "name": "la_dut_output", "area": "io", - "since": "next", + "since": "4.0.0", "message": "LA{la} is wired to a DUT output, and {function} would drive against it", "cause": "The wiring marks LA{la} as a pin the DUT drives (la_dir dut_output). Two push-pull outputs on one wire fight each other, which can damage either side, so the pod refuses to drive it. There is no override.", "args": { @@ -558,7 +558,7 @@ "BP0035": { "name": "la_driven_pin", "area": "io", - "since": "next", + "since": "4.0.0", "message": "LA{la} is driven by {function}, so it cannot be marked as a DUT output", "cause": "{function} drives LA{la} from the pod. Marking the pin as one the DUT drives would put two outputs on one wire, so the pod refuses until the pod's side stops driving it.", "args": { @@ -575,7 +575,7 @@ "BP0036": { "name": "la_not_gpio_output", "area": "io", - "since": "next", + "since": "4.0.0", "message": "LA{la} is not a GPIO output (it is {function})", "cause": "Writing a level or sending a gpio step needs the channel set up as a GPIO output or open drain first.", "args": { @@ -592,7 +592,7 @@ "BP0037": { "name": "la_voltage_pins_in_use", "area": "io", - "since": "next", + "since": "4.0.0", "message": "The I/O voltage cannot change while pins are in use: {pins}", "cause": "Changing the I/O voltage under a running GPIO, UART, flash or sensor would put the wrong level on the DUT's pins, so the pod refuses until they are free.", "args": { @@ -608,7 +608,7 @@ "BP0038": { "name": "trigger_timeout", "area": "capture", - "since": "next", + "since": "4.0.0", "message": "No {edge} edge on LA{la} within {timeout_ms} ms", "cause": "A triggered capture waits for its trigger condition before it records. The DUT never made a {edge} edge on LA{la} in the time given, so the pod stopped waiting and recorded nothing.", "args": { @@ -626,7 +626,7 @@ "BP0039": { "name": "sensor_trigger_timeout", "area": "capture", - "since": "next", + "since": "4.0.0", "message": "No I2C start on LA{la} (SDA of {instance}) within {timeout_ms} ms: the DUT did not use the I2C bus", "cause": "A sensor bus capture with trigger \"start\" waits for the DUT's first I2C start condition on the emulated sensor's SDA. None came in time.", "args": { @@ -644,7 +644,7 @@ "BP0040": { "name": "lan_locked", "area": "policy", - "since": "next", + "since": "4.0.0", "message": "The pod's LAN is locked: {cmd} needs the cloud or USB", "cause": "The pod's LAN policy is locked, so commands that change settings, flash or update (tiers T2 and T3) only run from the cloud or over USB. Reads and tests still run on the LAN.", "args": { @@ -660,7 +660,7 @@ "BP0041": { "name": "policy_not_from_lan", "area": "policy", - "since": "next", + "since": "4.0.0", "message": "{setting} cannot be changed over the LAN: change it from the cloud or the USB console", "cause": "Policies that decide who may change the pod are only changed by someone with the pod's cloud account or its USB cable, never by anyone on the network.", "args": { @@ -676,7 +676,7 @@ "BP0042": { "name": "setting_cloud_or_usb", "area": "policy", - "since": "next", + "since": "4.0.0", "message": "{setting} cannot be changed over the LAN: change it from the cloud or over USB", "cause": "Settings that decide what the pod trusts (LAN TLS, the cloud CA, the cloud proxy) are not changed from the network. TLS on port 8443 has no client authentication, so it does not count either.", "args": { @@ -692,7 +692,7 @@ "BP0043": { "name": "setting_device_only", "area": "policy", - "since": "next", + "since": "4.0.0", "message": "{setting} can only be changed on the device: the USB console, or over the USB link", "cause": "This setting changes how the pod can be reached or updated, so it needs someone at the pod: its USB console or its USB network link. Neither the LAN nor the cloud may change it.", "args": { @@ -708,7 +708,7 @@ "BP0044": { "name": "policy_loosen_usb_only", "area": "policy", - "since": "next", + "since": "4.0.0", "message": "Only the USB console can loosen {setting} (now {now})", "cause": "The cloud may make the pod stricter but never looser: a stolen cloud account must not be able to lower the pod's firmware signature policy.", "args": { @@ -727,7 +727,7 @@ "BP0045": { "name": "role_required", "area": "policy", - "since": "next", + "since": "4.0.0", "message": "{cmd} needs an organization owner or admin", "cause": "A cloud session runs commands up to the tier the server allows its user. {cmd} changes or updates the pod, which needs an owner or admin of the pod's organization.", "args": { @@ -743,7 +743,7 @@ "BP0046": { "name": "no_analog_front_end", "area": "board", - "since": "next", + "since": "4.0.0", "message": "This BenchPod has no analog front end, so it cannot run {cmd}", "cause": "The digital board has no DAC, ADC or analog outputs. The pod checks at boot; after fitting an analog add-on, restart it.", "args": { @@ -759,7 +759,7 @@ "BP0047": { "name": "pod_busy", "area": "busy", - "since": "next", + "since": "4.0.0", "message": "The pod is running another long command (a capture, measurement, upload or update)", "cause": "Captures, measurements, waveform uploads and firmware updates share the pod's sample memory, so one runs at a time. Light commands (status, GPIO, ...) still run.", "args": {}, @@ -773,7 +773,7 @@ "BP0048": { "name": "storage_bus_busy", "area": "busy", - "since": "next", + "since": "4.0.0", "message": "The pod's storage bus is in use: {what}", "cause": "The flash that holds settings, gateware and update images shares a bus with the sample memory. While {what}, the pod cannot write it.", "args": { @@ -789,7 +789,7 @@ "BP0049": { "name": "uart_session_open", "area": "uart", - "since": "next", + "since": "4.0.0", "message": "A UART session is already open", "cause": "The pod runs one UART at a time: the web app's Terminal, a test, an MCP session or a flash over the UART holds it.", "args": {}, @@ -803,7 +803,7 @@ "BP0050": { "name": "swd_session_open", "area": "flash", - "since": "next", + "since": "4.0.0", "message": "An SWD session is already running", "cause": "The pod runs one SWD session (a flash or a debug run) at a time.", "args": {}, @@ -817,7 +817,7 @@ "BP0051": { "name": "update_in_progress", "area": "update", - "since": "next", + "since": "4.0.0", "message": "A {target} update from {holder} is in progress", "cause": "The pod takes one update at a time, from one place. Another one is running.", "args": { @@ -834,7 +834,7 @@ "BP0052": { "name": "cloud_command_busy", "area": "busy", - "since": "next", + "since": "4.0.0", "message": "The pod is still running the previous cloud command", "cause": "Over the cloud command channel the pod runs one command at a time. The server retries, so this is usually brief.", "args": {}, @@ -848,7 +848,7 @@ "BP0053": { "name": "reply_too_large", "area": "protocol", - "since": "next", + "since": "4.0.0", "message": "The reply did not fit the pod's reply buffer", "cause": "The command worked, but its answer is larger than the pod can send at once. Commands that can grow (la_pins) take a subset.", "args": {}, @@ -862,7 +862,7 @@ "BP0054": { "name": "cloud_reply_too_large", "area": "protocol", - "since": "next", + "since": "4.0.0", "message": "The reply is too large for the cloud channel ({bytes} bytes, limit {limit})", "cause": "Cloud command replies travel in one frame of at most {limit} bytes. This one is {bytes}. Large data (captures) go through the cloud byte tunnel instead.", "args": { @@ -879,7 +879,7 @@ "BP0055": { "name": "sensor_instance_unknown", "area": "sensors", - "since": "next", + "since": "4.0.0", "message": "The pod has no emulated sensor {instance}", "cause": "The instance was never defined or started on this pod, was stopped, or the pod restarted.", "args": { @@ -895,7 +895,7 @@ "BP0056": { "name": "no_module_link", "area": "board", - "since": "next", + "since": "4.0.0", "message": "This BenchPod has no module link, so it cannot run {cmd}", "cause": "Only boards with a module header (digital v3r3) talk to an add-on module.", "args": { @@ -911,7 +911,7 @@ "BP0057": { "name": "image_switch_sensors_running", "area": "sensors", - "since": "next", + "since": "4.0.0", "message": "The emulated sensors {sensors} need the emulation image; stop them before switching", "cause": "I2C, SPI and UART sensors run in the emulation gateware image. Switching to another image would stop them mid-run, so the pod refuses.", "args": { @@ -927,7 +927,7 @@ "BP0058": { "name": "fpga_image_required", "area": "firmware", - "since": "next", + "since": "4.0.0", "message": "{feature} is not in the running gateware image; it needs the {image} image", "cause": "The pod's FPGA runs one of three images (loop, deep replay, emulation), and each has some features. {feature} is in the {image} image.", "args": { @@ -944,7 +944,7 @@ "BP0059": { "name": "fpga_image_sensors_first", "area": "sensors", - "since": "next", + "since": "4.0.0", "message": "{feature} is not in the emulation image the emulated sensors use; stop them, then switch to the {image} image", "cause": "Emulated I2C, SPI and UART sensors run in the emulation gateware image, which has no room for {feature}. It needs the {image} image, and switching stops the sensors.", "args": { @@ -961,7 +961,7 @@ "BP0060": { "name": "ota_unknown_target", "area": "update", - "since": "next", + "since": "4.0.0", "message": "{target} is not an update target this firmware knows", "cause": "The firmware on the pod is older than the tool, or the target name is wrong.", "args": { @@ -977,7 +977,7 @@ "BP0061": { "name": "i2c_needs_pullups", "area": "i2c", - "since": "next", + "since": "4.0.0", "message": "I2C needs pull-ups: LA{la} has none switched on", "cause": "I2C lines are open drain: something must pull them high. The pod can do it with its own pull-ups, or the board has its own.", "args": { @@ -993,7 +993,7 @@ "BP0062": { "name": "i2c_session_not_open", "area": "i2c", - "since": "next", + "since": "4.0.0", "message": "No I2C session is open", "cause": "I2C transactions run inside a session that i2c_start opens.", "args": {}, @@ -1007,7 +1007,7 @@ "BP0063": { "name": "i2c_engine_reset", "area": "i2c", - "since": "next", + "since": "4.0.0", "message": "The I2C engine was reset, which ended the session", "cause": "A gateware reload (an image switch, a recovery) resets the I2C engine, so the open session is gone.", "args": {}, @@ -1021,7 +1021,7 @@ "BP0064": { "name": "loop_sweep_with_map", "area": "dac", - "since": "next", + "since": "4.0.0", "message": "The sweep input cannot be combined with an input map on this gateware", "cause": "The sweep spans the raw count range, not the mapped window, so most of each pass would sit at one end of the curve.", "args": {}, @@ -1035,7 +1035,7 @@ "BP0065": { "name": "output_used_by_sensor", "area": "sensors", - "since": "next", + "since": "4.0.0", "message": "The {output} output is played by the emulated sensor {instance}", "cause": "An analog emulated sensor drives the pod's {output} output, so a DAC or current command would fight it.", "args": { @@ -1052,7 +1052,7 @@ "BP0066": { "name": "step_busy", "area": "io", - "since": "next", + "since": "4.0.0", "message": "A step pulse train is running", "cause": "The pod runs one step train at a time.", "args": {}, @@ -1066,7 +1066,7 @@ "BP0067": { "name": "samples_out_of_range", "area": "capture", - "since": "next", + "since": "4.0.0", "message": "samples must be 1 to {max} for this capture", "cause": "Each capture holds a fixed number of samples: the shallow ADC capture what fits the RAM buffer, the deep ones what fits their PSRAM region at the rate asked for. A deep ADC capture is capture_dual with la_samples 0.", "args": { @@ -1082,7 +1082,7 @@ "BP0068": { "name": "la_rate_above_ceiling", "area": "capture", - "since": "next", + "since": "4.0.0", "message": "LA at {rate_mhz} MS/s does not fit: with ADC samples in the capture the raw LA runs at most {max_mhz} MS/s on this gateware, {fit_mhz} MS/s for {samples} samples", "cause": "On gateware before v53 the raw LA runs at most {max_mhz} MS/s when the same capture records ADC samples: faster, the PSRAM writer starved the ADC. The pod refuses an explicit rate it cannot run instead of slowing it down. {fit_mhz} MS/s is the fastest rate that fits {samples} samples. Above 12 MS/s the LA records its changes instead.", "args": { @@ -1101,7 +1101,7 @@ "BP0069": { "name": "la_rate_too_deep", "area": "capture", - "since": "next", + "since": "4.0.0", "message": "LA at {rate_mhz} MS/s does not fit {samples} samples: at most {max_samples} samples at {rate_mhz} MS/s, or at most {fit_mhz} MS/s for {samples} samples", "cause": "The raw LA samples into a burst buffer that drains to the PSRAM more slowly than the fastest rates. A capture deeper than the buffer holds at {rate_mhz} MS/s would drop samples, so the pod refuses it instead of slowing it down. Either way out works: fewer samples at this rate, or a lower rate for this depth.", "args": { @@ -1120,7 +1120,7 @@ "BP0070": { "name": "capture_dual_too_deep", "area": "capture", - "since": "next", + "since": "4.0.0", "message": "capture_dual takes at most {la_max} LA and {adc_max} ADC samples", "cause": "Each stream of a capture_dual has its own PSRAM region of a fixed size. A deeper LA-only capture fits la_capture, which takes up to {la_capture_max} LA samples.", "args": { @@ -1138,7 +1138,7 @@ "BP0071": { "name": "capture_overflowed", "area": "capture", - "since": "next", + "since": "4.0.0", "message": "The capture overflowed: the PSRAM could not keep up with LA {la_ksps} kS/s and ADC {adc_ksps} kS/s", "cause": "The capture started, but its streams wrote to the PSRAM faster than it could take them, so samples were lost and the pod returns none.", "args": { @@ -1155,7 +1155,7 @@ "BP0072": { "name": "psram_too_small", "area": "capture", - "since": "next", + "since": "4.0.0", "message": "The capture is too deep: LA, ADC and a loaded DAC waveform together exceed the 8 MB PSRAM", "cause": "A capture_dual packs its LA region, its ADC region and any deep-replay waveform still loaded into the pod's 8 MB PSRAM, and refuses up front when they do not fit.", "args": {}, @@ -1169,7 +1169,7 @@ "BP0073": { "name": "psram_bandwidth", "area": "capture", - "since": "next", + "since": "4.0.0", "message": "The combined sample rate is more than the PSRAM bus can take", "cause": "The LA, the ADC and a running deep replay share one PSRAM bus. The pod adds up their sustained rates and refuses a capture that would overrun it, instead of losing samples.", "args": {}, @@ -1183,7 +1183,7 @@ "BP0074": { "name": "signatures_always_required", "area": "policy", - "since": "next", + "since": "4.0.0", "message": "{setting} cannot be set to {want}: this firmware installs only signed images", "cause": "Firmware 4.0.0 and later take an update (firmware, gateware, the Wi-Fi chip's image) only with a good signature, on every path: the LAN, the USB network adapter and the cloud. No command loosens that. Dev builds also take images signed with the developer key. Firmware you built yourself goes in over USB DFU (`benchpod flash-self`), which needs the pod on a USB cable.", "args": { @@ -1200,7 +1200,7 @@ "BP0075": { "name": "lan_plaintext_off", "area": "policy", - "since": "next", + "since": "4.0.0", "message": "The pod serves its JSON API on the LAN over TLS only (port 8443): plaintext port 8080 is off", "cause": "Firmware 4.0.0 and later serve the JSON API over Ethernet and Wi-Fi on TLS port 8443 only. Plaintext port 8080 still answers on the USB network adapter, and from the LAN when SCPI is switched on, but only for SCPI there. Plaintext JSON on the LAN comes back only when it is switched on over USB or from the cloud.", "args": {}, @@ -1214,7 +1214,7 @@ "BP0076": { "name": "usb_host_over_usb", "area": "usb", - "since": "next", + "since": "4.0.0", "message": "USB host mode cannot start over the pod's own USB link", "cause": "While the pod hosts a board on its USB port it is off the computer's USB, so the connection that asked would drop before the answer arrives. USB host mode starts only over the network (LAN or Wi-Fi) or the cloud.", "args": {}, @@ -1228,7 +1228,7 @@ "BP0077": { "name": "usb_host_port_unavailable", "area": "usb", - "since": "next", + "since": "4.0.0", "message": "This pod has no USB host port {port}", "cause": "Only pods with a USB-A host port can host a board there. Every pod can host on its USB-C port, but only on a bench rig with an adapter cable that powers the pod and carries the data lines to the board under test.", "args": { @@ -1244,7 +1244,7 @@ "BP0078": { "name": "usb_host_no_crystal", "area": "usb", - "since": "next", + "since": "4.0.0", "message": "USB host mode needs the pod's crystal clock, which is not running", "cause": "A USB host keeps the bus timing itself and needs a precise clock. The pod runs on its internal oscillator because the crystal did not start at boot.", "args": {}, @@ -1258,7 +1258,7 @@ "BP0079": { "name": "usb_host_other_port", "area": "usb", - "since": "next", + "since": "4.0.0", "message": "USB host mode is already running on {port}", "cause": "The pod hosts one port at a time. A start for the same port renews the timeout; another port needs a stop first.", "args": { @@ -1274,7 +1274,7 @@ "BP0080": { "name": "dac_pinout_mismatch", "area": "analog", - "since": "next", + "since": "4.0.0", "message": "{cmd} refused, the DAC is off: the digital board ({digital}) and the analog module ({module}) use different flat-cable pinouts", "cause": "The flat cable between the two boards carries the DAC's clock and data. Digital board v3r4 and analog module 3.5 swapped those two lines, so a newer board paired with an older one would send the DAC scrambled data and its outputs could jump to any voltage. The pod refuses every command that drives the DAC and sends it nothing; everything else keeps working. The module's revision comes from its EEPROM, so a module that was never programmed counts as an older one.", "args": { @@ -1288,6 +1288,38 @@ "mcp": "tell the user the digital board and the analog module do not belong together (status shows both revisions): a digital v3r4+ board needs an analog module 3.5+, and an older digital board an older module", "web": "The digital board and the analog module do not belong together, so the analog outputs are off. A digital v3r4 or later board needs an analog module 3.5 or later." } + }, + "BP0081": { + "name": "lan_not_paired", + "area": "policy", + "since": "next", + "message": "This computer is not paired with the pod: {cmd} needs pairing over USB or from the cloud", + "cause": "The pod only takes commands from the LAN (Ethernet, Wi-Fi) from computers paired with it. An unpaired computer may only read the pod's status and whether it is registered. Pairing adds this computer's TLS client key to the pod: over the pod's USB-C cable once, or from embeddedci.com for a registered pod. USB itself never needs pairing.", + "args": { + "cmd": "str" + }, + "fix": { + "sdk": "pair this computer once: connect over USB and call bp.pair() (or run `benchpod setup`), or use the cloud (\"embeddedci:\")", + "cli": "plug the pod into this computer's USB-C port and run `benchpod setup` once, or use the cloud (--connection embeddedci:)", + "mcp": "tell the user this computer is not paired with the pod: they plug the pod into it over USB-C once and run `benchpod setup`, or connect through the cloud ('embeddedci:')", + "web": "This computer is not paired with the pod. Pair it from the pod's Settings tab, or plug the pod in over USB and run benchpod setup." + } + }, + "BP0082": { + "name": "lan_clients_full", + "area": "policy", + "since": "next", + "message": "The pod already has {max} paired computers", + "cause": "The pod keeps at most {max} paired computers (fewer when a large user certificate fills its flash record).", + "args": { + "max": "int" + }, + "fix": { + "sdk": "remove a computer you no longer use (bp.lan_clients(remove=...)) over USB or the cloud, then pair again", + "cli": "remove a computer you no longer use with `benchpod lan-clients remove `, then pair again", + "mcp": "tell the user the pod's list of paired computers is full; they remove one they no longer use", + "web": "This pod's list of paired computers is full. Remove one you no longer use." + } } } } diff --git a/packages/embeddedci/src/embeddedci/benchpod/errors.py b/packages/embeddedci/src/embeddedci/benchpod/errors.py index 9fb55da..851b980 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/errors.py +++ b/packages/embeddedci/src/embeddedci/benchpod/errors.py @@ -233,6 +233,14 @@ class PodLockedError(FirmwareError): TLS on 8443, the SDK's default).""" +class PodNotPairedError(PodLockedError): + """This computer is not paired with the pod (``BP0081``, firmware 4.0.1+): over Ethernet and + Wi-Fi it may only read the pod's status. Pair it once over the pod's USB cable with + :meth:`~embeddedci.benchpod.BenchPod.pair` (or ``benchpod setup``), or use the cloud + (``embeddedci:``). A :class:`PodLockedError`, so code that handles the LAN policy + handles this too.""" + + class PodBusyError(FirmwareError): """The pod refused because it is busy: an I2C, SPI, UART or SWD session is already open (``BP0003``, ``BP0004``, ``BP0049``, ``BP0050``), the engine that runs SWD, SPI and I2C is in @@ -557,6 +565,8 @@ def _pin_conflict(v: Mapping[str, Any], cmd: Optional[str]) -> Dict[str, Any]: "BP0079": (FirmwareError, _NO_FIELDS), # usb_host_other_port {port} "BP0080": (DacPinoutMismatchError, # dac_pinout_mismatch lambda v, cmd: {"digital": _str(v.get("digital")), "module": _str(v.get("module"))}), + "BP0081": (PodNotPairedError, _NO_FIELDS), # lan_not_paired {cmd} + "BP0082": (FirmwareError, _NO_FIELDS), # lan_clients_full {max} } diff --git a/packages/embeddedci/src/embeddedci/benchpod/feature_map.json b/packages/embeddedci/src/embeddedci/benchpod/feature_map.json index 1515380..0c7fa1d 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/feature_map.json +++ b/packages/embeddedci/src/embeddedci/benchpod/feature_map.json @@ -1,10 +1,10 @@ { "_generated": "GENERATED by tools/gen_features.py from features/features.toml. DO NOT EDIT: edit the table.", "schema": 1, - "revision": 12, + "revision": 13, "api": 2, "min_client_api": 2, - "table_sha256": "875940ed02d7f8b7a9058803971565fc38e7f095d1795a80ee83627c563736dd", + "table_sha256": "4035ec709c8ba5a22bab6138d6cc18c22e1ff6f2d05569e833541f26a7808eaa", "floor": "3.9.2", "docs_base": "https://github.com/embeddedci-com/benchpod-firmware/blob/main/docs/", "facts": { @@ -775,6 +775,12 @@ "firmware": "next", "board": "any", "docs": "API.md#la_pins--report-every-la-pin" + }, + "lan_pairing": { + "rev": 13, + "firmware": "next", + "board": "any", + "docs": "API.md#lan_clients--paired-computers" } } } diff --git a/packages/embeddedci/src/embeddedci/benchpod/results.py b/packages/embeddedci/src/embeddedci/benchpod/results.py index 6edbcd8..8924ffb 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/results.py +++ b/packages/embeddedci/src/embeddedci/benchpod/results.py @@ -381,6 +381,37 @@ class MacAddresses: source: str = "" # "pod" (its status), "server" (embeddedci.com's record) or "" +@dataclass(frozen=True) +class LanClient: + """One computer paired with the pod (:meth:`BenchPod.lan_clients`).""" + + name: str + spki_sha256: str # SHA-256 of its TLS client key's SubjectPublicKeyInfo + this: bool = False # this computer's own key + + +@dataclass(frozen=True) +class LanClients: + """The computers paired with the pod for the LAN API (firmware 4.0.1+).""" + + pairing: bool # whether computers on Ethernet/Wi-Fi must be paired + count: int + max: int + clients: Tuple[LanClient, ...] = () + + @classmethod + def from_reply(cls, data: Any, mine: str = "") -> "LanClients": + d = data if isinstance(data, dict) else {} + cl = tuple(LanClient(name=str(c.get("name", "")), spki_sha256=str(c.get("spki_sha256", "")), + this=bool(mine) and str(c.get("spki_sha256", "")).lower() == mine.lower()) + for c in (d.get("clients") or []) if isinstance(c, dict)) + return cls(pairing=bool(d.get("pairing")), count=int(d.get("count") or len(cl)), + max=int(d.get("max") or 0), clients=cl) + + def has(self, spki_sha256: str) -> bool: + return any(c.spki_sha256.lower() == spki_sha256.lower() for c in self.clients) + + @dataclass(frozen=True) class LanTls: """The pod's LAN API over TLS (:meth:`BenchPod.lan_tls`, firmware 3.9.3+).""" diff --git a/packages/embeddedci/src/embeddedci/benchpod/transport/client_identity.py b/packages/embeddedci/src/embeddedci/benchpod/transport/client_identity.py new file mode 100644 index 0000000..af55714 --- /dev/null +++ b/packages/embeddedci/src/embeddedci/benchpod/transport/client_identity.py @@ -0,0 +1,198 @@ +"""This computer's TLS client identity for LAN pairing (firmware 4.0.1+), as ``benchpod`` keeps it +(its ``tcpclient/clientid.go``). + +The pod asks every client on port 8443 for a certificate and lets in beyond ``status`` only the +ones whose public key is on its list of paired computers. Pairing puts the key there, over the +pod's USB cable (:meth:`~embeddedci.benchpod.BenchPod.pair`, ``benchpod setup``) or from +embeddedci.com. + +One key per user, shared with ``benchpod`` and the MCP server: ``client.key`` (EC P-256, PKCS#8) +and ``client.crt`` (self-signed) next to ``known_pods.json`` in ``benchpod-cli``'s config +directory, made on first use. A CI runner passes its own instead: + +- ``BENCHPOD_CLIENT_KEY_PEM``: the certificate and key PEM (``benchpod lan-clients add --new-key`` + prints one), for a CI secret; +- ``BENCHPOD_CLIENT_CERT`` and ``BENCHPOD_CLIENT_KEY``: files. +""" + +from __future__ import annotations + +import atexit +import datetime as _dt +import hashlib +import os +import socket +import tempfile +import threading +import time +from pathlib import Path +from typing import Optional, Tuple + +from ..cli_config import config_dir + +CLIENT_KEY_FILE = "client.key" +CLIENT_CERT_FILE = "client.crt" + +_lock = threading.Lock() +_files: Optional[Tuple[str, str]] = None +_tmp_files: list = [] + +#: Overrides the directory ``client.key`` and ``client.crt`` live in (tests). +identity_dir: Optional[Path] = None + + +def _dir() -> Path: + return identity_dir if identity_dir is not None else config_dir() + + +def reset() -> None: + """Forget the cached identity (tests, and after the files change).""" + global _files + with _lock: + _files = None + + +def new_identity_pem(cn: str) -> Tuple[bytes, bytes]: + """A new EC P-256 key and a self-signed client certificate for it: ``(cert_pem, key_pem)``.""" + from cryptography import x509 + from cryptography.hazmat.primitives import hashes, serialization + from cryptography.hazmat.primitives.asymmetric import ec + from cryptography.x509.oid import ExtendedKeyUsageOID, NameOID + + key = ec.generate_private_key(ec.SECP256R1()) + name = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, cn)]) + now = _dt.datetime.now(_dt.timezone.utc) + cert = ( + x509.CertificateBuilder() + .subject_name(name) + .issuer_name(name) + .public_key(key.public_key()) + .serial_number(x509.random_serial_number()) + .not_valid_before(now - _dt.timedelta(hours=1)) + .not_valid_after(now + _dt.timedelta(days=365 * 100)) # the pod checks the key, not the dates + .add_extension(x509.KeyUsage(digital_signature=True, content_commitment=False, + key_encipherment=False, data_encipherment=False, + key_agreement=False, key_cert_sign=False, crl_sign=False, + encipher_only=False, decipher_only=False), critical=True) + .add_extension(x509.ExtendedKeyUsage([ExtendedKeyUsageOID.CLIENT_AUTH]), critical=False) + .sign(key, hashes.SHA256()) + ) + return (cert.public_bytes(serialization.Encoding.PEM), + key.private_bytes(serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8, + serialization.NoEncryption())) + + +def _write_exclusive(path: Path, data: bytes, mode: int) -> None: + fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode) + try: + os.write(fd, data) + except BaseException: + os.close(fd) + os.unlink(str(path)) + raise + os.close(fd) + + +def _from_env_pem(pem: str) -> Tuple[str, str]: + """``ssl`` loads a certificate chain only from files: the environment's PEM goes to a private + temporary file for this process.""" + fd, path = tempfile.mkstemp(prefix="benchpod-client-", suffix=".pem") + with os.fdopen(fd, "w") as f: + f.write(pem.strip() + "\n") + os.chmod(path, 0o600) + _tmp_files.append(path) + return path, path + + +@atexit.register +def _cleanup() -> None: + for p in _tmp_files: + try: + os.unlink(p) + except OSError: + pass + + +def _load() -> Tuple[str, str]: + pem = os.environ.get("BENCHPOD_CLIENT_KEY_PEM", "").strip() + if pem: + return _from_env_pem(pem) + cert_file, key_file = os.environ.get("BENCHPOD_CLIENT_CERT", ""), os.environ.get("BENCHPOD_CLIENT_KEY", "") + if cert_file or key_file: + if not (cert_file and key_file): + raise ValueError("set both BENCHPOD_CLIENT_CERT and BENCHPOD_CLIENT_KEY") + return cert_file, key_file + d = _dir() + cert_path, key_path = d / CLIENT_CERT_FILE, d / CLIENT_KEY_FILE + if cert_path.exists() and key_path.exists(): + return str(cert_path), str(key_path) + cert_pem, key_pem = new_identity_pem("benchpod client " + (socket.gethostname() or "computer")) + d.mkdir(parents=True, exist_ok=True) + try: + # The key first and exclusively: two processes (or this and benchpod) starting at once + # must not end up with two keys. The loser waits for the winner's certificate. + _write_exclusive(key_path, key_pem, 0o600) + except FileExistsError: + for _ in range(50): + if cert_path.exists(): + return str(cert_path), str(key_path) + time.sleep(0.02) + raise + _write_exclusive(cert_path, cert_pem, 0o644) + return str(cert_path), str(key_path) + + +def identity_files() -> Optional[Tuple[str, str]]: + """``(certfile, keyfile)`` of this computer's identity, made on first use; ``None`` when it + cannot be read or made (the pod then treats the connection as unpaired and says so).""" + global _files + with _lock: + if _files is None: + try: + _files = _load() + except (ImportError, OSError, ValueError): + return None + return _files + + +def spki_sha256_of_pem(cert_pem: bytes) -> str: + """What the pod lists a paired computer by: the SHA-256 (hex) of the certificate's DER + SubjectPublicKeyInfo.""" + from cryptography import x509 + from cryptography.hazmat.primitives import serialization + + cert = x509.load_pem_x509_certificate(cert_pem) + spki = cert.public_key().public_bytes(serialization.Encoding.DER, + serialization.PublicFormat.SubjectPublicKeyInfo) + return hashlib.sha256(spki).hexdigest() + + +def client_key_hash() -> str: + """:func:`spki_sha256_of_pem` of this computer's identity.""" + files = identity_files() + if files is None: + raise RuntimeError("no TLS client identity: install the 'cryptography' package, or set " + "BENCHPOD_CLIENT_KEY_PEM") + return spki_sha256_of_pem(Path(files[0]).read_bytes()) + + +def sanitize_name(s: str) -> str: + """A name the pod takes: 1-23 printable characters, no spaces (the USB console takes it too).""" + out = [] + for ch in s: + if ch in " \t": + out.append("-") + elif 0x21 <= ord(ch) <= 0x7E and ch not in "\"\\": + out.append(ch) + if len(out) >= 23: + break + name = "".join(out).strip("-")[:23] + return name or "computer" + + +def pairing_name() -> str: + """This computer's host name as a pairing name.""" + h = socket.gethostname() or "" + if h.endswith(".local"): + h = h[: -len(".local")] + return sanitize_name(h) diff --git a/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py b/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py index d1c3af0..449ecd5 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py +++ b/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py @@ -21,6 +21,7 @@ BenchPodError, ConnectionClosedError, ConnectionConfigError, + FirmwareError, TransportError, TransportTimeout, ) @@ -54,7 +55,7 @@ #: JSON commands the text console answers through its text equivalents (it has no JSON mode): #: firmware 4.0's console keeps status, ping and identity; everything else is on the JSON API #: (the LAN, the USB network adapter or the cloud). -TEXT_CONSOLE_COMMANDS = ("status", "ping") +TEXT_CONSOLE_COMMANDS = ("status", "ping", "lan_clients", "lan_tls") @contextmanager @@ -445,6 +446,29 @@ def _text_ping(self, req: dict) -> str: raise TransportError(f"the pod did not answer ping: {out.strip()!r}") return "pong" + def _text_lan_clients(self, req: dict) -> Dict[str, Any]: + """``lan_clients`` through the console's ``lan-clients`` (firmware 4.0.1+): pairing works + here also while the USB network adapter is off. The reply has the JSON command's shape.""" + if req.get("add") is not None: + name, key = str(req["add"]), str(req.get("spki_sha256", "")) + if not name or any(c in name for c in " \t\"\r\n"): + raise ValueError(f"lan_clients add: {name!r}: over the USB console a name has no spaces") + line = f"lan-clients add {name} {key.lower()}" + elif req.get("remove") is not None: + line = f"lan-clients remove {req['remove']}" + elif req.get("clear"): + line = "lan-clients clear" + else: + line = "lan-clients" + return parse_text_lan_clients(self._send_command(line), line) + + def _text_lan_tls(self, req: dict) -> Dict[str, Any]: + """``lan_tls`` (a read) through the console's ``lan-tls``: the port, HTTPS-only, SCPI and + the certificate's SHA-256.""" + if len(req) > 1: + raise TransportError(self._unsupported("lan_tls (a change)")) + return parse_text_lan_tls(self._send_command("lan-tls")) + def _needs_network(self, what: str) -> TransportError: """The USB console of firmware 4.0 answers status, ping and identity only.""" return TransportError( @@ -471,3 +495,74 @@ def close(self) -> None: self._port.close() except Exception: pass + + +def _console_reply_lines(raw: str, line: str) -> List[str]: + out, echo_seen = [], False + for ln in raw.replace("\r\n", "\n").replace("\r", "\n").split("\n"): + ln = ln.strip().lstrip(">").strip() + if not ln: + continue + if not echo_seen and ln == line: + echo_seen = True + continue + out.append(ln) + return out + + +def _console_refusal(cmd: str, raw: str, rest: str) -> None: + if "unknown command" in raw: + raise TransportError(f"this firmware has no {cmd} on its USB console (firmware 4.0.1+)") + if rest == "error" or rest.startswith("error "): + why = rest[5:].strip() or "refused" + raise FirmwareError(f"{cmd}: {why}") + + +def parse_text_lan_clients(raw: str, line: str = "lan-clients") -> Dict[str, Any]: + """The console's ``lan-clients`` reply as the JSON command's ``data``.""" + data: Dict[str, Any] = {} + header = False + for ln in _console_reply_lines(raw, line): + if ln.startswith("lan-clients "): + rest = ln[len("lan-clients "):].strip() + _console_refusal("lan-clients", raw, rest) + if rest in ("added", "renamed", "same"): + data["outcome"] = rest + continue + f = rest.replace(",", " ").split() + if len(f) >= 3 and f[1] == "of" and f[0].isdigit() and f[2].isdigit(): + data.update(count=int(f[0]), max=int(f[2]), offset=0, clients=[], + pairing=len(f) >= 5 and f[3] == "pairing" and f[4] == "on") + header = True + continue + if header: + f = ln.split() + if len(f) == 2 and len(f[1]) == 64: + data["clients"].append({"name": f[0], "spki_sha256": f[1]}) + if not header: + _console_refusal("lan-clients", raw, "") + raise TransportError(f"the pod did not answer lan-clients: {raw.strip()[-200:]!r}") + return data + + +def parse_text_lan_tls(raw: str) -> Dict[str, Any]: + """The console's ``lan-tls`` reply: ``lan-tls port 8443 https-only on sha256 ... scpi off``.""" + for ln in reversed(_console_reply_lines(raw, "lan-tls")): + if not ln.startswith("lan-tls "): + continue + rest = ln[len("lan-tls "):].strip() + _console_refusal("lan-tls", raw, rest) + f = rest.split() + out: Dict[str, Any] = {"sha256": ""} + for i in range(len(f) - 1): + if f[i] == "port" and f[i + 1].isdigit(): + out["port"] = int(f[i + 1]) + elif f[i] == "https-only": + out["https_only"] = f[i + 1] == "on" + elif f[i] == "sha256" and len(f[i + 1]) == 64: + out["sha256"] = f[i + 1].lower() + elif f[i] == "scpi": + out["scpi"] = f[i + 1] == "on" + return out + _console_refusal("lan-tls", raw, "") + raise TransportError(f"the pod did not answer lan-tls: {raw.strip()[-200:]!r}") diff --git a/packages/embeddedci/src/embeddedci/benchpod/transport/tls.py b/packages/embeddedci/src/embeddedci/benchpod/transport/tls.py index 013cc41..d56c325 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/transport/tls.py +++ b/packages/embeddedci/src/embeddedci/benchpod/transport/tls.py @@ -34,6 +34,7 @@ from typing import Dict, NamedTuple, Optional, Tuple from ..cli_config import config_dir +from . import client_identity PLAIN_PORT = 8080 TLS_PORT = 8443 @@ -206,6 +207,14 @@ def _context(ca: Optional[str], verify: bool) -> ssl.SSLContext: ctx.check_hostname = False ctx.verify_mode = ssl.CERT_NONE # the pin is the check ctx.minimum_version = ssl.TLSVersion.TLSv1_2 + # LAN pairing (client_identity.py): firmware 4.0.1+ asks for a client certificate and + # lets in only paired keys beyond status; older firmware never asks. + files = client_identity.identity_files() + if files is not None: + try: + ctx.load_cert_chain(files[0], files[1]) + except (OSError, ssl.SSLError): + pass _contexts[key] = ctx return ctx diff --git a/packages/embeddedci/tests/api_surface.json b/packages/embeddedci/tests/api_surface.json index 49311ef..5540614 100644 --- a/packages/embeddedci/tests/api_surface.json +++ b/packages/embeddedci/tests/api_surface.json @@ -140,6 +140,7 @@ "la_dir": "(self, la: 'Union[Pin, int, str, Sequence[Union[Pin, int, str]], None]' = None, dir: 'Optional[str]' = None) -> 'List[LaPinState]'", "la_pins": "(self, la: 'Union[Pin, int, str, Sequence[Union[Pin, int, str]], None]' = None) -> 'List[LaPinState]'", "la_step": "(self, la: 'Union[Pin, int]', *, steps: 'int', delay: 'float', dir_la: 'Optional[Union[Pin, int]]' = None, direction: 'int' = 0) -> 'Dict[str, Any]'", + "lan_clients": "(self, *, add: 'Optional[str]' = None, spki_sha256: 'Optional[str]' = None, remove: 'Optional[str]' = None, clear: 'bool' = False) -> \"'LanClients'\"", "lan_tls": "(self) -> \"'LanTls'\"", "leased": "property", "load_wiring": "(self, name: 'Optional[str]' = None) -> 'Wiring'", @@ -155,6 +156,7 @@ "open_motor_emulator": "(self, *, sck: 'Union[Pin, int, str, None]' = None, mosi: 'Union[Pin, int, str, None]' = None, miso: 'Union[Pin, int, str, None]' = None, cs: 'Union[Pin, int, str, None]' = None, programn: 'Union[Pin, int, str, None]' = None, done: 'Union[Pin, int, str, None]' = None, hz: 'int' = 6000000, calibration: 'Optional[_motor_emulator.EmulatorCalibration]' = None) -> '_motor_emulator.MotorEmulator'", "open_spi": "(self, *, sck: 'Union[Pin, int, str, None]' = None, mosi: 'Union[Pin, int, str, None]' = None, miso: 'Union[Pin, int, str, None]' = None, cs: 'Union[Pin, int, str, None]' = None, hz: 'int' = 1000000, mode: 'int' = 0) -> '_spi.SpiSession'", "open_uart": "(self, *, rx: 'Union[Pin, int, str, None]' = None, tx: 'Union[Pin, int, str, None]' = None, baud: 'Optional[int]' = None, max_buffer: 'int' = 1048576, parity: 'Optional[str]' = None, stop_bits: 'Optional[int]' = None, encoding: 'str' = 'utf-8', half_duplex: 'bool' = False, entry: 'Optional[_uart.UartEntry]' = None, de: 'Union[Pin, int, str, None]' = None, de_active_low: 'bool' = False) -> '_uart.UartSession'", + "pair": "(self, name: 'Optional[str]' = None) -> \"'LanClients'\"", "pin_directions": "(self, wiring: 'Optional[Wiring]' = None) -> 'Dict[int, str]'", "pin_levels": "(self) -> 'Dict[int, int]'", "ping": "(self) -> 'Any'", @@ -179,6 +181,7 @@ "set_default_wiring": "(self, name: 'str') -> 'str'", "set_gpio": "(self, la: 'Union[Pin, int, str, Sequence[Union[Pin, int, str]]]', level: 'Union[int, Sequence[int]]') -> 'None'", "set_la_voltage": "(self, voltage: 'float') -> 'LaVoltage'", + "set_lan_pairing": "(self, on: 'bool') -> 'bool'", "set_lan_tls_cert": "(self, cert_pem: 'Union[str, bytes]', key_pem: 'Union[str, bytes]') -> \"'LanTls'\"", "set_lan_tls_https_only": "(self, on: 'bool') -> \"'LanTls'\"", "set_log_level": "(self, level: 'str') -> 'str'", @@ -761,6 +764,23 @@ "from_reply": "(cls, reply: 'Any') -> \"'LaVoltage'\"", "is_set": "property" }, + "LanClient": { + "__fields__": [ + "name", + "spki_sha256", + "this" + ] + }, + "LanClients": { + "__fields__": [ + "pairing", + "count", + "max", + "clients" + ], + "from_reply": "(cls, data: 'Any', mine: 'str' = '') -> \"'LanClients'\"", + "has": "(self, spki_sha256: 'str') -> 'bool'" + }, "LanTls": { "__fields__": [ "port", @@ -933,6 +953,7 @@ "__init__": "(self, message: 'str', *, cmd: 'Optional[str]' = None, holder: 'str' = '', left_s: 'Optional[int]' = None, expires_at: 'str' = '', status: 'Optional[int]' = None, purpose: 'str' = '') -> 'None'" }, "PodLockedError": {}, + "PodNotPairedError": {}, "PowerProfile": { "__fields__": [ "efuse", @@ -1426,6 +1447,8 @@ "LaCapture", "LaPinState", "LaVoltage", + "LanClient", + "LanClients", "LanTls", "LibraryEntry", "LocalLease", @@ -1458,6 +1481,7 @@ "PodLeaseLostError", "PodLeasedError", "PodLockedError", + "PodNotPairedError", "PowerProfile", "PowerProfileSession", "PowerStatus", diff --git a/packages/embeddedci/tests/test_error_codes.py b/packages/embeddedci/tests/test_error_codes.py index 6fbce9a..ce0c680 100644 --- a/packages/embeddedci/tests/test_error_codes.py +++ b/packages/embeddedci/tests/test_error_codes.py @@ -23,6 +23,7 @@ PodLeasedError, PodLeaseLostError, PodLockedError, + PodNotPairedError, PullConflictError, PullDirectionError, ReplyTooLargeError, @@ -88,6 +89,8 @@ "BP0079": (FirmwareError, {}), "BP0080": (DacPinoutMismatchError, {"digital": "v_digital", "module": "v_module", "feature": "dac"}), + "BP0081": (PodNotPairedError, {}), + "BP0082": (FirmwareError, {}), } diff --git a/packages/embeddedci/tests/test_lan_pairing.py b/packages/embeddedci/tests/test_lan_pairing.py new file mode 100644 index 0000000..28ef3df --- /dev/null +++ b/packages/embeddedci/tests/test_lan_pairing.py @@ -0,0 +1,147 @@ +"""LAN pairing (firmware 4.0.1+): this computer's TLS client identity, the console's lan-clients and +lan-tls replies, and BenchPod.lan_clients / pair.""" + +import hashlib +import os +import ssl +import stat + +import pytest + +from embeddedci.benchpod import BenchPod, LanClients, PodLockedError, PodNotPairedError +from embeddedci.benchpod.errors import FirmwareError, firmware_error +from embeddedci.benchpod.transport import client_identity as ci +from embeddedci.benchpod.transport import tls as _tls +from embeddedci.benchpod.transport.serial import parse_text_lan_clients, parse_text_lan_tls + +KEY_A = "3f0c9a1e" + "0" * 55 + "a" +KEY_B = "9b2e" + "0" * 59 + "b" + + +@pytest.fixture +def idir(tmp_path, monkeypatch): + monkeypatch.setattr(ci, "identity_dir", tmp_path) + for v in ("BENCHPOD_CLIENT_KEY_PEM", "BENCHPOD_CLIENT_CERT", "BENCHPOD_CLIENT_KEY"): + monkeypatch.delenv(v, raising=False) + ci.reset() + yield tmp_path + ci.reset() + + +def test_identity_made_once_and_kept(idir): + a = ci.client_key_hash() + assert len(a) == 64 + assert stat.S_IMODE(os.stat(idir / "client.key").st_mode) == 0o600 + ci.reset() + assert ci.client_key_hash() == a + # ssl takes the files as they are + ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT) + ctx.load_cert_chain(*ci.identity_files()) + + +def test_spki_hash_is_the_public_key_hash(idir): + from cryptography import x509 + from cryptography.hazmat.primitives import serialization + cert_pem, _ = ci.new_identity_pem("x") + spki = x509.load_pem_x509_certificate(cert_pem).public_key().public_bytes( + serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo) + assert ci.spki_sha256_of_pem(cert_pem) == hashlib.sha256(spki).hexdigest() + + +def test_identity_from_env_pem(idir, monkeypatch): + cert_pem, key_pem = ci.new_identity_pem("ci-runner-1") + monkeypatch.setenv("BENCHPOD_CLIENT_KEY_PEM", (cert_pem + key_pem).decode()) + ci.reset() + assert ci.client_key_hash() == ci.spki_sha256_of_pem(cert_pem) + assert list(idir.iterdir()) == [] # nothing written next to known_pods.json + + +def test_half_the_file_variables_is_no_identity(idir, monkeypatch): + monkeypatch.setenv("BENCHPOD_CLIENT_CERT", "/nope.crt") + ci.reset() + assert ci.identity_files() is None + + +@pytest.mark.parametrize("raw,want", [ + ("Edward's MacBook Pro", "Edward's-MacBook-Pro"), + ('a"b\\c', "abc"), + ("", "computer"), + ("build-runner-with-a-very-long-name-01", "build-runner-with-a-ver"), +]) +def test_sanitize_name(raw, want): + assert ci.sanitize_name(raw) == want + + +def test_parse_console_lan_clients(): + line = f"lan-clients add laptop {KEY_A}" + raw = (f"> {line}\r\n[net] noise\r\nlan-clients added\r\nlan-clients 2 of 32, pairing on\r\n" + f" laptop {KEY_A}\r\n ci-runner-1 {KEY_B}\r\n> ") + d = parse_text_lan_clients(raw, line) + assert d["outcome"] == "added" and d["count"] == 2 and d["max"] == 32 and d["pairing"] is True + assert [c["name"] for c in d["clients"]] == ["laptop", "ci-runner-1"] + with pytest.raises(FirmwareError, match="out of memory"): + parse_text_lan_clients("lan-clients clear\r\nlan-clients error out of memory\r\n", "lan-clients clear") + + +def test_parse_console_lan_tls(): + raw = (f'lan-tls\r\nlan-tls port 8443 https-only on sha256 {KEY_A.upper()} generated "EC P-256" ' + '"CN=benchpod-30a9f1" "benchpod-30a9f1" scpi off\r\n> ') + d = parse_text_lan_tls(raw) + assert d == {"sha256": KEY_A, "port": 8443, "https_only": True, "scpi": False} + + +def test_not_paired_is_a_locked_error(): + e = firmware_error("", cmd="generate", code="BP0081", values={"cmd": "generate"}) + assert isinstance(e, PodNotPairedError) and isinstance(e, PodLockedError) + assert "not paired" in str(e) + + +class _FakeTransport: + """The JSON commands pair and lan_clients send, answered like a 4.0.1 pod over USB.""" + + def __init__(self, n_clients=0): + self.sent = [] + self.clients = [{"name": f"c{i}", "spki_sha256": f"{i:064x}"} for i in range(n_clients)] + + def command(self, req): + self.sent.append(req) + if req["cmd"] == "lan_clients": + if "add" in req: + self.clients.append({"name": req["add"], "spki_sha256": req["spki_sha256"]}) + off = int(req.get("offset", 0)) + return {"pairing": True, "count": len(self.clients), "max": 32, "offset": off, + "clients": self.clients[off:off + 12]} + if req["cmd"] == "lan_tls": + return {"port": 8443, "sha256": KEY_B} + raise AssertionError(req) + + def status(self): + return {"ip": "192.168.1.150"} + + def close(self): + pass + + +def _pod(t): + bp = BenchPod.__new__(BenchPod) + bp._transport = t + bp.command = t.command + return bp + + +def test_lan_clients_reads_every_page(idir): + t = _FakeTransport(n_clients=30) + got = _pod(t).lan_clients() + assert isinstance(got, LanClients) and got.count == 30 and len(got.clients) == 30 + assert [r.get("offset", 0) for r in t.sent] == [0, 12, 24] + + +def test_pair_adds_this_computer_and_pins_the_lan_certificate(idir, monkeypatch): + pins = {} + monkeypatch.setattr(_tls, "set_pin", lambda host, sha, port=8443, subject="": pins.update({host: sha})) + t = _FakeTransport() + got = _pod(t).pair(name="my laptop") + mine = ci.client_key_hash() + assert t.sent[0] == {"cmd": "lan_clients", "add": "my-laptop", "spki_sha256": mine} + assert got.has(mine) and [c.this for c in got.clients] == [True] + assert pins == {"192.168.1.150": KEY_B}