docs(security): per-instance credential references (#835) and the user-certificate directory (#836)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
2026-11-11 03:52:48 -05:00
parent 63331b0416
commit 0810e808c9
4 changed files with 112 additions and 4 deletions
+79 -3
View File
@@ -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/<other-inst>/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/<other-instance>/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/<X>/…`, `secret:otopcua/galaxy/<X>/…`, `secret:opcuaclient/<X>/…`, `secret:heidenhain/<X>/…` (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/<VictimName>/…`. Consequence: two same-type drivers that share a *name* cannot use name-scoped
secrets — scope them by **driver id** (`secret:galaxy/<DriverInstanceId>/…`, 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/<its DriverInstanceId>/…` (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
`<LocalAppData>/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