High Performance OPC UA Server SDK  1.7.0.367
SDK Migration Guide

This section contains instructions for migrating existing applications to a new SDK release.

Migration from 1.6.x to 1.7.0

Change in certificates section of the config file.

The parameter issuer_index was not used and has been removed. If it is set in the config file, loading of the file will cause an error. Simply remove it from your config file to fix this issue. This parameter mus also be removed from appconfig.c files if you are using a hardcoded configuration.

Change in the pubsub section of the config file

Various settings where added to this section. At least the following must be configured in addition to the existing ones to achieve the behaviour of the previous versions. If the new options are missing, no non-empty configuration will be loaded. In previous versions these limits where hard coded. Now it is possible to set the limits at compile time and configure any limit equal or smaller to the compile time limit in the server settings.

[pubsub]
max_config_size = 10000000
max_connections = 4
max_writer_groups = 8
max_reader_groups = 8
max_dataset_writers = 32
max_dataset_readers = 32
max_published_datasets = 32
max_subscribed_datasets = 32
max_security_groups = 32

Migration from 1.5.x to 1.6.0

Provider Array Initialization

A new field user_data was added to the struct uaserver_provider, it is recommended to use the new macro UASERVER_PROVIDER_INITIALIZER to avoid possible further breaks. Thus code like this:

static struct uaserver_provider g_provider[] = {
{-1, uaprovider_server_init},
{-1, my_provider_init},
};

should be changed to this:

static struct uaserver_provider g_provider[] = {
UASERVER_PROVIDER_INITIALIZER(uaprovider_server_init),
};

Rolepermissions

The introduction of the UA Rolepermissions in the SDK requires a few changes. All the details are explained in the Authorization section, this document will point out the two most fundamental aspects required to get started with Rolepermissions:

Namespace Default Permissions

With Rolepermissions each namespace has default permissions, which are used for each node without explicitly assigned permissions. When no default permissions are loaded (e.g. included in the XML file) the SDK assigns some default permissions, which are more restrictive than before the introduction of Rolepermissions. Thus it is recommended to explicitly set namespace default permissions for all namespaces (including NS0 and NS1), here is an example how this can be done:

#include <uaserver/addressspace/addressspace.h>
#include <uaserver/addressspace/rolepermissions.h>
#include <uabase/structure/permissiontype.h>
int ret;
uint16_t my_nsidx = <assign namespace index>
struct ua_addressspace *addr;
struct ua_nodepermission np[3];
const struct ua_rolepermissiontype rp[3] = {
{
UA_NODEID_NUMERIC_INITIALIZER(UA_ID_WELLKNOWNROLE_ANONYMOUS, 0),
UA_PERMISSIONTYPE_READ
| UA_PERMISSIONTYPE_BROWSE
},
{
UA_NODEID_NUMERIC_INITIALIZER(UA_ID_WELLKNOWNROLE_AUTHENTICATEDUSER, 0),
UA_PERMISSIONTYPE_READ
| UA_PERMISSIONTYPE_BROWSE
| UA_PERMISSIONTYPE_WRITE
| UA_PERMISSIONTYPE_READHISTORY
| UA_PERMISSIONTYPE_RECEIVEEVENTS
| UA_PERMISSIONTYPE_CALL
},
{
UA_NODEID_NUMERIC_INITIALIZER(UA_ID_WELLKNOWNROLE_SECURITYADMIN, 0),
UA_PERMISSIONTYPE_READ
| UA_PERMISSIONTYPE_READROLEPERMISSIONS
| UA_PERMISSIONTYPE_BROWSE
| UA_PERMISSIONTYPE_WRITE
| UA_PERMISSIONTYPE_READHISTORY
| UA_PERMISSIONTYPE_RECEIVEEVENTS
| UA_PERMISSIONTYPE_CALL
},
};
if (ret != 0) return ret;
addr = ua_addressspace_getaddr(my_nsidx);
if (addr == NULL) return UA_EBADNOTFOUND;
if (ret != 0) return ret;

Role Configuration

Rolepermissions require roles to be configured with identity mapping rules, which make sure incoming clients are correctly assigned to roles. The SDK allows to configure these mappings via a configuration file, an example file is included as roles.conf. The roles configuration file must be set in the main configuration file as authorization_roles_file:

[session]

authorization_roles_file = roles.conf

The former groups and users files are not used anymore, because the uid/gid based authorization concept was superseded by the UA Role Permission concept. The passwd file is still used for user authentication and defines the available users with their individual password.

Certificate configuration

