Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -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:<ns>/<X>/…` 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
|
||||
|
||||
@@ -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 | `<LocalAppData>/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),
|
||||
|
||||
@@ -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:<name>` by re-creating
|
||||
the secret as `opcuaclient/<name>`. See [`docs/security.md`](../security.md) §"Credential references are namespaced per driver".
|
||||
A `secret:opcuaclient/<X>/…` 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 `<LocalAppData>/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).
|
||||
|
||||
+79
-3
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user