feat(opcuaclient): opt-in server-certificate host-name check; NAT fixture keeps its PKI (#816, #818)

#816 finding: the SDK checks that the server certificate names the host only
when a session is created with checkDomain:true. The driver, the AdminUI
browser and Client.Shared all called the 8-argument
DefaultSessionFactory.CreateAsync, which forwards checkDomain:false — so no
host-name check ever ran (why a trusted NAT cert for *.invalid browsed fine
over an IP in #813). When enabled the SDK (Session.OpenAsync ->
ValidateDomains -> FindDomain) compares ConfiguredEndpoint.EndpointUrl.IdnHost
— the CONFIGURED host, because OpcUaEndpointSelection/EndpointSelector
rewrote the advertised one — against the cert's DNS/IP SANs; secured
sessions only, and the auto-accept handler accepts a mismatch.

Policy: certificateValidation.validateServerHostName, tri-state. Unset =
OpcUaCertificateValidationOptions.DefaultValidateServerHostName = false, the
pre-#816 behaviour, so nothing changes on upgrade; true = validate the
configured host; false = explicit NAT/port-publish opt-out. Threaded into the
driver, the AdminUI browser (same JSON) and the AdminUI form (a select that
keeps "unset" unset), Client.Shared ConnectionSettings.ValidateServerHostName
and the CLI --validate-host-name. A driver refusal names the opt-out.

#818: the NAT fixture's /app/pki is on the opc-plc-nat-pki volume (verified:
same thumbprint across --force-recreate), its PUBLIC cert is committed as
Docker/nat/opc-plc-nat-server.der, and NatPublishedEndpointBrowseTests run
every secure browse on a throwaway PKI (internal browser seam): refusal with
nothing trusted, positive with the cert trusted (unset/false host check), and
a BadCertificateHostNameInvalid refusal with the check on. The trusted cert is
OPCUA_NAT_SERVER_CERT or the committed one (skip on thumbprint mismatch);
OPCUA_NAT_SERVER_CERT_TRUSTED is retired. CI exports its throwaway NAT
container's public cert. ServerHostNameValidationTests pin the driver against
the plain opc-plc. MIN_EXECUTED not raised (needs a hosted run): +6 in
v2-integration (440 -> 446), documented in scripts/ci/README.md.
This commit is contained in:
Joseph Doherty
2026-11-11 01:33:00 -05:00
parent bde6cce2fc
commit ae91e6b7f7
30 changed files with 648 additions and 59 deletions
@@ -1,5 +1,6 @@
using System.Net;
using System.Net.Sockets;
using System.Security.Cryptography.X509Certificates;
using Opc.Ua;
using Opc.Ua.Client;
using Shouldly;
@@ -20,27 +21,54 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Browser.IntegrationTests;
/// # or locally / in CI (scripts/ci/integration-fixtures.sh starts the same shape as otopcua-ci-opcplc-nat):
/// docker run -d --rm --name otopcua-806-nat --hostname otopcua-806-nat-parity -p 32781:50000 \
/// mcr.microsoft.com/iotedge/opc-plc:2.14.10 --pn=50000 --ph=otopcua-806-nat-parity.invalid --autoaccept --ut
/// OPCUA_NAT_ENDPOINT=opc.tcp://127.0.0.1:32781 dotnet test --filter Fixture=opc-plc-nat
/// docker exec otopcua-806-nat bash -c 'cat /app/pki/own/certs/*.der' > /tmp/nat.der # public cert only
/// OPCUA_NAT_ENDPOINT=opc.tcp://127.0.0.1:32781 OPCUA_NAT_SERVER_CERT=/tmp/nat.der dotnet test --filter Fixture=opc-plc-nat
/// </code>
/// Skipped unless <c>OPCUA_NAT_ENDPOINT</c> is set and accepts TCP. Every test first proves the premise (the
/// advertised URL is NOT the configured host:port, and its host does not resolve here), so a fixture that
/// advertises a reachable address cannot make these pass vacuously. Before the fix the positive cases failed with
/// <c>SocketException: nodename nor servname provided, or not known</c>.
/// <para><b>Secure cases (#813/#816/#818).</b> Every browse here runs on a THROWAWAY browse PKI (the browser's
/// internal PKI-root seam), never the operator's <c>adminui-browse-pki</c>. The refusal case trusts nothing. The
/// positive and host-name cases trust the fixture's PUBLIC certificate — from <c>OPCUA_NAT_SERVER_CERT</c> (a DER or
/// PEM file; what CI exports after copying it out of its throwaway container) or else the committed
/// <c>Docker/nat/opc-plc-nat-server.der</c> (the shared-host stack's certificate, stable since #818 put its PKI on a
/// volume) — and SKIP when the committed certificate is not the one the server presents, so they can never pass
/// against a different server.</para>
/// </summary>
[Trait("Category", "Integration"), Trait("Fixture", "opc-plc-nat")]
public sealed class NatPublishedEndpointBrowseTests
public sealed class NatPublishedEndpointBrowseTests : IDisposable
{
private const string EnvVar = "OPCUA_NAT_ENDPOINT";
private const string CertEnvVar = "OPCUA_NAT_SERVER_CERT";
private const string CommittedCertFile = "opc-plc-nat-server.der";
private readonly string _pkiRoot = Path.Combine(Path.GetTempPath(), "otopcua-nat-pki-" + Guid.NewGuid().ToString("N"));
private static string? Endpoint => Environment.GetEnvironmentVariable(EnvVar) is { Length: > 0 } e ? e : null;
private static string Json(string endpoint, string policy = "None", string mode = "None") => $$"""
{
"EndpointUrl":"{{endpoint}}",
"SecurityPolicy":"{{policy}}","SecurityMode":"{{mode}}","AuthType":"Anonymous",
"SessionTimeout":"00:01:00","Timeout":"00:00:10","PerEndpointConnectTimeout":"00:00:10"
}
""";
/// <inheritdoc />
public void Dispose()
{
try { Directory.Delete(_pkiRoot, recursive: true); } catch { /* best-effort temp cleanup */ }
}
/// <summary>A browser on this test's throwaway PKI.</summary>
private OpcUaClientDriverBrowser Browser() => new(_pkiRoot);
private static string Json(string endpoint, string policy = "None", string mode = "None", bool? validateHostName = null)
{
var certValidation = validateHostName is { } v
? $$""","CertificateValidation":{"ValidateServerHostName":{{(v ? "true" : "false")}}}"""
: "";
return $$"""
{
"EndpointUrl":"{{endpoint}}",
"SecurityPolicy":"{{policy}}","SecurityMode":"{{mode}}","AuthType":"Anonymous",
"SessionTimeout":"00:01:00","Timeout":"00:00:10","PerEndpointConnectTimeout":"00:00:10"{{certValidation}}
}
""";
}
private static string RequireFixture()
{
@@ -60,8 +88,11 @@ public sealed class NatPublishedEndpointBrowseTests
return endpoint;
}
/// <summary>The premise: the server advertises a host:port other than the configured one, and that host is unresolvable.</summary>
private static async Task AssertAdvertisesUnreachableAddressAsync(string endpoint, CancellationToken ct)
/// <summary>
/// The premise: the server advertises a host:port other than the configured one, and that host is unresolvable.
/// Returns the DER certificate the server presents on its secure endpoint.
/// </summary>
private static async Task<byte[]> AssertAdvertisesUnreachableAddressAsync(string endpoint, CancellationToken ct)
{
var appConfig = new ApplicationConfiguration(DefaultTelemetry.Create(_ => { }))
{
@@ -84,6 +115,61 @@ public sealed class NatPublishedEndpointBrowseTests
await Should.ThrowAsync<SocketException>(() => Dns.GetHostAddressesAsync(advertised.Host, ct),
$"advertised host '{advertised.Host}' must be unresolvable from here, or this test proves nothing");
}
return endpoints.First(e => e.SecurityPolicyUri == SecurityPolicies.Basic256Sha256).ServerCertificate.ToArray();
}
/// <summary>
/// Trust the fixture's public certificate in this test's throwaway PKI, or SKIP when no certificate for THIS
/// server is available (see the class remarks). An explicit <c>OPCUA_NAT_SERVER_CERT</c> that does not match
/// FAILS: it names the certificate the operator meant, so a mismatch is a fixture problem worth seeing.
/// </summary>
/// <param name="presentedDer">The certificate the server presents (from its GetEndpoints answer).</param>
private void TrustFixtureCertificate(byte[] presentedDer)
{
using var presented = X509CertificateLoader.LoadCertificate(presentedDer);
X509Certificate2 trusted;
if (Environment.GetEnvironmentVariable(CertEnvVar) is { Length: > 0 } path)
{
trusted = LoadPublicCertificate(path);
trusted.Thumbprint.ShouldBe(presented.Thumbprint,
$"{CertEnvVar}={path} is not the certificate the NAT fixture presents");
}
else
{
var committed = Path.Combine(AppContext.BaseDirectory, CommittedCertFile);
if (!File.Exists(committed))
Assert.Skip($"{CommittedCertFile} is not deployed next to the tests and {CertEnvVar} is unset.");
trusted = LoadPublicCertificate(committed);
if (trusted.Thumbprint != presented.Thumbprint)
Assert.Skip($"the committed {CommittedCertFile} ({trusted.Thumbprint}) is not this fixture's certificate " +
$"({presented.Thumbprint}, expires {presented.NotAfter:yyyy-MM-dd}); set {CertEnvVar} or " +
"refresh the committed copy (see Docker/nat/docker-compose.yml).");
}
using (trusted)
{
trusted.HasPrivateKey.ShouldBeFalse("only a PUBLIC certificate is ever trusted from a file");
var certs = Path.Combine(_pkiRoot, "trusted", "certs");
Directory.CreateDirectory(certs);
File.WriteAllBytes(Path.Combine(certs, "opc-plc-nat.der"), trusted.RawData);
}
}
private static X509Certificate2 LoadPublicCertificate(string path)
{
var bytes = File.ReadAllBytes(path);
var text = System.Text.Encoding.ASCII.GetString(bytes);
return text.Contains("-----BEGIN CERTIFICATE-----", StringComparison.Ordinal)
? X509Certificate2.CreateFromPem(text)
: X509CertificateLoader.LoadCertificate(bytes);
}
private static StatusCode? FindStatus(Exception? ex)
{
for (; ex is not null; ex = ex.InnerException)
if (ex is ServiceResultException sre) return sre.StatusCode;
return null;
}
[Fact]
@@ -93,7 +179,7 @@ public sealed class NatPublishedEndpointBrowseTests
var ct = TestContext.Current.CancellationToken;
await AssertAdvertisesUnreachableAddressAsync(endpoint, ct);
await using var session = await new OpcUaClientDriverBrowser().OpenAsync(Json(endpoint), ct);
await using var session = await Browser().OpenAsync(Json(endpoint), ct);
var roots = await session.RootAsync(ct);
roots.Count.ShouldBeGreaterThan(0);
@@ -111,7 +197,7 @@ public sealed class NatPublishedEndpointBrowseTests
var ct = TestContext.Current.CancellationToken;
// A closed loopback port: the rewrite must not invent a reachable address; the open fails promptly.
var sw = System.Diagnostics.Stopwatch.StartNew();
await Should.ThrowAsync<Exception>(() => new OpcUaClientDriverBrowser().OpenAsync(Json("opc.tcp://127.0.0.1:1"), ct));
await Should.ThrowAsync<Exception>(() => Browser().OpenAsync(Json("opc.tcp://127.0.0.1:1"), ct));
sw.Elapsed.ShouldBeLessThan(TimeSpan.FromSeconds(30));
}
@@ -122,29 +208,59 @@ public sealed class NatPublishedEndpointBrowseTests
var ct = TestContext.Current.CancellationToken;
await AssertAdvertisesUnreachableAddressAsync(endpoint, ct);
// Basic256Sha256/SignAndEncrypt through the published port. The browse PKI never auto-accepts, so unless the
// operator trusted this fixture's certificate in the browse PKI (then set OPCUA_NAT_SERVER_CERT_TRUSTED=1) the
// open must be refused on the certificate — which proves the session reached the SERVER (no DNS failure on the
// advertised host) and that the rewrite did not relax trust.
var trusted = Environment.GetEnvironmentVariable("OPCUA_NAT_SERVER_CERT_TRUSTED") == "1";
var json = Json(endpoint, "Basic256Sha256", "SignAndEncrypt");
if (trusted)
{
await using var session = await new OpcUaClientDriverBrowser().OpenAsync(json, ct);
(await session.RootAsync(ct)).Count.ShouldBeGreaterThan(0);
return;
}
// Basic256Sha256/SignAndEncrypt through the published port, on a browse PKI that trusts NOTHING (the browse
// never auto-accepts): the open must be refused on the certificate — which proves the session reached the
// SERVER (no DNS failure on the advertised host) and that the rewrite did not relax trust.
var ex = await Should.ThrowAsync<Exception>(async () =>
{
await using var session = await new OpcUaClientDriverBrowser().OpenAsync(json, ct);
await using var session = await Browser().OpenAsync(Json(endpoint, "Basic256Sha256", "SignAndEncrypt"), ct);
});
TestContext.Current.TestOutputHelper?.WriteLine($"secure open refused: {ex.GetType().Name}: {ex.Message}");
ex.ShouldNotBeOfType<SocketException>($"must not fail on DNS for the advertised host: {ex}");
var sre = ex as ServiceResultException ?? ex.InnerException as ServiceResultException;
sre.ShouldNotBeNull($"expected a certificate refusal, got {ex.GetType().Name}: {ex.Message}");
sre.StatusCode.ShouldBeOneOf(
var status = FindStatus(ex);
status.ShouldNotBeNull($"expected a certificate refusal, got {ex.GetType().Name}: {ex.Message}");
status.Value.ShouldBeOneOf(
StatusCodes.BadCertificateUntrusted, StatusCodes.BadSecurityChecksFailed,
StatusCodes.BadCertificateChainIncomplete);
}
/// <summary>
/// #818 — the positive secure case, runnable in CI. #816 — with the host-name check unset (the default) or
/// explicitly off, a trusted certificate is accepted although it names <c>*-nat-private.invalid</c> and the
/// browse dialled the published address: the NAT opt-out.
/// </summary>
[Theory]
[InlineData(null)]
[InlineData(false)]
public async Task Secure_browse_with_the_fixture_certificate_trusted_succeeds_without_a_host_name_check(bool? validate)
{
var endpoint = RequireFixture();
var ct = TestContext.Current.CancellationToken;
TrustFixtureCertificate(await AssertAdvertisesUnreachableAddressAsync(endpoint, ct));
await using var session = await Browser().OpenAsync(
Json(endpoint, "Basic256Sha256", "SignAndEncrypt", validate), ct);
(await session.RootAsync(ct)).Count.ShouldBeGreaterThan(0);
}
/// <summary>
/// #816 — with the host-name check on, the SAME trusted certificate is refused, and the host checked is the one
/// the operator configured (the published address), not the server-advertised private name the certificate lists.
/// </summary>
[Fact]
public async Task Host_name_validation_checks_the_configured_host_and_refuses_the_NAT_certificate()
{
var endpoint = RequireFixture();
var ct = TestContext.Current.CancellationToken;
TrustFixtureCertificate(await AssertAdvertisesUnreachableAddressAsync(endpoint, ct));
var ex = await Should.ThrowAsync<Exception>(async () =>
{
await using var session = await Browser().OpenAsync(
Json(endpoint, "Basic256Sha256", "SignAndEncrypt", validateHostName: true), ct);
});
TestContext.Current.TestOutputHelper?.WriteLine($"secure open refused: {ex.GetType().Name}: {ex.Message}");
FindStatus(ex).ShouldBe(StatusCodes.BadCertificateHostNameInvalid, $"expected a host-name refusal, got {ex}");
ex.ToString().ShouldContain($"'{new Uri(endpoint).IdnHost}'");
}
}
@@ -24,4 +24,11 @@
<ProjectReference Include="..\..\..\src\Core\ZB.MOM.WW.OtOpcUa.Commons\ZB.MOM.WW.OtOpcUa.Commons.csproj" />
</ItemGroup>
<ItemGroup>
<!-- #818: the shared-host NAT fixture's PUBLIC server certificate (its PKI is on a persistent volume), trusted by
NatPublishedEndpointBrowseTests in a throwaway browse PKI. Never a private key. -->
<None Include="..\ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests\Docker\nat\opc-plc-nat-server.der"
Link="opc-plc-nat-server.der" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
</Project>