Naming of own certificates and own keys

It is no more necessary to use certificate configuration files. Own certificates and keys can be identified by a textual name instead of the SHA1 thumbprint. Internally the PKI store still identifies certificates and keys by their thumbprint. The PKI store itself will map the names to the SHA1 thumbprints. This mapping is stored in the file sha1table.txt in the file based PKI store. You MUST NOT edit this file, because it is entirely managed by the store and this file is just an implementation detail.

When importing a "own" certificate you can also specify the name to use in uacertmgr.

> ./uacertmgr -n myserver import-own <der-file> <pem-file>
Successfully imported certificate into 'own'.
Successfully imported private key into 'own'.

Please see the following example certificate configuration. It defines two own (private) certificates/keys. One certificate is named "server4k", the other certificate is named "server2k".

[certificates]

certificates/size = 2 certificates/0/certificate = store://server4k certificates/0/key = store://server4k certificates/0/store = 0 certificates/0/certificate_type_id = UA_RSA_256_TYPE certificates/0/days_valid = 1448 certificates/0/algorithm = sha256 certificates/0/key_usage = server_auth certificates/0/key_length = 4096 certificates/0/issuer_index = 2 certificates/0/create = true certificates/1/certificate = store://server2k certificates/1/key = store://server2k certificates/1/store = 0 certificates/1/certificate_type_id = UA_RSA_MIN_TYPE certificates/1/days_valid = 1448 certificates/1/algorithm = sha256 certificates/1/key_usage = server_auth certificates/1/key_length = 2048 certificates/1/issuer_index = 2 certificates/1/create = true

The SDK will automatically generate the "sha1table.txt" file from these data. Each PKI store holds it's own file.

An example for the content of the file is:

2451CBE654B1C7FDD08CD8D6833117867A44702D server2k 22968601C3F33EA367634F2688CE898877B3C6D3 server4k

This makes it unnecessary to write a new certificate configuration if a certificate or key is exchanged (e.g. via GDS). Only the "sha1table.txt" file needs to be updated with the new SHA1 by the SDK.

When using the "file://" scheme instead of "store://" no mapping file is used as the certificate and the key are loaded with the given file path.

Note: Do not name the certificate and the key equally in the "file://" case, else the certificate file is overridden by the key file.

Certificate Groups

A certificate group defines a set of certificates. Each certificate is of one certificate type (see next section). Within one certificate group a certificate type must be used only once. A certificate is selected with the combination of certificate group and certificate type. The DefaultApplicationGroup is defined within namespace 0. It is possible to define an own certificate group. These groups must be defined within namespace 1. Please see below for an example.

The settings file has to be updated to set the certificate groups setting. In the most cases it is enough to define the DefaultApplicationGroup.

Application Certificate Types

A certificate must be of a certain certificate type. Currently two certificate types are supported.

Attention: Only one instance per certificate type may exist per certificate group. This is a limitation designed by the OPC UA Specification and we cannot change this.

UA_RSA_256_TYPE

This type references the RsaSha256ApplicationCertificateType as defined in Part 12 section 7.5.16. The key length must be 2048, 3072 or 4096 bits. This type must be used if Basic256Sha256, Aes128_Sha256_RsaOAep or Aes256_Sha256_RsaPss profile is used.

UA_RSA_MIN_TYPE

This type references the RsaMinApplicationCertificateType as defined in Part 12 section 7.5.15. The key length must be 1024 or 2048 bits. This type must be used if Basic128Rsa15 and Basic256 profiles are used.

Configuration settings

[cagroup] settings

This section defines the CertificateGroups as defined in Part 12. A server may support more than one certificate group. At least one certificate group must be supported. A certificate group specifies a set of certificates which are handled within a PKI store. Each certificate group must have one PKI store assigned.

The following [cagroup] section defines the usage of the DefaultApplicationGroup.

[cagroup]

cagroups/size = 1
cagroups/0/cagroupid = DefaultApplicationGroup
cagroups/0/store_index = 0
cagroups/0/certificates = 0

The store index defines the index of the used pki store. The certificates parameter defines a list of indices in the certificates list.

The following [cagroup] section defines the usage of the "MyCertGroup". A user defined certificate group must always be located in the server workspace (ns=1).

[cagroup]

cagroups/size = 1
cagroups/0/cagroupid = "ns=1;s=MyCertGroup"
cagroups/0/store_index = 0
cagroups/0/certificates = 0

[endpoint] settings

In this section the connection between the certificate groups and the certificates is done.

[endpoint]

