C++ Based OPC UA Client/Server SDK  1.6.4.457
Discovery and Security Configuration

SDK Specific Configuration

The following page describes the general OPC UA concepts for Discovery and security configuration.

Please refer to the following pages for SDK specific information:

Server side:
Server Configuration (XML configuration file, INI configuration file)
Client side:
Security Configuration, Getting Started Lesson 4: Discovery and Secure Connection

General Concept

To connect to a server, a client needs information like network address, protocol, and security settings. For this purpose, OPC UA defines a set of discovery features.

For the connection between client and server, OPC UA provides different security features for different purpose and for different levels of security:

  • Application Authentication based on Certificates
  • Secure communication channel with message signing and encryption based on Security Policies
  • User Authentication based on different user tokens
  • User Authorization based on roles
  • Access control down to nodes and attributes
  • Audit mechanisms for connection establishment, Write and Call services

All information which is required to establish a connection between client and server is stored in a so-called endpoint. A server can provide several endpoints, each containing

  • Endpoint URL (protocol and network address)
  • Security Policy (name for a set of security algorithms and key length)
  • Message Security Mode (security level for exchanged messages)
  • User Token Type (types of user authentication supported by the server)

If several OPC UA servers exist, a Discovery Server can be used to provide information of available servers. Servers can register at the Discovery Server. Clients may then request a list of all available servers from the discovery server and then use the GetEndpoints service to get connection information from a server.

discovery_server.png

The initial configuration on client and server side, the different options to find available servers, and the connection establishment between client and server is described in the following sections.

Security Policies

A Security Policy specifies which security mechanisms are to be used for the Secure Channel between client and server. A SecurityPolicy defines the algorithms for signing and encryption, the algorithm for key derivation and the key lengths used in the algorithms.

A Security Policy is derived from a security profile defined in OPC UA Part 7 - Profiles. The security profiles are regularly updated since specific algorithms may be considered insecure in the future or a key length is not longer secure because of increased compute power.

Therefore each OPC UA profile specification release may add new Security Policies and may deprecate older Security Policies.

OPC UA defines a unique URI for each Security Policies. The following table contains the currently valid Security Policies:

Security PolicyURI
Aes256_Sha256_RsaPss http://opcfoundation.org/UA/SecurityPolicy#Aes256_Sha256_RsaPss
Aes128_Sha256_RsaOaep http://opcfoundation.org/UA/SecurityPolicy#Aes128_Sha256_RsaOaep
Basic256Sha256 http://opcfoundation.org/UA/SecurityPolicy#Basic256Sha256
None http://opcfoundation.org/UA/SecurityPolicy#None

The following table contains the already deprecated Security Policies:

Deprecated Security PolicyURI
Basic256 (Deprecated) http://opcfoundation.org/UA/SecurityPolicy#Basic256
Basic128Rsa15 (Deprecated) http://opcfoundation.org/UA/SecurityPolicy#Basic128Rsa15
Note
For security reasons, the Security Policies Basic128Rsa15, Basic256 and None should be deactivated by default. It is up to an administrator to enable deprecated Security Policies for backward compatibility but the user must be warned about the deprecated status of these Security Policies.

Certificates, Certificate Store and Trust List

To identify itself to communication partners, each installed OPC UA application or devices needs an Application Instance Certificate and an associated public/private key pair. The public key is distributed with the certificate. The private key has to remain secret and is used to sign and/or decrypt messages. A communication partner can use the public key to verify the trust relation, check the signature of messages, and encrypt messages. The Application Instance Certificate, including the public and private key, can either be generated by the application or provided by an administrator.

Certificates are filed in a Certificate Store, containing separate locations for trusted and own certificates, as well as certificates from certificate authorities used to verify certificate chains. An additional rejected location may contain certificates of applications that tried to connect but are not trusted yet.

Certificates issued by the application are called self-signed certificates. They are typically generated during installation of the application or at first start. To establish a trust relation between an OPC UA client and server, the self-signed certificates of the communication partner are installed to the trust list. The client certificate is installed to the trust list of the server and the server certificate to the trust list of the client. If the certificate of an application is removed from the trust list, a communication establishment is no longer possible.

