Feature: add auto secure scheme support in binding-opcua (#1425)

* feat(binding-opcua): implement Auto Security Scheme for OPC UA #1401

* chore(opcua-binding): fix file naming inconsistency #1423

Author: erossignon

packages/binding-opcua/src/find-most-secure-channel.ts

@@ -0,0 +1,115 @@
+/********************************************************************************
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the W3C Software Notice and
+ * Document License (2015-05-13) which is available at
+ * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
+ ********************************************************************************/
+
+import { MessageSecurityMode, OPCUAClient, SecurityPolicy } from "node-opcua-client";
+
+function getPriority(securityPolicy: string | null, securityMode: MessageSecurityMode): number {
+    const encryptWeight = securityMode === MessageSecurityMode.SignAndEncrypt ? 100 : 0;
+
+    switch (securityPolicy) {
+        case null:
+        case "":
+        case "http://opcfoundation.org/UA/SecurityPolicy#None":
+            return 0;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Basic128":
+            return 1 + encryptWeight;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Basic192":
+            return 2 + encryptWeight;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Basic192Rsa15":
+            return 3 + encryptWeight;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Basic256":
+            return 4 + encryptWeight;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Basic256Rsa15":
+            return 5 + encryptWeight;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Basic256Sha256":
+            return 6 + encryptWeight;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Aes128_Sha256_RsaOaep":
+            return 7 + encryptWeight;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Aes256_Sha256_RsaPss":
+            return 8 + encryptWeight;
+        default:
+            return -100;
+    }
+}
+
+function coerceSecurityPolicyUri(securityPolicyUri: string | null): SecurityPolicy {
+    switch (securityPolicyUri) {
+        case null:
+        case "":
+        case "http://opcfoundation.org/UA/SecurityPolicy#None":
+            return SecurityPolicy.None;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Basic128":
+            return SecurityPolicy.Basic128;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Basic192":
+            return SecurityPolicy.Basic192;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Basic192Rsa15":
+            return SecurityPolicy.Basic192Rsa15;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Basic256":
+            return SecurityPolicy.Basic256;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Basic256Rsa15":
+            return SecurityPolicy.Basic256Rsa15;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Basic256Sha256":
+            return SecurityPolicy.Basic256Sha256;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Aes128_Sha256_RsaOaep":
+            return SecurityPolicy.Aes128_Sha256_RsaOaep;
+        case "http://opcfoundation.org/UA/SecurityPolicy#Aes256_Sha256_RsaPss":
+            return SecurityPolicy.Aes256_Sha256_RsaPss;
+        default:
+            return SecurityPolicy.Invalid;
+    }
+}
+
+interface EndpointDescriptionMini {
+    endpointUrl: string | null;
+    securityMode: MessageSecurityMode;
+    securityPolicyUri: string | null;
+}
+
+const defaultEndpoint: EndpointDescriptionMini = {
+    endpointUrl: null,
+    securityMode: MessageSecurityMode.None,
+    securityPolicyUri: SecurityPolicy.None,
+};
+
+async function findMostSecureChannelInternal(client: OPCUAClient): Promise<EndpointDescriptionMini> {
+    let endpoints = await client.getEndpoints();
+
+    // sort in descending order of security level
+    endpoints = endpoints.sort((a, b) => {
+        const securityLevelA = getPriority(a.securityPolicyUri, a.securityMode);
+        const securityLevelB = getPriority(b.securityPolicyUri, b.securityMode);
+        return securityLevelB - securityLevelA;
+    });
+    return endpoints.length > 0 ? endpoints[0] : defaultEndpoint;
+}
+
+export async function findMostSecureChannel(
+    endpointUrl: string
+): Promise<{ messageSecurityMode: MessageSecurityMode; securityPolicy: SecurityPolicy }> {
+    const client = OPCUAClient.create({
+        endpointMustExist: false,
+        securityMode: MessageSecurityMode.None,
+        securityPolicy: SecurityPolicy.None,
+    });
+    try {
+        await client.connect(endpointUrl);
+        const endpoint = await findMostSecureChannelInternal(client);
+        const messageSecurityMode = endpoint.securityMode;
+        const securityPolicy = coerceSecurityPolicyUri(endpoint.securityPolicyUri);
+        return { messageSecurityMode, securityPolicy };
+    } finally {
+        await client.disconnect();
+    }
+}

packages/binding-opcua/src/index.ts

@@ -16,5 +16,5 @@
 export * from "./factory";
 export * from "./codec";
 export * from "./opcua-protocol-client";
-export * from "./security_scheme";
+export * from "./security-scheme";
 // no protocol_client here => get access from factor

packages/binding-opcua/src/opcua-protocol-client.ts

@@ -63,9 +63,10 @@ import { Argument, BrowseDescription, BrowseResult, MessageSecurityMode, UserTok
 import { isGoodish2, ReferenceTypeIds } from "node-opcua";
 
 import { schemaDataValue } from "./codec";
-import { OPCUACAuthenticationScheme, OPCUAChannelSecurityScheme } from "./security_scheme";
+import { OPCUACAuthenticationScheme, OPCUAChannelSecurityScheme } from "./security-scheme";
 import { CertificateManagerSingleton } from "./certificate-manager-singleton";
 import { resolveChannelSecurity, resolvedUserIdentity } from "./opcua-security-resolver";
+import { findMostSecureChannel } from "./find-most-secure-channel";
 
 const { debug } = createLoggers("binding-opcua", "opcua-protocol-client");
 
@@ -161,6 +162,7 @@ export class OPCUAProtocolClient implements ProtocolClient {
 
     private _securityMode: MessageSecurityMode = MessageSecurityMode.None;
     private _securityPolicy: SecurityPolicy = SecurityPolicy.None;
+    private _useAutoChannel: boolean = false;
     private _userIdentity: UserIdentityInfo = <AnonymousIdentity>{ type: UserTokenType.Anonymous };
 
     private async _withConnection<T>(form: OPCUAForm, next: (connection: OPCUAConnection) => Promise<T>): Promise<T> {
@@ -173,6 +175,14 @@ export class OPCUAProtocolClient implements ProtocolClient {
         let c: OPCUAConnectionEx | undefined = this._connections.get(endpoint);
         if (!c) {
             const clientCertificateManager = await CertificateManagerSingleton.getCertificateManager();
+
+            if (this._useAutoChannel) {
+                if (this._securityMode === MessageSecurityMode.Invalid) {
+                    const { messageSecurityMode, securityPolicy } = await findMostSecureChannel(endpoint);
+                    this._securityMode = messageSecurityMode;
+                    this._securityPolicy = securityPolicy;
+                }
+            }
             const client = OPCUAClient.create({
                 endpointMustExist: false,
                 connectionStrategy: {
@@ -517,6 +527,7 @@ export class OPCUAProtocolClient implements ProtocolClient {
         const { messageSecurityMode, securityPolicy } = resolveChannelSecurity(security);
         this._securityMode = messageSecurityMode;
         this._securityPolicy = securityPolicy;
+        this._useAutoChannel = false;
         return true;
     }
 
@@ -529,6 +540,20 @@ export class OPCUAProtocolClient implements ProtocolClient {
         for (const securityScheme of securitySchemes) {
             let success = true;
             switch (securityScheme.scheme) {
+                case "auto": {
+                    //
+                    // Security scheme = auto instruct the client to automatically
+                    // determine the most secure channel to use based on server Endpoints.
+                    //
+                    this._useAutoChannel = true;
+                    // Invalid + _useAutoChannel=true indicates that the
+                    // Channel Security Settings need to be resolved at runtime
+                    // based on server Endpoints.
+                    this._securityMode = MessageSecurityMode.Invalid;
+                    this._securityPolicy = SecurityPolicy.None;
+                    success = true;
+                    break;
+                }
                 case "uav:channel-security":
                     success = this.#setChannelSecurity(securityScheme as OPCUAChannelSecurityScheme);
                     break;

packages/binding-opcua/src/opcua-security-resolver.ts

@@ -21,7 +21,7 @@ import {
     UserTokenType,
 } from "node-opcua-client";
 import { convertPEMtoDER } from "node-opcua-crypto";
-import { OPCUACAuthenticationScheme, OPCUAChannelSecurityScheme } from "./security_scheme";
+import { OPCUACAuthenticationScheme, OPCUAChannelSecurityScheme } from "./security-scheme";
 
 export interface OPCUAChannelSecuritySettings {
     securityPolicy: SecurityPolicy;

packages/binding-opcua/src/security_scheme.ts renamed to packages/binding-opcua/src/security-scheme.ts

@@ -126,6 +126,9 @@ const thingDescription: WoT.ThingDescription = {
             scheme: "combo",
             allOf: ["c:sign-encrypt_basic256Sha256"],
         },
+        "c:auto_a:anonymous": {
+            scheme: "auto",
+        },
     },
 
     security: "no_security", // by default,
@@ -230,6 +233,11 @@ function inferExpectedSecurityMode(security: string): WhoAmI {
     } else if (security.match(/c:no_security/)) {
         expected.ChannelSecurityMode = "None";
         expected.ChannelSecurityPolicyUri = "http://opcfoundation.org/UA/SecurityPolicy#None";
+    } else if (security.match(/c:auto/)) {
+        // the most secure that the server supports, by client looking-up at the server endpoints
+        expected.ChannelSecurityMode = "SignAndEncrypt";
+        expected.ChannelSecurityPolicyUri = "http://opcfoundation.org/UA/SecurityPolicy#Aes256_Sha256_RsaPss";
+        return expected;
     }
 
     if (security.match(/basic256Sha256/)) {