security_policies/X/cagroupid = DefaultApplicationGroup
security_policies/X/certificate_type_id = UA_RSA_256_TYPE

The example above defines that the security policy X uses the DefaultApplicationGroup and certificate of type UA_RSA_256_TYPE. With this both settings the certificate can be located which belongs to the policy.

Certificate validation.

The following checks are performed:

  • The key length of a certificate must match it's type.
  • The certificate_type_id must be set.
  • The certificate_type_id must match the security policy.
  • No certificate is assigned to more than one certificate group.
  • A certificate group has only one certificate of one certificate type assigned.

New Application Settings

[gds] settings

# Maximum size of transmitted trustlist object
# 0 indicates a default size of 8000 bytes instead of unlimited.
max_trustlist_size = 5000

See GDS Section (server only) for more information.

Migration from 1.4.x to 1.5.0

New Application Settings

The appconfig struct as well as the according settings.conf parameters have been extended for this version and may require updates of existing configuration files depending on the enabled features.

Certificate Configuration

With V1.5.0 support for GDS Push model has been introduced and this required improving the handling of store:// prefix in settings.conf. The file:// prefix is not affected by this change and works as before.

In V1.4.x the SDK was searching for the correct certificate based on the certificate metadata if the SHA1 ID was missing in the certificate configuration. This heuristic was never 100% reliable, but avoided changing the settings.conf every time when the certificate was changed (e.g. initial self-signed generation).

With V1.5.0 it is now required to enter the correct SHA1 e.g. store://51A16B6E182F584ABAF30D5A8A2E4C41B0F4EE3F. In this case it is 100% guaranteed that the correct certificate gets loaded. An invalid SHA1 ID will cause a configuration error on startup.

The empty configuration using store:// is still used and working for the initial configuration. This will tell the SDK that a new certificate needs to be generated. The SDK will update the configuation automatically if the new parameter certificate_conf_filename was set.

Because we don't want to overwrite the settings.conf and loose all comments and formatting, we moved the certificate configuration into a separate new file (e.g. certificates.conf), which gets included by settings.conf using the newly introduced 'include' support. This way the SDK can overwrite the certificates.conf with updated information whenever a new certificate is created. This works for both SDK-generated self-signed certificates and certificates downloaded by GDS Push.

The new parameter and include statement is found in the general section:

[general]
# Set the configuration file for the certificates.
certificate_conf_filename = certificates.conf
# Include the certificate section [certificates].
!include certificates.conf

The !include directive performs the include operation. The parameter certificate_conf_filename tells the SDK where to save updated certificate configurations.

FileType Settings

For the new UA FileType functionality new settings habe been added in the [server] section:

# Maximum number of file objects
num_fileobjects = 5
# Maximum number of file handles (opened files)
num_filehandles = 5
# Timeout [sec] when inactive filehandle get reclaimed
filehandle_timeout = 60

Server Settings

The [server] section now allows to configure the server capabilities. You should configure this to match your server's capabilities.

GDS Push Settings

A new section for GDS configuration has been added.

[gds]
# MaxTrustListSize - 0=unlimited
maxtrustlistsize = 0

When building with GDS support you should also add the "GDS" capability to the [server] section.

GDS functionality depends on UA FileType, so you need to configure this as well.

Mempool Settings for NS0 and NS1

The sections [ns0_config] and [ns1_config] now allow to configure additional memory pool resources. This was hard coded in the server provider in previous versions.

By default, the server will only allocate as much as is necessary to load the ns0.bin file for NS0. NS1 is configured to be able to create diagnostic objects. If you need to create additional nodes or references in these namespaces at runtime use these settings to adjust the memory pools to your needs.

PubSub Settings

To configure the new (optional) pubsub functionality another new section was introduced. At the moment this contains only the filename of the pubsub configuration file, which contains all publisher ans subscriber settings. This configuration can be changed online using UaExpert. This functionality also require UA FileType support.

[pubsub]
# filename of pubsub configuration
config_filename = "pubsubconfig.uabinary"

Migration from 1.3.x to 1.4.0

The 1.4.0 required to introduce some breaking changes that can be easily fixed by following these instructions.

AppConfig Changes

Applications that use hardcoded appconfig structures need to change the following settings. If you are using configuration files skip this section and read the next section about settings files.

Certificate Configuration

To make client security configuration possible independent of server endpoints the certificate configuration has been moved from the server's endpoint settings into the separate certificate_config structure. Both client and server configuration refer to this certificate configuration by using a certificate index.

To fix this, move existing certificate configurations from g_appconfig.endpoint to g_appconfig.certificates.