Certificates signed by Certificate Authorities (CA) enable central trust management for a group of OPC UA applications or devices. In this case, just the CA certificate must be installed to the trust list of the OPC UA applications. After the CA certificate is installed, all other applications with certificates signed by the CA are able to communicate with each other. To be able to exclude previously trusted applications from the communication, the CA maintains a Certificate Revocation List (CRL). Each installed CA certificate must have an associated, up-to-date CRL installed. This CRL is required for a verification of the trust relation. The OPC UA Global Discovery Server definition provides a mechanism for central management of CA signed certificates and update of the corresponding CRLs. CA certificates can build a chain, e.g. a root CA for a company, a CA for a site where the site CA is signed by the root CA and a CA for a production line in the site. An OPC UA application in the production line would only trust the CA for the production line. The other CA certificates are only used to verify the chain.

A file based certificate store contains the following directories. Names and structure may differ between applications.

Own
Application Instance Certificate and private key of the application
Trusted
Self-signed certificates of trusted OPC UA applications or CA certificates for trusted CAs. Each CA certificate comes with a CRL that requires frequent updates.
Issuers
CA certificates that are not directly trusted but required to verify a chain of CA certificates. Each CA certificate comes with a CRL that requires frequent updates.

In addition, there is typically a Rejected directory where the OPC UA application can store certificates from other OPC UA applications that tried to connect but were not trusted. Administrators can move certificates from Rejected to Trusted if the application is allowed to connect.

As an example, let’s look at a production line where ServerX, ClientY, and ClientZ need to communicate with each other. In the simplest case, a single certificate authority (CaLine1R) manages the central certificate management of the production line (and is thus the root CA). ServerX, ClientY, and ClientZ are all signed by CaLine1R (see figure below). To trust each other, it’s only necessary to install the certificate and the associated certificate revocation list of CaLine1R.

certificate_authority.png
Certificate Authority

In a more complex set-up, e.g. if production line 1 is part of a larger plant consisting of more than one line, itself being part of a company having several production sites, there may be more than one certificate authority, altogether forming a certificate chain (see figure). CaLine1 is signed by CaPlantA (the production site’s certificate authority), which in turn is signed by CaRoot (the company’s root certificate authority). Each of these CAs keeps its own certificate revocation list.

certificate_chain.png
Certificate Chain

The following figure exemplarily shows the content of a file based certificate store for ClientX in the above mentioned scenarios. In both cases, the directories own look identical: The subfolder certs contains the client’s own certificate ClientX.der and private contains the private key ClientX.pem.

The content of the folders trusted is similar in both cases: certs contains the certificate of the trusted certificate authority (i.e. the CA signing the applications to trust): CaLine1R.der in the simple case without certificate chain, and CaLine1.der in the more complex case. The associated certificate revocation list CaLine1R.crl (simple case) or CaLine1.crl (certificate chain example) has to be placed into the subfolder crl.

If there’s no certificate chain, the folder issuers remains empty. If there is a certificate chain, issuers has to contain all certificates needed to validate the complete chain in the subfolder certs, and one and only one certificate revocation list for each certificate authority in the folder crl. In our example above, we have two superordinate certificate authorities: CaPlantA and CaRoot. Thus, the folder certs contains the certificates CaPlantA.der and CaRoot.der, and the folder crl contains the certificate revocation lists CaPlantA.crl and CaRoot.crl.

certificate_store_clientx.png
Certificate Store Configuration for ClientX with Certificate Chain (top) and without (bottom)

Initial Server Configuration

The following figure shows the initial configuration of a server after installation.

server_initial_config.png

The configuration consists of

  • an application instance certificate identifying the server installation
  • a certificate store, including a list of trusted and rejected application instance certificates
  • at least one endpoint (see below)

Endpoints

