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
+10 -1
View File
@@ -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).