Manual for DNC Connectivity over OPC-UA

HumanOS Gateway Installation

1. Install the runtime for Windows x86 as described in Installation Instructions

2. Copy the deployment of the HumanOS IoT Gateway Project to the folder C:\ProgramData\CyberTech\HumanOS.IoT.Gateways for each machine.

3. Register Windows Service for each Gateway instance

4. Generate OPC-UA Server application certificate

Example for Server li-humanosd01

$hostname = hostname

& "C:\Temp\Opc.Ua.CertificateGenerator.exe" -cmd issue 
  -au "urn:cybertech:HumanOS:OpcUaServer" 
  -sn "CN=HumanOS OPC-UA Server/O=UnifiedAutomation/DC=$hostname" 
  -sp ".\ServerCertificates" 
  -dn $hostname 
  -an "HumanOS.OpcUaServer" 
  -st ([datetime]::Now).toFileTime() 
  -ks 2048 
  -lm 600

2. Install the certificate from .\ServerCertificates\private\HumanOS.OpcUaServer.pfx OPC-UA Server (gateway host) in Windows LocalMachine Certificate store in "personal" folder.

3. Install the the certificate from .\ServerCertificates\certs\HumanOS.OpcUaServer.der on the Dnc Client computer in the Windows LocalMachine Certificate store in "enterprise trust" folder

   NOTE

   LocalMachine\Trust correlates to Enterprise Trust folder.

4. Start each gateway as windows service

DNC Client

Installation

The DNC client is installed next to MDM Tool application on each client (workstation or pc).

1. Install .net 6 ASP and CORE Runtime
2. Copy the DNC client to C:\Program Files\CyberTech\HumanOS.DncClient\
3. Open console and run following command to check the functionality

   .\HumanOS.DncClient.exe --help 

Creating Certificates

Understand the Communication Flow between Client and Server

Every application using secure communication with an OPC-UA server needs an application certificate. Since the communication is bidirectional, two certificates are required. Both certificates are utilized for encrypting and decrypting messages.

The client requires a certificate with a public key (file with .der extension) to encrypt messages, while the server needs the corresponding private key from the same certificate (file with .pfx extension) to decrypt the messages. Conversely, in the opposite direction, the server needs the private key from its own certificate to decrypt messages received from the client.

How to Create the Client and ServerAppCertificate

The certificates can be created with Opc.Ua.CertificateGenerator.exe which can ve downloaded from CyberTech Share.

1. Generate application certificate for the server (Replace SERVER_NAME with the name of the Server)

   $hostname=<SERVER_NAME>
   $applicationName = "HumanOS.OpcUaServer"
   
   & "C:\Temp\Opc.Ua.CertificateGenerator.exe" -cmd issue `
   -au "urn:$hostname:HumanOS:OpcUaServer" `
   -sn "CN=$applicationName/O=UnifiedAutomation/DC=$hostname" `
   -sp ".\ServerApplicationCertificates" `
   -dn $hostname `
   -an $applicationName `
   -st ([datetime]::Now).toFileTime() `
   -ks 2048 `
   -lm 600$

2. Install the certificate from .\ServerApplicationCertificates\private\HumanOS.OpcUaServer.pfx on the OPC-UA Server (gateway host) in Windows Certificate store in "personal" folder.

3. Install the certificate from .\ServerApplicationCertificates\certs\HumanOS.OpcUaServer.der locally on the Dnc Client computer in Windows LocalMachine Certificate store in "enterprise trust" folder

4. Generate application certificate for the client:

   $hostname=$env:computername
   $applicationName = "HumanOS.Dnc.Client"
   & "C:\Temp\Opc.Ua.CertificateGenerator.exe" -cmd issue `
   -au "urn:cybertech:HumanOS:DncClient" `
   -sn "CN=$applicationName/O=UnifiedAutomation/DC=$hostname" `
   -sp ".\ClientApplicationCertificates" `
   -dn $hostname `
   -an $applicationName `
   -st ([datetime]::Now).toFileTime() `
   -ks 2048 `
   -lm 600

5. Install the certificate from .\ClientApplicationCertificates\private\HumanOS.OpcUaServer.pfx locally on the Dnc Client computer in Windows LocalMachine Certificate store in "personal" folder.

6. Install the certificate from .\ClientApplicationCertificates\certs\HumanOS.OpcUaServer.der on the OPC-UA Server (gateway host) in the Windows LocalMachine Certificate store in "enterprise trust" folder.

NOTE

To ensure the functionality of certificates under Windows, it is necessary to set the value to 'Windows' under opc:StoreType in the Appsettings.json file.

User Certificate for Authentication

Authentication with a user certificate is possible. This replaces the authentication using username and password. An extra certificate must therefore be generated. Replace USER with the Username