A server has to provide (at least one) endpoint(s) where clients can connect to. A client uses the Discovery URL (normally identical to the Endpoint URL) to request the list of endpoints including the security configuration from a server. This request through the GetEndpoints service always works without security. The Discovery URL is normally provided by Discovery servers.

The Endpoint URL provides the basic information that clients need to connect to a server, including the protocol, the host name or IP address, and the port number, e.g. opc.tcp://localhost:48020. In addition, the client needs to know the following security options configured on the server.

The Security Policy defines the algorithms and key length used by the client to establish a Secure Channel with the server. See Security Policy above for more details on the available Security Policies.

The Message Security Mode configures the general level of security applied to messages exchanged between client and server. Three Message Security Modes are defined:

None
No security is applied.
Sign
All messages are signed but not encrypted.
Sign&Encrypt
All messages are signed and encrypted.
Note
For security reasons, the Security Policies Basic128Rsa15, Basic256 and None as well as the Message Security Mode None should be deactivated by default.

OPC UA supports the following User Identity Token Types

Anonymous Identity Token
No user information is available.
Username Identity Token
A user identified by user name and password.
X.509 Identity Token
A user identified by an X509v3 Certificate.
Issued Identity Token
A user identified by a JSON Web Token (JWT).

A typical set of endpoints could be:

Endpoint 1Endpoint 2
Endpoint URL
opc.tcp://MyServer:48001
Security Policy
Basic256
Message Security Mode
Sign, SignAndEncrypt
User Token Type
Username, X.509
Endpoint URL
opc.tcp://MyServer:48001
Security Policy
Basic256Sha256
Message Security Mode
Sign, SignAndEncrypt
User Token Type
Username

Discovery Server

Servers may register at so-called Discovery Servers so that they can be discovered by clients. The registration process is described further on for the different Discovery options.

A Local Discovery Server (LDS) on a network node is only necessary if more than one OPC UA server is available, e.g. on a Windows PC with several OPC UA servers installed. In this case, the LDS is listening on port 4840, which is the IANA registered port for OPC UA. OPC UA clients start the discovery process with FindServers using this port.

OPC UA servers on devices or other systems with just one server use port 4840 directly. There is no need for a LDS in this case. Every OPC UA server implements the FindServers service returning itself.

Initial Client Configuration

The following figure shows the initial configuration of a client after installation:

client_initial_config.png

The configuration consists of

  • an application instance certificate to identify the client application
  • a certificate store, including a list of trusted certificates
  • list of server endpoints (see below)

List of Server Endpoints

A client can find servers using the different Discovery options and retrieve the information it needs to connect to a server via the OPC UA service GetEndpoints. To avoid having to repeat this Discovery process before each connection attempt, most clients will store the server endpoint information for a configured server.

Connection Configuration

Once a client has found the server it intends to connect to, the client is able to call GetEndpoints. The server returns a list of endpoints it provides, including the security configuration (see above) as well as its certificate (including the server’s public key).

get_endpoints.png

For being able to establish a secure connection to the server, the client has to trust the server’s certificate, i.e. the certificate has to be added to the trust list. Usually, a dialog window will open and prompt the user to examine the certificate and decide whether it should be trusted.

The following screenshot shows the respective dialog window in UaExpert when trying to connect to a server for the first time. It displays the content of the server’s certificate and allows the user to decide whether to trust the certificate or not. If the user chooses “Trust Server Certificate”, it is stored in the folder trusted/certs in UaExpert’s PKI certificate store.

expert_server_certificate_scaled.png

Having trusted the certificate, the client is able to check the signature of messages from the server and encrypt messages to be sent to the server. After saving the endpoints to the server connection list, the client configuration is finished.

client_configured.png

Now the client can attempt to create a secure channel with the server, sending along its Application Instance Certificate (including the public key of the client). This first connection attempt will be rejected, because the server doesn’t trust the client yet.

create_secure_channel.png

Trusting the client’s certificate is a manual step on the server. Usually, a server administrator has to move the client certificate from the list of rejected to the list of trusted certificates.