Certificate Key Usage

Certificate entries now have a new field key_usage which allow to set either server_auth, client_auth, or client_and_server_auth.

You need to add this new field to each configured certificate.

Maximum Queue Size for Event Monitored Items

Monitored items which are monitoring objects for alarms & conditions typically use a much larger queue size then for monitoring data. For this reason a separate configuration option was necessary to allow a different maximum queue size for event monitoring items.

To fix this add the new setting g_appconfig.subscription.max_monitoreditem_event_queue_size.

Method Calltable Size

A new mechanism for registering method callbacks was introduced, which allows a better way of finding method callbacks, based on ObjectId and MethodId combinations. This mechanism allows registering methods simply on ObjectTypes and when calling methods on instances of this type, the according method is still found by following the MethodDelarationId. Still it is possible to override the method callbacks for certain instances if necessary. Inheritance is also supported by this new mechanism.

The method registration table requires the new setting g_appconfig.server.num_methods, which is the maximum number of callbacks that can be registered using uaserver_call_table_register.

See Lesson 3: Creating Methods for more information on registering methods at the method call table.

Settings File Changes

Applications that load the configuration from a settings file need to update their configurations files.

Certificate Configuration

To make client security configuration possible independent from server endpoints the certificate configuration has been moved from the server's endpoint settings into the separate [certificates] section. Both client and server configuration refer to this certificate configuration by using a certificate index.

To fix this, move existing certificate entries from the [endpoint] section to a new [certificates] section.

Certificate Key Usage

Certificate entries now have a new field key_usage which allow to set either server_auth, client_auth, or client_and_server_auth. If this field is missing it will default to client_and_server_auth.

Example:

[certificates]
certificates/size = 1
certificates/0/store = 0
certificates/0/certificate = store://
certificates/0/key = store://
certificates/0/create = true
certificates/0/days_valid = 365
certificates/0/algorithm = sha256
certificates/0/key_length = 4096
certificates/0/key_usage = "server_auth"
certificates/0/issuer_index = 0

Maximum Queue Size for Event Monitored Items

Monitored items which are monitoring objects for alarms & conditions typically use a much larger queue size then for monitoring data. For this reason a separate configuration option was necessary to allow a different maximum queue size for event monitoring items.

To fix this, add the new setting max_monitoreditem_event_queue_size to the [subscription] section.

Example:

[subscription]
...
# Maximum queue size of events for one monitoreditem
max_monitoreditem_event_queue_size = 50
...

Method Calltable Size

A new mechanism for registering method callbacks was introduced, which allows a better way of finding method callbacks, based on ObjectId and MethodId combinations. This mechanism allows to register methods simply on ObjectTypes and when calling methods on instances of this type, the according method is still found by following the MethodDelarationId. Still, it is possible to override the method callbacks for certain instances if necessary. Inheritance is also supported by this new mechanism.

The method registration table requires the new setting g_appconfig.server.num_methods, which is the maximum number of callbacks that can be registered using uaserver_call_table_register.

To fix this, add the new setting num_methods to the [server] section.

Example:

[server]
...
# Maximum number of methods that can be registerd at the call table */
num_methods = 20
...

See Lesson 3: Creating Methods for more information on registering methods at the method call table.

New SetMonitoringMode Callback

This is only relevant when you have implemented your own data sampling at provider interface level and don't use the default provider implementation.

The provider interface contained three callbacks for managing monitored items, that should be sampled at the underlying data source: add_item, remove_item, and modify_item. A new callback set_item_mode must now be implemented, which allows to disable sampling without removing the items. This callback is called when a UA client changes the ua_monitoringmode.

If you override the default implementation of the three existing callbacks, you now also need to implement the new set_item_mode callback. The SDK will detect inconsistent configurations and will stop the server to avoid crashes.

Users of the default provider implementation don't need any changes, as the default provider implementation has been updated accordingly.

New Default Groups

The example groups configuration file, that is used by our example servers has been updated and now contains new default groups as defined in the OPC specification.

  • Observer
  • Operator
  • Engineer
  • Supervisor
  • ConfigureAdmin
  • SecurityAdmin

When building the server with UASERVER_SUPPORT_DIAGNOSTICS=ON, which will enable server diagnostic via the OPC UA information model, the security relevant nodes will get assigned to the SecurityAdmin group. This means only users of this group will be able to read this information.

You need to ensure that this group exists in your groups configuration as well, if using user authorization. The group is found by its name so this works also with custom authorization backends as long as this group does exist.