diff --git a/.claude/rules/drivers.md b/.claude/rules/drivers.md index aec25c30f..70cfd0fa9 100644 --- a/.claude/rules/drivers.md +++ b/.claude/rules/drivers.md @@ -351,6 +351,16 @@ host logger factory (wired in `DriverFactoryBootstrap`; the FOCAS and TwinCAT fa browsers/probes pass none (hard-fail), Heidenhain never has one. Chosen by call site — do not add a global flag, and do not hand the tracker to an admin-node path. Upgrade preflight: `CredentialReferencePreflightService` + the `/raw` banner. `docs/security.md` §"Credential references are namespaced per driver". +- **…and per instance (#835):** a `secret://…` whose first segment `X` is ANOTHER same-type driver's id or name + (case-insensitive; another-instance match beats an own-name match) is refused at save (`DriverConfigSaveGate.ValidateAsync`), + deploy (`CredentialReferenceOtherInstance`), Test Connect (`TestDriverConnect.DriverInstanceId`) and browse + (`OpenAsync(…, driverInstanceId, …)`; no ConfigDb ⇒ fail closed). One rule: `DriverCredentialPolicy.DescribeOtherInstanceProblems` + + `DriverInstanceIdentities`. The runtime adds no check (drivers don't know the fleet); `env:` is not instance-scoped. +- **Key-material file paths (#836):** OpcUaClient `UserCertificatePath` is a RELATIVE path inside + `Drivers:OpcUaClient:UserCertificateDirectory` (`DriverCredentialPolicy` path field + `CredentialFilePaths`, all seams; + load-time `ResolveWithin` = lexical + link-resolved containment, before the PFX password resolves). `LoadCertificate` + refuses an unresolved (relative) path — build identities only from `ResolveSecretRefsAsync` output. A running driver's + pre-#836 ABSOLUTE path stays warn-only (`LegacyCredentialReferenceTracker.ReportPath`). - **Native condition state survives a full rebuild (#641):** `RebuildAddressSpace` captures each NATIVE condition's live node state (client acks included), the same-apply re-materialise restores it, and `CompleteAddressSpaceApply` (called by `OpcUaPublishActor` at the end of every apply) reports ONE event per restored off-normal condition and diff --git a/docs/Configuration.md b/docs/Configuration.md index 23f2e0e55..6de77c70f 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -540,6 +540,19 @@ deploy that recreates the driver), not on `ReinitializeAsync`. The init log line `transport=Libplctag (node default)` when the pin is what selected the stack. There is **no AbLegacy counterpart**: an AbLegacy driver with no key always runs libplctag (Native is opt-in per driver). +### `Drivers:OpcUaClient:UserCertificateDirectory` (user-certificate directory, #836) + +- **Purpose:** the ONLY directory an OpcUaClient driver's `UserCertificatePath` (user-certificate identity) may load a + PFX from. The authored path is relative to it (`plant1/user.pfx`); absolute / UNC / drive paths and `..` are refused + at save, deploy, Test Connect and browse, and the resolved path — symbolic links / junctions included — must stay + inside it at load time. See [`security.md`](security.md) §"Key-material file paths are confined to a node directory". +- **Read** once at startup in `Program.cs` (`OpcUaUserCertificatePaths.Configure`) on every node: the driver (driver + role) and the AdminUI live browse (admin role) both load user certificates, so keep the same relative layout on both. + +| Key | Type | Default | Meaning | +|---|---|---|---| +| `UserCertificateDirectory` | string | `/OtOpcUa/pki/user-certificates` | Directory (made absolute at startup). Env form: `Drivers__OpcUaClient__UserCertificateDirectory`. ACL it to the service account + administrators. | + ### `Drivers:Galaxy:AckIdentityCache` (cached API-key → Galaxy ack identity set, #765) - **Purpose:** the node-wide set of API key ids that have a Galaxy ack identity (a `galaxy-ack-user` secret), diff --git a/docs/drivers/OpcUaClient.md b/docs/drivers/OpcUaClient.md index 2795ef89f..677493e6a 100644 --- a/docs/drivers/OpcUaClient.md +++ b/docs/drivers/OpcUaClient.md @@ -52,7 +52,7 @@ measurements; they are not fresh SDK 2.0.1 interoperability evidence. |---------|--------|------| | `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient/` | net10.0 | In-process driver — session lifetime, read / write / subscribe / alarm / history passthrough | | `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Browser/` | net10.0 | `IDriverBrowser` — live address-picker browse used by the AdminUI. Its side-panel `AttributesAsync` reads a variable's DataType / ValueRank / UserAccessLevel and maps them through the same `UpstreamAttributeMapping` discovery uses; it authenticates Anonymous, Username **or Certificate** through the driver's own `OpcUaUserIdentityFactory`, resolving `secret:` credentials through the host's secret store (fail-closed) — review 2026-10-21 O-5 (it was a stub, and Certificate was refused) | -| | | ⚠️ Browse Certificate auth reads `UserCertificatePath` on the **AdminUI host's** filesystem, which may differ from the driver node's; the browse session disposes the certificate it loaded when it closes. | +| | | ⚠️ Browse Certificate auth reads `UserCertificatePath` on the **AdminUI host's** filesystem (inside its `Drivers:OpcUaClient:UserCertificateDirectory`, #836), which may differ from the driver node's; the browse session disposes the certificate it loaded when it closes. | | `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Session/` | net10.0 | The SDK-typed layer the driver AND the browser share: `NamespaceMap`, `UpstreamAttributeMapping`, `OpcUaUserIdentityFactory` | | `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Contracts/` | net10.0 | Config records + enums bound from `DriverConfig` JSON | @@ -87,6 +87,15 @@ so any other `secret:`/`env:` reference (and `file:`) is refused at save, deploy Connect, browse and (for the AdminUI browser) again before anything is read; an already-deployed driver's session open keeps the pre-#815 semantics in deprecated warn-only mode until its next deploy. Migrate an existing `secret:` by re-creating the secret as `opcuaclient/`. See [`docs/security.md`](../security.md) §"Credential references are namespaced per driver". +A `secret:opcuaclient//…` reference may not name **another** OpcUaClient driver instance (by id or name) — #835, +§"Per-instance credential references". + +**User certificate (#836).** `UserCertificatePath` is a **relative** path (`plant1/user.pfx`) inside the node's +`Drivers:OpcUaClient:UserCertificateDirectory` (default `/OtOpcUa/pki/user-certificates`); absolute / UNC / +drive paths and `..` are refused at save, deploy, Test Connect and browse, and the resolved path (symbolic links / +junctions included) must stay inside the directory at load time. Put the PFX at the same relative path on the driver +nodes **and** the admin nodes (browse loads it there). An already-deployed absolute path keeps loading in deprecated +warn-only mode until the next deploy. See [`docs/security.md`](../security.md) §"Key-material file paths are confined to a node directory". `ProbeTimeoutSeconds` (default 15, AdminUI "Probe timeout") caps the Test-Connect probe's deadline — it can shorten the budget the host hands the probe, never extend it (review 2026-10-21 O-4; it used to be authored and consumed by nothing). diff --git a/docs/security.md b/docs/security.md index b2fa3e8e4..af7ec1b5b 100644 --- a/docs/security.md +++ b/docs/security.md @@ -1311,9 +1311,85 @@ driver, device, field, allowed form, never the value. The same list, plus runnin warn-only resolution (**Running**, from driver-health diagnostics, fleet-wide), is shown as a banner on `/raw`, with a Re-check button. -Residual (accepted): within one namespace, a Designer can still point one driver instance at another -instance's secret (e.g. `secret:galaxy//apikey`) — the value then reaches the endpoint the Designer -chose. Per-instance scoping is a possible follow-up. +#### Per-instance credential references (#835) + +The namespace confines a reference to values provisioned for that driver *type*, but not to one *instance*: before +#835 a Designer could create a Galaxy driver pointing at their own endpoint with +`secret:galaxy//apikey` (Test Connect, browse, or a deploy) and capture another instance's mxaccessgw +key. Now a reference's **instance-identifying segment** — the first path segment after the namespace, +`secret:galaxy//…`, `secret:otopcua/galaxy//…`, `secret:opcuaclient//…`, `secret:heidenhain//…` (also in +the `${secret:…}` spelling) — may not name **another existing driver instance of the same type**, matched against +that instance's **id or name**, case-insensitively. + +| Reference (in driver `DRV-a` / "PlantA") | Result | +|---|---| +| `secret:galaxy/DRV-a/apikey`, `secret:galaxy/PlantA/apikey` | allowed — its own | +| `secret:galaxy/gw/apikey`, `secret:galaxy/apikey` (no instance is called `gw` / `apikey`) | allowed — a shared key | +| `secret:galaxy/DRV-b/apikey`, `secret:galaxy/PlantB/apikey`, `secret:galaxy/plantb` | **refused** — another instance's | +| `env:OTOPCUA_GALAXY_…` | not checked — environment variables carry no instance convention (see residuals) | + +Rules worth knowing: + +- **A match against another instance wins over a match against the owner.** Names are unique per folder, not + fleet-wide, so a Designer who renames their own driver after a victim's must not unlock the victim's + `secret:galaxy//…`. Consequence: two same-type drivers that share a *name* cannot use name-scoped + secrets — scope them by **driver id** (`secret:galaxy//…`, ids are unique) instead. +- A driver **being created** owns nothing yet, so any reference naming an existing instance is refused. +- Creating or renaming a driver whose name equals a segment other drivers already use as a *shared* name makes those + drivers' next deploy fail (`CredentialReferenceOtherInstance`) — rename the shared secret or the driver. + +One rule — `DriverCredentialPolicy.DescribeOtherInstanceProblems` — at the same seams as #815, reading the instance list +through `DriverInstanceIdentities` (only when the config carries an in-scope `secret:` reference at all): + +1. **AdminUI save** — `DriverConfigSaveGate.ValidateAsync` (every `RawTreeService` driver/device create + update; the + owner is the driver itself, or the device's driver). +2. **Deploy gate** — `CredentialReferenceDeployChecks`, code **`CredentialReferenceOtherInstance`** (Heidenhain included). +3. **Test Connect** — `AdminOperationsActor`, before the probe; `TestDriverConnect.DriverInstanceId` names the owner + (the device modal passes it; omitted ⇒ treated as a new driver, i.e. stricter). +4. **Live browse** — `BrowserSessionService.OpenAsync(…, driverInstanceId, …)`, before any browser; `/raw` browse + resolves the owner from the device. Without a ConfigDb it fails closed. + +Already-running drivers: a deployed driver resolves its reference exactly as before (the driver itself does not know +the other instances, so the runtime adds no check) — the same deprecated window as #815: the deploy gate refuses the +config at its next deploy, and the upgrade preflight / `/raw` banner lists it (Draft and Deployed). Migration: store +the driver's own value under `galaxy//…` (or a shared name no instance uses) and point the field +at it. + +Residuals (accepted): `env:` references are not instance-scoped (a variable is node-wide, and there is no naming +convention to match — a deployment that needs per-instance isolation must use the secret store); and the rule cannot +stop a Designer from editing an **existing** driver's endpoint and Test-Connecting with that driver's own reference — +that is the general "anyone who may author config may redirect it" property described above (the lever is the page +policy). A gateway-side complement — mxaccessgw binding each API key to the client identity / Galaxy it was issued for +— would make a captured key useless elsewhere; that is cross-repo (`mxaccessgw`) and not implemented here. + +#### Key-material file paths are confined to a node directory (#836) + +OpcUaClient `UserCertificatePath` (user-certificate identity) names a PFX the node **loads and signs with** against the +author-chosen server. An unrestricted path let a Designer make the node sign a hostile server's nonce with any PFX the +service account can read (another product's client certificate, a host certificate under the profile, …). Now: + +- The field is a **relative path** (`plant1/user.pfx`) inside the node's user-certificate directory, + **`Drivers:OpcUaClient:UserCertificateDirectory`** (env `Drivers__OpcUaClient__UserCertificateDirectory`; default + `/OtOpcUa/pki/user-certificates`, beside the driver's PKI stores — for a service running as LocalSystem + that is under `C:\Windows\System32\config\systemprofile\AppData\Local`). Segments are `[A-Za-z0-9._-]`; an absolute, + rooted, drive-qualified or UNC path, `.`/`..`/empty segments and anything else are refused + (`CredentialFilePaths`, rule row `DriverCredentialPolicy.OpcUaClientUserCertificatePathField`). +- **Refused at the same five seams as #815** (save, deploy gate `CredentialReferenceOutOfScope`, Test Connect, browse — + messages never carry the path) and **at load time**: `OpcUaUserIdentityFactory.ResolveSecretRefsAsync` (called by the + running driver and the AdminUI browse before the identity is built) joins it to the directory, canonicalises it, and + requires both the lexical result **and the result with every symbolic link / junction resolved** to stay inside the + (equally link-resolved) directory; `LoadCertificate` refuses any path that was not resolved. The path is checked before + the PFX password is resolved. Residual: a check-then-open race (swapping a link between the check and the load) needs + write access to the directory, which only an administrator should have — keep it ACL'd to the service account + + administrators. +- **The admin nodes and the driver nodes must hold the same relative layout** (the browse loads the certificate on the + admin node). +- `UserCertificatePassword` stays covered by #815 (`secret:opcuaclient/…` / `env:OTOPCUA_OPCUACLIENT_…` / literal). +- **Already-running drivers (deprecated warn-only window):** a deployed driver whose path is a pre-#836 **absolute** path + keeps loading it, with a rate-limited Warning (driver + field, never the path) and a + `credential-compat:UserCertificatePath` diagnostics entry, until its next deploy (which the gate refuses). The AdminUI + browse never gets the tracker (hard-fail). Migration: move the PFX under the directory on every node that runs the + driver **and** the admin nodes, then set the field to its relative path. ### Role grant source