client_certificate_rejected.png

When using the C++ SDK Demo Server, this can be done using the administration tool as shown in the following screenshot. The “Certificates” tab lists the certificates in the server’s Certificate Store. Certificates from the Trusted directory are shown as trusted and the certificates from the Rejected directory are shown as untrusted. UaExpert’s certificate is shown as “Untrusted”. Right clicking on the certificate and choosing “Trust” from the context menu moves the certificate from the folder rejected to trusted/certs in the server’s Certificate Store.

admin_dialog_trust_certificate_scaled.png

After this step, the server is configured.

server_configured.png

The next attempt of the client to create a secure channel will succeed, and it is able to create and activate a session with the server.

secure_connection.png

Reverse Connect

The creation of a secure channel includes a TCP/IP connection establishment from client to server. In this case the server opens a port that is used by the client to create the TCP/IP connection.

OPC UA provides also a Reverse Connect capability where client opens a port and the TCP/IP connection is created by server to the client. After this initial TCP/IP connection establishment, the client creates the secure channel and the session the same way as for the normal connect.

For this case the server needs to know the clients that want to connect and must try to establish the TCP/IP connections to allow the clients to complete the secure channel and session establishment. All further actions after the initial TCP/IP connect are initiated by the client. This includes the connection monitoring.

Discovery

Before a client can connect to a server, it needs to collect information. Therefore, OPC UA defines three different discovery options:

  • Local Discovery
  • Multicast Subnet Discovery
  • Global Discovery

Local Discovery