1. Generate user certificate for

   & openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout .\UserCertificate\<USER>.self.key -out .\UserCertificate\<USER>.self.crt -subj "/CN=<USER>" -extensions v3_ca -extensions v3_req
   
   & openssl pkcs12 -inkey .\UserCertificate\<USER>.self.key -in .\UserCertificate\<USER>.self.crt -export -out .\UserCertificate\<USER>.self.pfx -passout pass:

2. Install the certificate from .\UserCertificate\<USER>.self.pfx locally on the Dnc Client computer in Windows LocalMachine Certificate store in "personal" folder.

3. Install the certificate from .\UserCertificate\<USER>.self.crt on the OPC-UA Server (gateway host) in the Windows LocalMachine Certificate store in "enterprise trust" folder

Machine Configuration

The machine configuration is done in the appsettings.json which is located at .\ProgramData\CyberTech\HumanOS.Dnc.Client\.

There are two sections:

• Common: common settings for all machines
• Machines: machine specific settings (overwrites the ones in Common if same property name is used)

Name	Description	Data Type
opc:SecuritySelection	Security protocol selection of the endpoints: (None: no security requested (default); BestAvailable: select the best available security)	System.String
opc:CertificateHandling	Handling of server certificates: (Strict: only trusted certificates allowed (default); AcceptAll: do not check the certificates)	System.String
opc:StoreType	Specifies the store type, either 'Directory' or 'Windows', if left empty the 'Directory' type is taken	System.String
opc:CertificatePath	For StoreType Windows: Specifies the certificate store path, see HumanOS® OpcUaServer manual.	System.String
opc:CertificateTrustedPath	For StoreType Windows: Specifies path to trusted certificates.	System.String
opc:CertificateIssuerPath	For StoreType Windows: Specifies path to issuer certificates.	System.String
opc:CertificateRejectedPath	For StoreType Windows: Specifies path to rejected certificates.	System.String
opc:CertificateSubject	For StoreType Windows: Specifies the application certificate subject name e.g. CN=servercert/O=myorg/DC=myhost	System.String
opc:AutoGenerateClientCertificate	Automatically generates a client application certificate for the connecting device client. Default is false.	System.Boolean
opc:AllowInsecureCredentials	Allows to send credentials over an insecure connection. (When the server has no TLS certificate but requires authentication) Default is false.	System.Boolean
UserName	[opt] Username to login. Used to authenticate with username and password.	System.String
Password	[opt] Password of the user. Used to authenticate with username and password.	System.String
opc:ClientCertificate	[opt] Client certificate for authentication. Name of certificate (filename or subject name in windows store), requires a ".pfx" file.	System.String
opc:ClientCertificatePassword	[opt] Client certificate password unused for authentication. Optional password.	System.String
opc:EnableTraceLog	[opt] Enabling the trace logger of the UaClient	System.Boolean

NOTE

Set the opc:CertificateSubject to the subject name of the DncClient application certificate. Set the opc:ClientCertificate to the subject name of the user certificate.

Machine specific settings are

Name	Description	Data Type
Name	Name of the machine. This name is referenced using the command line argument -i	System.String
opc:DncNodeId	NodeId of the OPC-UA server representing the DNC command container	System.String

Example:

  "OpcUaClient": {
    "Common": {
      "opc:ServerAddress": "opc.tcp://li-humanosd01:48030/",
      "opc:SecuritySelection": "BestAvailable",
      "opc:CertificateHandling": "AcceptAll",
      "opc:EnableTraceLog": false,
      "opc:AutoGenerateClientCertificate": false,
      "opc:AllowInsecureCredentials": false,
      "opc:UserName": null,
      "opc:Password": null,
      "opc:StoreType": "Windows",
      "opc:CertificatePath": "LocalMachine\\My",
      "opc:CertificateTrustedPath": "LocalMachine\\Trust",
      "opc:CertificateIssuerPath": "LocalMachine\\Root",
      "opc:CertificateRejectedPath": "LocalMachine\\Disallowed",
      "opc:CertificateSubject": "CN=HumanOS.DncClient/O=UnifiedAutomation/DC=client",
      "opc:ClientCertificate": "CN=User",
      "opc:ClientCertificatePassword": ""
    },
    "Machines": [
      {
        "Name": "iTNC530",
        "opc:DncNodeId": "ns=2;s=iTNC530 Simulator/Controller/NCPath1"
      },
      {
        "Name": "TNC640",
        "opc:DncNodeId": "ns=2;s=TNC640 Simulator/Controller/NCPath1",
      }
    ]
  }

DNC General Commands

Print Help

.\HumanOS.Dnc.Client.exe --help

Get List of all configured Machines

.\HumanOS.Dnc.Client.exe --list

DNC File Commands

Reading an NC-file

.\HumanOS.Dnc.Client.exe -i TNC640 "GET TNC:\\Warmup.h C:\Temp\Warmup.h"

Writing an NC-File:

