Merge branch 'master' into fix/832-docker-dev-batch
This commit is contained in:
@@ -81,7 +81,7 @@ Project root files:
|
||||
|
||||
`DriverConfig` JSON binds to `Config/GalaxyDriverOptions.cs`. The four sections are:
|
||||
|
||||
- **`Gateway`** — endpoint, API key secret ref, TLS knobs, connect/call/stream timeouts. `StreamTimeoutSeconds = 0` keeps the long-lived `StreamEvents` RPC open for the driver's lifetime.
|
||||
- **`Gateway`** — endpoint, API key secret ref (`secret:galaxy/<name>` · `secret:otopcua/galaxy/<name>` · `env:OTOPCUA_GALAXY_<NAME>` · legacy `env:GALAXY_MXGW_<NAME>` · `dev:KEY` · literal; anything else, incl. `file:`, is refused — #815 (an already-deployed driver keeps resolving a pre-#815 ref on init and every gateway reconnect in deprecated warn-only mode until its next deploy), [`docs/security.md`](../security.md) §"Credential references are namespaced per driver"), TLS knobs, connect/call/stream timeouts. `StreamTimeoutSeconds = 0` keeps the long-lived `StreamEvents` RPC open for the driver's lifetime.
|
||||
- **`MxAccess`** — `ClientName` (must be unique per OtOpcUa instance — redundancy pairs enforce uniqueness at install time), `PublishingIntervalMs` (forwarded as `buffered_update_interval_ms` on subscribe), `WriteUserId` for ArchestrA secured-write, `EventPumpChannelCapacity` (default 50_000 — one second of headroom at 50k tags / 1Hz; tune via the `galaxy.events.dropped` metric).
|
||||
- **`Repository`** — `DiscoverPageSize`, `WatchDeployEvents`.
|
||||
- **`Reconnect`** — `InitialBackoffMs`, `MaxBackoffMs`, `ReplayOnSessionLost` (calls the gateway's `ReplaySubscriptions` RPC after reconnect rather than re-issuing subscribe-bulk for every tag).
|
||||
@@ -103,8 +103,10 @@ Galaxy password, so `GalaxyAckCredentialResolver` picks the account per acknowle
|
||||
not silently downgraded to the fallback.
|
||||
2. **The driver's fallback account** — `AlarmAck.FallbackUser` / `FallbackDomain` /
|
||||
`FallbackPasswordSecretRef` in `DriverConfig`, used by keys without an identity and by anonymous
|
||||
sessions. The password ref must be `secret:NAME` / `${secret:NAME}` (production), `env:NAME`,
|
||||
`file:PATH` or `dev:VALUE`; a bare literal is refused so a password never sits in DriverConfig.
|
||||
sessions. The password ref must be `secret:galaxy/NAME` / `secret:otopcua/galaxy/NAME` (or the `${secret:…}`
|
||||
spelling; production), `env:OTOPCUA_GALAXY_NAME` / `env:GALAXY_MXGW_NAME`, or `dev:VALUE`; a bare literal, a
|
||||
`file:` reference or a reference outside the Galaxy namespace is refused (#815) — the password is sent to the
|
||||
authored gateway endpoint, so it must not be able to name another subsystem's secret.
|
||||
3. **Neither** → the driver throws `DriverOperationRefusedException`; **nothing is sent to the
|
||||
gateway**. The refusal is excluded from the resilience breaker (it says nothing about gateway
|
||||
health). How the client learns of it (#760):
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Heidenhain LSV2 driver (read-only)
|
||||
|
||||
`DriverType = "Heidenhain"` (`DriverTypeNames.Heidenhain`) · projects `Driver.Heidenhain` (+ `.Contracts`) ·
|
||||
Gitea **#803**.
|
||||
Gitea **#803** (native alarms + rediscovery: **#831**; authoring UX: **#830**).
|
||||
|
||||
A native, **read-only** Heidenhain LSV2 client over TCP (default port **19000**) for iTNC/TNC controls. No
|
||||
Java/Python runtime and no vendor SDK (RemoTools/DNC) — a managed `System.Net.Sockets` client. It is a port of the
|
||||
@@ -21,9 +21,12 @@ Three independent layers, each sufficient on its own for its concern:
|
||||
manual-entry grid also fix the access level at Read — and again by the deploy gate `HeidenhainTagWritable`, so no
|
||||
node is ever advertised writable. A `"writable": true` TagConfig key is rejected by the tag reader and dropped by
|
||||
the typed editor. The same paths tie `Tag.DataType` to what the driver publishes (the catalog type for a fixed
|
||||
address — `Float64` ⇒ `Double` — or the binding's declared type): the modals default it from the address, the
|
||||
save path refuses a mismatch, and the deploy gate `HeidenhainTagDataTypeMismatch` catches anything older
|
||||
(one rule, `HeidenhainTagRules`).
|
||||
address — `Float64` ⇒ `Double` — or the binding's declared type; `Boolean` for an `ALARM:` condition): the tag
|
||||
modal and the manual-entry grid **lock** the access level and data type to the driver's values (#830 — the grid
|
||||
used to offer a choice it silently replaced on commit), the CSV import's staged review grid flags a ReadWrite or
|
||||
mistyped row **in the preview**, the save path refuses a mismatch, and the deploy gate
|
||||
`HeidenhainTagDataTypeMismatch` catches anything older. One rule (`HeidenhainTagRules`), reached by every AdminUI
|
||||
path through the driver-dispatched `RawTagRowRules` (no call site names a driver).
|
||||
3. **Payload-aware outbound allowlist** (`Lsv2ReadOnlyPolicy`). `Lsv2Codec.Frame` — the only frame builder — checks
|
||||
command **and** payload immediately before any byte is written. There is no raw-command API (`Lsv2Client`'s
|
||||
public surface is pinned by a reflection test) and no configuration knob that widens it.
|
||||
@@ -66,6 +69,7 @@ enums, so the numeric-enum form/factory trap cannot occur):
|
||||
| `Access.DataEnabled` | false | Opt-in DATA login, attempted only when a `DATA:` binding exists (iTNC only) |
|
||||
| `Access.InspectPassword` / `DncPassword` / `DataPassword` | — | **References only** (below) |
|
||||
| `Polling.StatusMs` / `CustomMs` / `SlowMs` | 1000 / 1000 / 10000 | each 100–3600000 |
|
||||
| `Polling.AlarmMs` | 2000 | 100–3600000; the alarm walk behind `ALARM:` conditions — only for a control carrying an `ALARM:` tag ([Alarm conditions](#alarm-conditions-alarm-gitea-831)) |
|
||||
| `Polling.MaxAlarms` | 64 | 1–256 |
|
||||
| `Polling.TimersEnabled` | **false** | Experimental selectors 30–34 |
|
||||
| `Reconnect.InitialDelayMs` / `MaxDelayMs` | 1000 / 30000 | doubling backoff, bounded |
|
||||
@@ -90,8 +94,13 @@ Host at their own machine. Anything outside the namespace is refused by **every*
|
||||
(`HeidenhainOptionsParser`, so the factory and the probe), the resolver **again at resolve time**
|
||||
(`HeidenhainCredentials`, fail-closed independently of earlier validation), the AdminUI **save path**
|
||||
(`RawTreeService` create/update driver + device refuse the config server-side via `DriverConfigSaveGate`, and the
|
||||
driver/device modals disable Save while it is invalid — so a literal never reaches the config database), and the
|
||||
deploy gate `HeidenhainCredentialPersisted`. Messages never echo the value.
|
||||
driver/device modals disable Save while it is invalid and show the refusal **once**, below the form — the typed
|
||||
forms report only ranges/endpoints, #830 — so a literal never reaches the config database), and the deploy gate
|
||||
`HeidenhainCredentialPersisted`. Messages never echo the value. Since #815 the parser and resolver are
|
||||
the shared `CredentialReferences` / `DriverCredentialPolicy` (`Core.Abstractions`) that Galaxy and OpcUaClient use
|
||||
too, and Test Connect / live browse also refuse an out-of-namespace reference before any probe or browser runs; a
|
||||
prefix in another casing (`SECRET:`) is refused, and `${secret:heidenhain/<name>}` is accepted as a spelling of
|
||||
`secret:heidenhain/<name>`.
|
||||
|
||||
Resolved **at each login**, never held in options or session state. Fail-closed: an absent secret or unset
|
||||
variable fails the login rather than sending the reference text. An unusable **INSPECT** credential fails the
|
||||
@@ -147,6 +156,70 @@ truncates or wraps — otherwise `BadTypeMismatch`.
|
||||
|
||||
At most 256 PLC/DATA bindings per control (excess are skipped and reported on `/hosts`).
|
||||
|
||||
## Alarm conditions (`ALARM:`, Gitea #831)
|
||||
|
||||
The control exposes one flat active-alarm list (`R_RI 27` first, `28` next — class, group, number, text; only refusal
|
||||
57 ends it). Besides the `Alarms/*` typed arrays (unchanged), the list can drive **native OPC UA Part 9 conditions**:
|
||||
a raw tag whose address is an `ALARM:` selector **and** whose `TagConfig` carries the cross-driver `alarm` object is
|
||||
exactly one condition, `ConditionId` = the tag's RawPath (the key the host routes and fans on — raw device folder +
|
||||
every referencing equipment folder, per the v3 native-alarm model). Same opt-in-per-tag shape as FOCAS #647 and
|
||||
MTConnect #626.
|
||||
|
||||
```jsonc
|
||||
{ "address": "ALARM:CLASS=7", "dataType": "Boolean",
|
||||
"alarm": { "alarmType": "AlarmCondition", "severity": 800 } }
|
||||
```
|
||||
|
||||
| Address | Condition is active while… |
|
||||
|---|---|
|
||||
| `ALARM:*` | any alarm is active on the control (summary) |
|
||||
| `ALARM:OTHER` | an alarm is active that no **filter** selector on the same control claims |
|
||||
| `ALARM:CLASS=<r>[/GROUP=<r>][/NUMBER=<r>]` (any subset, any order, each key once) | an alarm matches every named field |
|
||||
|
||||
`<r>` is `n` or `lo..hi` (inclusive; `..` because numbers can be negative — a real iTNC 530 reports `-1`). CLASS/GROUP
|
||||
are 0–65535 (wire uint16), NUMBER is int32. **No semantic class/group names**: their meaning is undocumented in the
|
||||
reference (pyLSV2 / the Java port keep them raw), so nothing is guessed — observe `Alarms/Classes` / `Alarms/Groups` or
|
||||
a condition message, then filter. One parser (`HeidenhainAlarmSelector`) backs the editor, the deploy inspector and the
|
||||
driver.
|
||||
|
||||
- **Opt-in is the tag — nothing is on by default.** An existing config gains no condition and loses nothing; the
|
||||
`Alarms/*` arrays keep publishing. This follows FOCAS #647 (`AlarmProjection.Enabled` became a no-op: the authored
|
||||
tag is the switch) and MTConnect #626 (opt-in because alarm tags leave the value subscription). There is no
|
||||
driver-level enable flag.
|
||||
- **Pairing is enforced** (`HeidenhainTagDefinitionFactory`, so the editor, the save path, CSV and the deploy inspector
|
||||
agree): an `ALARM:` address without the `alarm` object, or an `alarm` object on any other address, is refused. The
|
||||
tag's data type is fixed at `Boolean`; it is never a value (`ReadAsync` answers `BadNotSupported`), never in a data
|
||||
subscription, never writable (the `HeidenhainTagWritable` gate still applies). The typed editor seeds
|
||||
`{"alarmType":"AlarmCondition","severity":700}` when you pick an `ALARM:` selector and drops it when you leave one.
|
||||
- **Identity** = (class, group, number, **text**) — the number alone is not unique (`-1` above). **Displayed alarm** is
|
||||
deterministic (ascending class, group, number, text), never wire order. Message:
|
||||
`-1 Run test of cutout channels (class 7, group 4) [+N more]`.
|
||||
- **Transitions** (the FOCAS #647 rules): inactive → active `Raise`; a key not in the told set appears, or the displayed
|
||||
alarm leaves while others remain → `Retrigger` (un-acknowledges — a statement the operator has not seen); a
|
||||
non-displayed member leaves → nothing; nothing matches → `Clear`.
|
||||
- **Severity**: an authored integer `alarm.severity` is the exact Part 9 severity; otherwise High (700). No
|
||||
class→severity table is invented.
|
||||
- **Diffed against what the server was TOLD**, recorded only while a handler is attached; the record lives on the
|
||||
driver instance (survives a reconnect / same-set re-subscribe / in-place re-init). A deploy respawns the driver and its
|
||||
first walk re-states still-active alarms with `Raise`, which the host treats as a re-statement (ack kept,
|
||||
`NativeAlarmProjector` #647).
|
||||
- **A failed walk is not "no alarms."** A refusal (e.g. 23/49 access denied → `BadUserAccessDenied`, 22/24 →
|
||||
`BadNotSupported`), a list overflow (`MaxAlarms` → `BadOutOfRange`), a decode error, telemetry disabled, or comms loss
|
||||
(`BadNoCommunication`) keeps every condition's Active/Acked state and annotates its **quality** once (quality-only
|
||||
event, no `/alerts` row, one Warning per episode); the next good walk lifts it to Good before diffing. Only a down
|
||||
session degrades health (the existing rule) — a refusal never does.
|
||||
- **Acknowledgement is local-only.** LSV2 has no acknowledge request and the read-only allowlist is **not** widened:
|
||||
`AcknowledgeAsync` is a no-op success, so the Part 9 Acknowledge / AddComment the host routes to it is applied (and
|
||||
pair-replicated) server-side — the FOCAS / MTConnect posture. Confirm, the shelve methods and Enable/Disable are
|
||||
refused `BadNotSupported` by the host for every native condition. The control clears an alarm when its cause is reset;
|
||||
an operator ack never reaches it.
|
||||
- **Traffic:** the walk is the same allowlisted `R_RI 27/28` the arrays use, on the control's single acquisition loop
|
||||
every `Polling.AlarmMs`, and only for a control that carries an `ALARM:` tag. No new command type exists
|
||||
(`HeidenhainAlarmTests` asserts the wire log is a subset of the read set and `Lsv2ReadOnlyPolicy` is unchanged).
|
||||
- **Authoring:** the `/raw` tag modal (`Native alarm` section + the typed editor), manual entry (the editor seeds the
|
||||
alarm object) and CSV (`Alarm.AlarmType` / `Alarm.Severity` columns). The browse picker offers only catalog leaves.
|
||||
- E2E: `Runtime.Tests/Drivers/HeidenhainNativeAlarmEndToEndTests` (real driver → simulator → real `DriverHostActor`).
|
||||
|
||||
## Quality
|
||||
|
||||
| Condition | Value status / capability |
|
||||
@@ -183,6 +256,11 @@ overrides, axes, tool, the whole alarm walk) and aliased custom addresses are re
|
||||
- Subscriptions: the initial push and later publications are ordered under one lock, so a subscriber never
|
||||
receives an older value after a newer one. A re-init disposes every control loop first; a late start of a
|
||||
disposed loop is a no-op.
|
||||
- **Rediscovery signal (`IRediscoverable`, #831):** every session already reads `R_VR` at connect; when a control
|
||||
reconnects reporting a **different** identity (model, NC/PLC software version or option string) than the previous
|
||||
session on this driver instance, the driver raises `OnRediscoveryNeeded` once with both identities in the reason —
|
||||
the `/hosts` "re-browse" chip. Advisory only (drivers.md §Change Detection): nothing is re-materialised. The first
|
||||
session records the baseline; a deploy respawn forgets it (the next session is a new baseline). No extra traffic.
|
||||
- **Health:** `Degraded` only while a control's session is down (connect failing / lost), with
|
||||
`LastSuccessfulRead` frozen — the conjunction the #527 comms-loss watchdog needs. Per-tag refusals, denials and
|
||||
decode errors are quality, not health (else the watchdog would reconnect-loop a control that merely denies one
|
||||
@@ -202,7 +280,13 @@ session to the first device: INSPECT login + `R_VR`. A bare TCP listener does no
|
||||
any non-allowlisted telegram. The Java fixtures' captured iTNC 530 replies (`Fixtures/*.properties`) are replayed
|
||||
as golden vectors (inspect-only telemetry on two controls; DATA boundary replies on three).
|
||||
- `Runtime.Tests/Drivers/HeidenhainDriverEndToEndTests` — the real driver inside `DriverInstanceActor`.
|
||||
- `Configuration.Tests/DraftValidatorHeidenhainTests`, `AdminUI.Tests/Uns/HeidenhainAuthoringTests` + the fleet
|
||||
- `HeidenhainAlarmTests` (#831) — selector grammar, pairing, transition rules, and against the simulator: the captured
|
||||
iTNC 530 alarm record raising/clearing conditions, local-only ack (zero bytes sent), quality-only comms-loss/refusal,
|
||||
handler-detached recording, identity-change rediscovery; every case asserts the wire log stays inside the read set.
|
||||
- `Runtime.Tests/Drivers/HeidenhainNativeAlarmEndToEndTests` — driver → simulator → real `DriverHostActor` condition.
|
||||
- `Configuration.Tests/DraftValidatorHeidenhainTests`, `AdminUI.Tests/Uns/HeidenhainAuthoringTests`,
|
||||
`AdminUI.Tests/Uns/HeidenhainAuthoringUxTests` (#830 CSV preview ⇔ commit parity, data-type lock, single
|
||||
credential notice) + the fleet
|
||||
parity suites.
|
||||
- **LiveIntegration** (`--filter Category=LiveIntegration`, skipped unless `HEIDENHAIN_LSV2_HOST` is set; optional
|
||||
`HEIDENHAIN_LSV2_PORT`, `OTOPCUA_HEIDENHAIN_INSPECT_PASSWORD`): read-only INSPECT identity/selector/layout survey and a
|
||||
@@ -223,5 +307,5 @@ No real control was available for this port. Still open:
|
||||
|
||||
Writes of any kind, file upload/download, remote input/keyboard/motion, parameter edits, PLCDEBUG/MONITOR/FILE
|
||||
roles, scope setup, arbitrary requests, buffer-size negotiation, vendor SDK, serial transport, built-in SSH,
|
||||
PLC-wide symbol discovery / memory scanning, OEE mapping, and native alarms as Part 9 conditions (alarms are
|
||||
published as typed arrays).
|
||||
PLC-wide symbol discovery / memory scanning, OEE mapping, and any controller-side alarm acknowledgement (native alarm
|
||||
conditions are acknowledged server-side only — see [Alarm conditions](#alarm-conditions-alarm-gitea-831)).
|
||||
|
||||
@@ -81,6 +81,13 @@ for every field (security policy/mode, auth type, session timeout, keep-alive,
|
||||
browse root, node/depth caps). `ReconnectPeriod` was **deleted** (#676 — unused since #670 removed the SDK reconnect
|
||||
handler, and the AdminUI no longer shows it); stored configs that still carry `reconnectPeriod` keep parsing in the
|
||||
factory, the Test-Connect probe and the browse picker (unknown keys are skipped), and the form drops it on the next save.
|
||||
**Credentials (#815).** `Password` / `UserCertificatePassword` are a literal, `secret:opcuaclient/<name>` (the node's
|
||||
secret store) or `env:OTOPCUA_OPCUACLIENT_<NAME>`. They are resolved on the node and sent to the configured endpoint,
|
||||
so any other `secret:`/`env:` reference (and `file:`) is refused at save, deploy (`CredentialReferenceOutOfScope`), Test
|
||||
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".
|
||||
|
||||
`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).
|
||||
|
||||
@@ -108,7 +115,14 @@ The rule, for `opc.tcp` (and any scheme, as long as advertised and configured sc
|
||||
a real rewrite keeps the advertised path's percent-escaping (`AbsoluteUri`, #812);
|
||||
- a **different scheme** (an `https` endpoint next to an `opc.tcp` one) is a different transport and is left alone;
|
||||
- an unusable advertised URL (null / blank / unparseable) falls back to the configured one in the driver and the
|
||||
browser; the Client CLI/UI instead reports it (it validates before calling the rewriter).
|
||||
browser; the Client CLI/UI instead reports it (it validates before calling the rewriter);
|
||||
- an **IPv6 zone index** on the configured host (`opc.tcp://[fe80::1%eth0]:4840`) is **kept, verbatim** (#819).
|
||||
.NET's `Uri` parses the zone but drops it from `Host`/`Authority`/`AbsoluteUri`/`ToString()` — only
|
||||
`DnsSafeHost`/`IdnHost` carry it — so the rewriter splices it back into the string. The SDK dials
|
||||
`new Uri(EndpointUrl).IdnHost` (`TcpByteTransport` → `DnsEndPoint`), which keeps it, so a link-local endpoint now
|
||||
routes; before #819 the session dialled a zone-less `fe80::` address. The zone text is not normalised: write the
|
||||
form your OS resolves (`%eth0` / `%4`). .NET does **not** decode RFC 6874's `%25eth0` (its `DnsSafeHost` is
|
||||
`fe80::1%25eth0`), so that form is passed through as written — GetEndpoints and the session see the same string.
|
||||
|
||||
**What the rewrite does NOT touch.** It only chooses the network address. The **security policy and mode** are
|
||||
still selected from the server's advertisement exactly as before — the driver and browser filter on the configured
|
||||
@@ -118,7 +132,72 @@ user-token policies** are the advertised ones. **Certificate validation is uncha
|
||||
validates the certificate of the server actually reached, against the same trust store (the driver's PKI, the
|
||||
browse picker's separate `adminui-browse-pki`, the CLI's own) with the same `AutoAcceptCertificates` semantics. The
|
||||
NAT tests below pin that a secure browse through the NAT is refused on an untrusted certificate and succeeds once it
|
||||
is trusted.
|
||||
is trusted. The optional **host-name** check (#816, next section) is the one place the rewrite matters to validation:
|
||||
it runs against the rewritten URL, i.e. the **configured** host.
|
||||
|
||||
### Server certificate host name (#816)
|
||||
|
||||
**Finding (SDK 2.0.1).** The SDK only checks that the server certificate names the host you connected to when the
|
||||
session is created with `checkDomain: true`. All three surfaces — the driver (`OpenSessionOnEndpointAsync`), the
|
||||
AdminUI browser (`OpcUaClientDriverBrowser.OpenAsync`) and Client.Shared (`DefaultSessionFactory`) — called the
|
||||
8-argument `DefaultSessionFactory.CreateAsync(config, endpoint, updateBeforeConnect, sessionName, …)`, which
|
||||
forwards `checkDomain: false`. So **no host-name check ever ran**; trust was the trusted-peer / issuer store alone.
|
||||
That is why, in #813, a trusted NAT certificate for `otopcua-opc-plc-nat-private.invalid` browsed fine over an IP.
|
||||
|
||||
Where the check lives when enabled — **two** places in SDK 2.0.1, both calling
|
||||
`CertificateValidationExtensions.ValidateDomains` → `CertificateValidationCore.ValidateDomains` →
|
||||
`CertificateValidationHelpers.FindDomain`:
|
||||
|
||||
1. `DefaultSessionFactory.CreateChannelAsync` — before the channel opens, against the certificate in the
|
||||
**GetEndpoints reply** (`endpoint.Description.ServerCertificate`), whenever that reply carries one and **before any
|
||||
security-mode test**. opc-plc sends its certificate on its `None` endpoint too, so `checkDomain: true` refused a
|
||||
`None` connect (found in review, reproduced against `:50000`).
|
||||
2. `Session.OpenAsync` — after `CertificateManager.ValidateAsync` accepts the chain the server returned in
|
||||
CreateSession (only when the channel or the user-token policy needs the server certificate).
|
||||
|
||||
`FindDomain` compares `ConfiguredEndpoint.EndpointUrl.IdnHost` with the names `X509Utils.GetDomainsFromCertificate`
|
||||
returns (DNS / IP SANs, and the subject's `DC=` parts); IP literals are normalised, and a `localhost` / `127.0.0.1` /
|
||||
`::1` URL is compared as the machine's own host name + FQDN. A miss is `BadCertificateHostNameInvalid` ("The domain
|
||||
'…' is not listed in the server certificate."), passed to the certificate manager's `AcceptError` hook first.
|
||||
Consequences:
|
||||
|
||||
- **It checks the CONFIGURED host.** `ConfiguredEndpoint.EndpointUrl` is the URL `OpcUaEndpointSelection` /
|
||||
`EndpointSelector` rewrote, so the advertised host the server named itself never takes part.
|
||||
- **Sign / SignAndEncrypt endpoints only — enforced here, not by the SDK.** Because of site 1, all three call sites
|
||||
pass `checkDomain` only when the selected endpoint's `SecurityMode != None` (`OpcUaEndpointSelection.CheckDomainFor`
|
||||
for the driver and the browser, the same expression in Client.Shared's `ConnectToEndpointAsync`; both cover the
|
||||
failover sweep, which goes through the same per-endpoint open). A host-name check on an unauthenticated channel
|
||||
proves nothing.
|
||||
- **It is a loose match.** For a DNS host the SDK also accepts a match on the **first label alone**:
|
||||
`plc1.site-a.corp` passes a certificate whose only SAN is `PLC1` (case-insensitive), and so would
|
||||
`plc1.site-b.corp`. There is no wildcard support (`*.site-a.corp` matches nothing), and the subject's `DC=`
|
||||
components count as names.
|
||||
- **A zone-qualified IPv6 host never passes.** `FindDomain` compares the host *with* its zone (`fe80::1%eth0`; macOS
|
||||
normalises `%en0` to `%14`) against the certificate's zone-less IP SANs, so a link-local endpoint (#819) needs
|
||||
`validateServerHostName: false`. The repo does not fork the SDK check to strip the zone.
|
||||
- **`autoAcceptCertificates` accepts a mismatch too** (the driver's auto-accept `AcceptError` handler returns `true`
|
||||
for everything but revocation). The Client CLI always auto-accepts.
|
||||
- Test Connect (`OpcUaClientDriverProbe`) only calls GetEndpoints on an unsecured discovery channel — no session, so no
|
||||
certificate or host-name check.
|
||||
|
||||
**Policy: `certificateValidation.validateServerHostName`** (driver JSON; AdminUI driver form "Server host-name check";
|
||||
the browser reads the same JSON):
|
||||
|
||||
| Value | Meaning |
|
||||
|---|---|
|
||||
| absent / `null` (**default**) | `OpcUaCertificateValidationOptions.DefaultValidateServerHostName` = **off** — exactly the pre-#816 behaviour, so no existing deployment changes on upgrade. The AdminUI form keeps it absent ("Default (off)") rather than writing a concrete `false`. |
|
||||
| `true` | Validate: the certificate must list the configured endpoint host. The driver's connect failure then appends the remedy (fix the certificate, connect by a name it lists, or opt out). |
|
||||
| `false` | Explicit opt-out — the NAT / container port-publish / connect-by-an-IP-the-cert-omits case. |
|
||||
|
||||
When to turn it on: it earns its keep when trust comes from a **CA** (a trusted issuer vouches for every certificate
|
||||
it signed, so only the host check ties the certificate to *this* server) — within the limits above: a
|
||||
first-label-only match means a certificate issued as `PLC1` for one site is accepted for `plc1` at every site, so give
|
||||
certificates fully-qualified, site-unique names. With the server's own self-signed
|
||||
certificate pinned in the trusted-peer store it adds little — the pin already identifies the server. Client
|
||||
CLI: `--validate-host-name` (`ConnectionSettings.ValidateServerHostName`, default `false`). Pinned by
|
||||
`ServerHostNameValidationTests` (driver vs. the plain opc-plc, whose certificate names only its container id) and
|
||||
`NatPublishedEndpointBrowseTests` (browser vs. the NAT opc-plc): unset/`false` connect, `true` is refused naming the
|
||||
configured host.
|
||||
|
||||
**Running the NAT tests.** `NatPublishedEndpointBrowseTests`
|
||||
(`tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Browser.IntegrationTests`, `Fixture=opc-plc-nat`) run against
|
||||
@@ -133,13 +212,20 @@ OPCUA_NAT_ENDPOINT=opc.tcp://10.100.0.35:50010 dotnet test \
|
||||
tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Browser.IntegrationTests --filter Fixture=opc-plc-nat
|
||||
```
|
||||
|
||||
The secure case asserts a certificate **refusal** by default. To make it positive, trust the fixture's server
|
||||
certificate in the browse PKI and set `OPCUA_NAT_SERVER_CERT_TRUSTED=1` — the certificate is regenerated whenever
|
||||
the container is recreated, so fetch the current one:
|
||||
`ssh dohertj2@10.100.0.35 'docker exec otopcua-opc-plc-nat sh -c "cat /app/pki/own/certs/*.der"' > "<LocalAppData>/OtOpcUa/adminui-browse-pki/trusted/certs/opc-plc-nat.der"`
|
||||
(`~/Library/Application Support/...` on macOS, `~/.local/share/...` on Linux), and delete it again afterwards. CI
|
||||
(`v2-integration.yml`) starts its own throwaway NAT copy (`scripts/ci/integration-fixtures.sh`); `v2-e2e.yml` points at
|
||||
the shared one. Neither trusts the certificate, so CI runs the refusal form.
|
||||
Every secure browse there runs on a **throwaway browse PKI** (an internal PKI-root seam on the browser), never your
|
||||
`adminui-browse-pki`. The refusal case trusts nothing and always runs. The positive case (unset / `false` host check)
|
||||
and the host-name refusal (`true`) trust the fixture's **public** certificate (#818), from:
|
||||
|
||||
1. `OPCUA_NAT_SERVER_CERT` — a DER or PEM file; must be the certificate the server presents, or the test **fails**; else
|
||||
2. the committed `tests/.../Driver.OpcUaClient.IntegrationTests/Docker/nat/opc-plc-nat-server.der` — the shared-host
|
||||
stack's certificate, stable because its PKI lives on the `opc-plc-nat-pki` volume. If it is not the certificate
|
||||
the server presents (another NAT fixture, or the stack's certificate was rolled) these tests **skip**.
|
||||
|
||||
The private key never leaves the volume. The committed certificate expires **2027-11-10**; to roll it, see the comment
|
||||
at the top of `Docker/nat/docker-compose.yml`. CI (`v2-integration.yml`) starts its own throwaway NAT copy
|
||||
(`scripts/ci/integration-fixtures.sh`), copies that container's public certificate out with `docker exec` and exports
|
||||
`OPCUA_NAT_SERVER_CERT`, so it runs the positive cases too; `v2-e2e.yml` points at the shared stack and uses the
|
||||
committed certificate.
|
||||
|
||||
### Session lifetime
|
||||
|
||||
@@ -379,6 +465,7 @@ also refuses them explicitly — defence in depth (#277), not a behaviour change
|
||||
|---|---|---|
|
||||
| `rejectUnknownRevocationStatus` | `false` | Reject a server certificate whose revocation status cannot be determined (no CRL for its issuer, or a stale one). Leave `false` for brownfield sites without CRL infrastructure. **Only effective with `autoAcceptCertificates` off** — the auto-accept handler accepts every suppressible error, including revocation-unknown. |
|
||||
| `issuerStorePath` | `null` (= `%LocalAppData%/OtOpcUa/pki/issuers`) | Directory used as the trusted-issuer store. The SDK reads issuer CRLs (`*.crl`) from its `crl/` sub-folder, so this is how an operator points the driver at a managed CRL set. |
|
||||
| `validateServerHostName` | `null` (= off) | #816: require the server certificate to name the **configured** endpoint host (`BadCertificateHostNameInvalid` otherwise). Sign / SignAndEncrypt endpoints only (never passed for `None`); accepted anyway under `autoAcceptCertificates`; loose (first-label) match; never matches a zone-qualified IPv6 host. `false` = explicit NAT / link-local opt-out. See "Server certificate host name" above. |
|
||||
|
||||
### Subscription tuning (#273)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user