If a client does know that there are OPC UA servers running on a certain host, but doesn’t have detailed connection information, it can construct a connection URL from the host name and the standard OPC UA port 4840 (e.g. opc.tcp://localhost:4840 or opc.tcp://targetHost:4840). This URL is then used to connect to the discovery server and to call FindServers.

If more than one OPC UA server is installed on a system, a Local Discovery Server (LDS) is running on port 4840. The LDS maintains a list of available servers which may be used by servers to announce their existence to clients.

To be visible for local discovery, servers have to register at the LDS using either the RegisterServer2 or the RegisterServer service. The registration with the LDS requires security configuration. Therefore, the server certificate must be installed in the trust list of the LDS.

local_discovery.png

If only one server is installed, a separate LDS is not necessary and the server itself will use the port 4840 and will respond to FindServers returning itself.

Multicast Subnet Discovery

For situations where the client doesn’t know the available servers on the network, OPC UA defines the use of mDNS, a standardized multicast extension to DNS also known as zeroconf. mDNS defines mechanisms for name resolution without a central DNS server as well as service discovery functionality. This ad-hoc discovery typically works only within a subnet.

For regular OPC UA applications, the functionality is provided by Local Discovery Servers with multicast extension (LDS-ME). Servers registered with the LDS are automatically announced via LDS-ME. Servers registered with RegisterServer2 can also provide a list of server capabilities that can be used for filtering the list of available servers.

Another feature of an LDS-ME is the creation of a local cache with OPC UA servers announced via mDNS.

Clients can retrieve this list by calling the service FindServersOnNetwork on the local LDS-ME.

multicastsubnet_discovery.png

Global Discovery Server

The OPC UA Global Discovery Server (GDS) concept allows the configuration of a network wide discovery of OPC UA servers that is not limited to a subnet like mDNS. In addition, it provides functionality for central certificate management including the distribution of CA signed certificates and related Certificate Revocation Lists (CRL). A GDS is a complete OPC UA Server and therefore provides the only secure discovery option.

For the discovery functionality, OPC UA servers must be registered as application with the GDS when they are installed within the network. The registration requires security and administrative rights on the GDS.

OPC UA clients can query the GDS for available servers using different filter options (like capability filter of a string pattern matching on product or application URIs).

gds_simple.png

If the GDS is registered at different LDS-MEs in different subnets, the GDS can be found by clients using FindServersOnNetwork on the local LDS-ME.

gds_ldsme.png

Certificate Management with GDS

OPC UA applications registered with a GDS can use the GDS also for central certificate management.

The GDS can manage self-signed certificates, but the main use case is the management of a Certificate Authority (CA), the generation of CA signed Application Instance Certificates, and the distribution of the CA related Certificate Revocation Lists (CRL). More details regarding Certificates can be found in Certificates, Certificate Store and Trust List.

The OPC UA interface DirectoryType provides application registration and discovery functionality. The OPC UA interface CertificateDirectoryType of the GDS encapsulates a CA or the communication with the CA and the related certificate management functionality.

The certificate management includes

  • the initial set-up of an Application Instance Certificate
  • regular updates of the trust list and CA related Certificate Revocation Lists
  • renewal of Application Instance Certificates
gds_application_setup.png

The initial application set-up requires administrative rights. The first step is the registration of the client or server applications using DirectoryType::RegisterApplication. Registered servers are returned in calls to DirectoryType::QueryServers.

The second step is the creation of a CA signed certificate. A call to CertificateDirectoryType::StartSigningRequest is used to send a certificate signing request to the CA. With this method, the private key is kept in the client and server application and is only used to sign the request. The CA uses the request to create and sign the public key. An alternative is the creation of a private and a public key using the method CertificateDirectoryType::StartNewKeyPairRequest. After the request is processed by the GDS, the new certificate can be used by the OPC UA application. The initial set-up also includes the initial transfer of the trust list for the application from the GDS to the application.

gds_pull.png

Since a CA can revoke certificates, the application trust lists and the CA related Certificate Revocation Lists (CRL) must be updated frequently. If the OPC UA application is a client or a server with client functionality, the OPC UA application can use CertificateDirectoryType::GetTrustList to request the latest trust list and CRLs from the GDS OPC UA server.

This update model is called Pull Certificate Management.

gds_push.png

For OPC UA servers without client functionality, the GDS concept defines also a server side interface called ServerConfigurationType. It allows the management of the server certificate and the trust list through a standard interface. The management is done through a GDS client that connects to the GDS on behalf of the server to manage and update the server through the ServerConfiguration object.

This update model is called Push Certificate Management.

The ServerConfiguration object enables also remote certificate management without a GDS by using tools like UaExpert.

All certificate management related functionality requires administrative rights and encrypted communication channels.

User Authentication

User authentication allows the server to verify the identity of the client user credentials. The user credentials are passed as User Identity Token in the Service ActivateSession

OPC UA supports the following User Identity Token Types

Anonymous Identity Token
No user information is available.
Username Identity Token
A user identified by user name and password.
X.509 Identity Token
A user identified by an X509v3 Certificate.
Issued Identity Token
A user identified by a JSON Web Token (JWT).
user_authentication.png

The client shall always prove possession of a User Identity Token when it passes it to the server in ActivateSession.

The Username Identity Token includes a password as secret which the server will accept as proof.

X.509 Identity Tokens allow the client to create a signature with the secret associated with the token. In this cases, the client proves possession of a User Identity Token by creating a signature with the secret (private key) and passing the signature to the server.

The Issued Identity Token is used to pass security tokens issued by an external authorization service to the server. The standard option for Issued Identity Tokens are JSON Web Tokens (JWT). The external authorization service authorizes the client and user credentials for the server. If the access to the server is granted, the external authorization service creates a token and a signature for the token. The server uses the signature contained in the JWT to validate the token. The token must be treated as secret.

In order to protect tokens that contain a secret these tokens are encrypted before they are passed to the server.

After checking the user credentials, the server verifies if the user is allowed to create a session with the server. This can be done with a user data base in the case of Username Identity Token or X.509 Identity Token or by trusting the verification of an external authorization service for the Issued Identity Token.

User Authorization

A role is a function assumed by a client when it accesses a server. Roles are used to separate authentication (determining who a client is) from authorization (determining what the Client is allowed to do). By separating these tasks servers can allow centralized services to manage user identities and credentials while the server manages the permissions on its nodes for roles. But even if the mapping of users to roles is done in the server, the management of permissions for the nodes can be separated from the management of users and the assignment of users to roles.

user_authorization1.png

When a Session is created, the server must determine what roles are granted to that Session. OPC UA defines standard mapping rules which servers may support. Servers may also use vendor specific mapping rules in addition to or instead of the standard rules.

The standard mapping rules allow Roles to be granted based on:

  • User identity
  • Application identity
  • Endpoint used to connect

User identity mappings can be based on user names, user certificates or roles in an Issued Identity Token.

Application identity mappings are based on the ApplicationUri specified in the client certificate.

OPC UA defines the following well known roles. A server can define additional roles.

Standard RoleDescription
Anonymous The role has very limited access for use when a Session has anonymous credentials.
AuthenticatedUser The Role has limited access for use when a Session has valid non-anonymous credentials but has not been explicitly granted access to a specific role.
Observer The role is typically allowed to browse, read live data, read historical data/events or subscribe to data/events.
Operator The role is typically allowed to browse, read live data, read historical data/events or subscribe to data/events. In addition, the Session is allowed to write some live data and call some Methods.
Engineer The role is typically allowed to browse, read/write configuration data, read historical data/events, call Methods or subscribe to data/events.
Supervisor The role is typically allowed to browse, read live data, read historical data/events, call Methods or subscribe to data/events.
ConfigureAdmin The role is allowed to change the non-security related configuration settings.
SecurityAdmin The role is allowed to change security related settings.

OPC UA defines also a standard access control mechanism for nodes called RolePermission. A RolePermission defines the permissions mask for a role. The permission mask defines the access to attributes of the Node or the Service specific access to Nodes.

The following table shows example RolePermissions for the Node in the following figure.

RolePermissions
Observer Browse, Read
Operator Browse, Read, Write
user_authorization2.png

The attribute RolePermissions is only readable for security administrators. It contains the list of RolePermissions for the Node. If the attribute is writable, the security administrator is able to change the RolePermissions.

For some attributes like UserAccessLevel, the attribute value depends on the role permissions.

The following table provides the list of permission masks.

PermissionDescription
Browse The client is allowed to see the references to and from the Node. This implies that the client is able to Read to attributes other than the Value or the RolePermissions attribute.
Read The client is allowed to read the Value attribute. This bit affects the CurrentRead bit of the UserAccessLevel attribute.
Write The client is allowed to write the Value attribute. This bit affects the CurrentWrite bit of the UserAccessLevel attribute.
Call The client is allowed to call the Method if this bit is set on the Object or ObjectType Node passed in the Call request and the Method Instance associated with that Object or ObjectType. This bit affects the UserExecutable attribute when set on Method Node.
WriteHistorizing The client is allowed to write to the Historizing attributes if the WriteMask indicates that the Attribute is writeable. This bit affects the value of the UserWriteMask attribute.
WriteAttribute The client is allowed to write to attributes other than the Value, Historizing or RolePermissions attribute if the WriteMask indicates that the attribute is writeable. This bit affects the value of a UserWriteMask attribute.
ReadRolePermissions The client is allowed to read the RolePermissions attribute.
WriteRolePermissions The client is allowed to write to the RolePermissions attribute if the WriteMask indicates that the attribute is writeable. This bit affects the value of the UserWriteMask attribute.
ReadHistory The client is allowed to read the history associated with a Node. This bit affects the HistoryRead bit of the UserAccessLevel attribute.
InsertHistory The client is allowed to insert the history associated with a Node.
ModifyHistory The client is allowed to modify the history associated with a Node.
DeleteHistory The client is allowed to delete the history associated with a Node.
ReceiveEvents A client only receives an Event if this bit is set on the Node identified by the EventTypeId field and on the Node identified by the SourceNode field.
AddReference The client is allowed to add references to the Node.
RemoveReference The client is allowed to remove references from the Node.
DeleteNode The client is allowed to delete the Node.
AddNode The client is allowed to add Nodes to the Namespace.