.\HumanOS.Dnc.Client.exe -i TNC640 "PUT C:\Temp\Warmup.h TNC:\\Warmup.h"

Delete an NC-File:

.\HumanOS.Dnc.Client.exe -i TNC640 "DEL TNC:\\Warmup.h"

DNC Directory Commands

Reading Directory:

.\HumanOS.Dnc.Client.exe -i TNC640 "DIR"

Changing current directory:

.\HumanOS.Dnc.Client.exe -i TNC640 "GET TNC:\\Warmup.h C:\Temp\Warmup.h"

Create a new directory (no backslash at the end):

.\HumanOS.Dnc.Client.exe -i TNC640 "MKDIR TNC:\\MDMTOOL"

Delete a directory (no backslash at the end):

.\HumanOS.Dnc.Client.exe -i TNC640 "RMDIR TNC:\\MDMTOOL"

DNC Backup Commands

Creates a backup from the NC memory

.\HumanOS.Dnc.Client.exe -i TNC640 "BACKUP TNC:\\MDMTOOL C:\\Temp\\MyCNC"

DNC Tool Transfer Commands

Reading entire tool table as file:

.\HumanOS.Dnc.Client.exe -i TNC640 "GET TNC:\\tables\tool.t C:\Temp\tool.t"

Writing tools to the machine (with merge command):

.\HumanOS.Dnc.Client.exe -i TNC640 "PUT C:\Temp\tool2.t TNC:\\tables\tool.t /m"

NOTE

iTNC530 based controls uses the tool table in location TNC:\\tool.t.

Also some attributes are not correctly transmitted, like

• RT : cannot be written, ignored
• NMAX: cannot be written, ignored
• TT:R-OFFS: cannot be reset back to R

Debugging

Connection Failed "Schlüsselsatz"

Error Message

• Der Schlüsselsatz nicht vorhanden

Error Description: The client or user certificates are not installed on the client. The application cannot find any certificate with the corresponding CN.

The error might also appear after rebooting your client computer.

Solution:

1. Check if the DncClient and User certificates are already installed in "Eigene Zertifikate".

   Remove the old certificates first

2. Install the private DncClient certificate to LocalComputer - "Eigene Zertifikate"

3. Install the private User Certificate (PFX file) to LocalComputer - "Eigene Zertifikate"

Missing Private Key

Error Message

• The Certificate must have an accessible private key.

Error Description The user certificate has not a private key.

Solution

1. Check if the User certificate is already installed in "Eigene Zertifikate".

   Remove the old certificate first

2. Install the private User Certificate (PFX file) to LocalComputer - "Eigene Zertifikate"

BadNodeId on Softing

This error appears, if the namespace ns is not correct.

1. Select the node <Maschine>/Controller/NCPath1 on the Softing server address space and take the namespace from the node id.

DNC Client Configuration for Softing

  "OpcUaClient": {
    "Common": {
      "opc:StoreType": "Windows",
      "opc:CertificatePath": "LocalMachine\\My",
      "opc:CertificateTrustedPath": "LocalMachine\\Trust",
      "opc:CertificateIssuerPath": "LocalMachine\\Root",
      "opc:CertificateRejectedPath": "LocalMachine\\Disallowed",
      "opc:CertificateSubject": "CN=HumanOS.DncClient/O=UnifiedAutomation/DC=client",
      "opc:ClientCertificate": "CN=User",
      "opc:ClientCertificatePassword": "",
      "opc:SecuritySelection": "BestAvailable",
      "opc:CertificateHandling": "AcceptAll",
      "opc:EnableTraceLog": false,
      "opc:AutoGenerateClientCertificate": false,
      "opc:AllowInsecureCredentials": false,
      "opc:UserName": null,
      "opc:Password": null,
      "opc:ServerAddress": "opc.tcp://<SERVER>:4897/"
    },
    "Machines": [
      {
        "Name": "HermleB300",
        "opc:DncNodeId": "ns=11;s=HermleB300/Controller/NCPath1"
      },
      {
        "Name": "HermleC40",
        "opc:DncNodeId": "ns=15;s=HermleC40/Controller/NCPath1"
      },
      {
        "Name": "HermleC42-14",
        "opc:DncNodeId": "ns=19;s=HermleC42-14/Controller/NCPath1"
      },
      {
        "Name": "HermleC42-17",
        "opc:DncNodeId": "ns=23;s=HermleC42-17/Controller/NCPath1"
      }
    ]
  }

Unable to Load Certificates after Reboot

Error Message The private certificates can not be loaded by the application after the reboot of the windows client. The bug can be temporary fixed reinstalling of the pfx files. But after a reboot, the certificates cannot be loaded again.

Solution The problem lays in the access of the private key. After the installation, the security access must be explicitly set to a client user group.

1. Right-click the certificate in MMC console - All Tasks - Manage Private Keys.
2. Add the needed users or group to access. Now, reboot the system and try - it will work.