1 Scope

This part specifies how OPC Unified Architecture (OPC UA) Clients and Servers interact with DiscoveryServers when used in different scenarios. It specifies the requirements for the LocalDiscoveryServer, LocalDiscoveryServer-ME and GlobalDiscoveryServer. It also defines information models for Certificate management, KeyCredential management and AuthorizationServices.

2 Normative references

The following documents, in whole or in part, are normatively referenced in this document and are indispensable for its application. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments and errata) applies.

3 Terms, definitions, and conventions

3.1 Terms and definitions

For the purposes of this document the following terms and definitions as well as the terms and definitions given in OPC 10000-1, OPC 10000-2, OPC 10000-3, OPC 10000-4, OPC 10000-6 and OPC 10000-9 apply.

3.1.1 CertificateManager

a software application that manages the Certificates used by Applications in an administrative domain.

3.1.2 CertificateGroup

a context used to manage the TrustList and Certificate(s) associated with Applications or Users.

3.1.3 CertificateRequest

a PKCS #10 encoded structure used to request a new Certificate from a Certificate Authority.

3.1.4 ClientUrl

a physical address available on a network that allows Servers to initiate a reverse connection.

3.1.5 DirectoryService

a software application, or a set of applications, that stores and organizes information about resources such as computers or services.

3.1.6 DiscoveryServer

an application that maintains a list of OPC UA Applications that are available on the network and provides mechanisms for other OPC UA Applications to obtain this list.

3.1.7 DiscoveryUrl

a URL for a network Endpoint that provides the information required to connect to a Client or Server.

3.1.8 GlobalDiscoveryServer (GDS)

a Server that provides numerous services related to discovery and security management.

3.1.9 GlobalService

a Server that provides centrally managed Capabilities needed for a system.

3.1.10 IPAddress

a unique number assigned to a network interface that allows Internet Protocol (IP) requests to be routed to that interface.

3.1.11 KeyCredential

a unique identifier and a secret used to access an AuthorizationService or a Broker.

3.1.12 KeyCredentialService

a software application that provides KeyCredentials needed to access an AuthorizationService or a Broker.

3.1.13 LocalDiscoveryServer (LDS)

a DiscoveryServer that maintains a list of all Servers that have registered with it.

3.1.14 LocalDiscoveryServer-ME (LDS-ME)

a LocalDiscoveryServer that includes the MulticastExtension.

3.1.15 MulticastExtension

an extension to a LocalDiscoveryServer that adds support for the mDNS protocol.

3.1.16 MulticastSubnet

a network that allows multicast packets to be sent to all nodes connected to the network.

3.1.17 NonUaApplication

an application which is not an OPC UA Application.

3.1.18 Privilege

a named set of rights which cannot be expressed as Permissions granted on Nodes.

3.1.19 PullManagement

a workflow where a Client manages its configuration by using a GlobalService.

3.1.20 PushManagement

a workflow where a GlobalService manages a Server’s configuration.

3.1.21 ServerCapabilityIdentifier

a short identifier which uniquely identifies a set of discoverable Capabilities supported by an OPC UA Application.

3.2 Abbreviations and symbols

4 The Discovery Process

4.1 Overview

The discovery process allows OPC UA Applications to find other OPC UA Applications on the network and then discover how to connect to them. Note that this discussion builds on the discovery related concepts defined in OPC 10000-4. Discoverable applications are generally Servers; however, some Clients will support reverse connections as described in OPC 10000-6 which allows Servers to be able to discover them. OPC UA Applications can exist on hosts with a LocalDiscoveryServer (see 4.2.2) or on hosts with a dedicated Server (see 4.2.3).

Clients and Servers can be on the same host, on different hosts in the same subnet, or even on completely different locations in an administrative domain. The following clauses describe the different configurations and how discovery can be accomplished.

The mechanisms for Clients to discover Servers are specified in 4.3.

The mechanisms for Servers to make themselves discoverable are specified in 4.2.

The Discovery Services are specified in OPC 10000-4. They are implemented by individual Servers and by dedicated DiscoveryServers. The following dedicated DiscoveryServers provide a way for applications to discover registered OPC UA Application in different situations:

A LocalDiscoveryServer (LDS) maintains discovery information for all applications that have registered with it, usually all applications available on the host that it runs on.

A LocalDiscoveryServer with the MulticastExtension (LDS-ME) maintains discovery information for all applications that have been announced on the local MulticastSubnet.

A GlobalDiscoveryServer (GDS) maintains discovery information for applications available in an administrative domain.

LDS and LDS-ME are specified in Clause 5. The GDS is specified in Clause 6.

4.2 Registration and Announcement of Applications

4.2.1 Overview

The clause describes how an OPC UA Application registers itself so it can be discovered. Most Applications will want other applications to discover them. OPC UA Applications that do not wish to be discovered openly should not register with a DiscoveryServer. In this case such OPC UA Applications should only publish a DiscoveryUrl via some out-of-band mechanism to be discovered by specific applications.

4.2.2 Hosts with a LocalDiscoveryServer

Applications register themselves with the LDS on the same host if they wish to be discovered. The registration ensures that the applications are visible for local discovery (see 4.3.3) and MulticastSubnet discovery if the LDS is a LDS-ME (see 4.3.4).

The OPC UA Standard (OPC 10000-4) defines a RegisterServer2 Service which provides additional registration information. All Applications and LocalDiscoveryServer shall support the RegisterServer2 Service and, for backwards compatibility, the older RegisterServer Service. If an application encounters an older LDS that returns a Bad_ServiceUnsupported error when calling RegisterServer2 Service it shall try again with RegisterServer Service.

The RegisterServer2 Service allows the application to specify zero or more ServerCapability Identifiers. CapabilityIdentifiers are short, string identifiers of well-known OPC UA features. Applications can use these identifiers as a filter during discovery.

The set of known CapabilityIdentifiers is specified in Annex D and is limited to features which are considered to be important enough to report before an OPC UA Application makes a connection. For example, support for the GDS information model or the Alarms information model are Server Capabilities that have a ServerCapabilityIdentifier defined.

Applications that are not preconfigured with an LDS endpoint shall call the GetEndpoints Service and choose the most secure endpoint supported by the LDS and the OPC UA Application. It then calls RegisterServer2 or RegisterServer.

Registration with LDS or LDS-ME is illustrated in Figure 1.

See OPC 10000-4 for more information on the re-registration timer and the IsOnline flag.

4.2.3 Hosts without a LocalDiscoveryServer

Dedicated systems (usually embedded systems) with exactly one Server installed may not have a separate LDS. Such Servers shall become their own LDS or LDS-ME by implementing FindServers and GetEndpoints Services at the well-known address for an LDS. If implementing an LDS-ME, they should also announce themselves on the MulticastSubnet with a basic MulticastExtension. This requires a small subset of an mDNS Responder (see mDNS and Annex C) that announces the Server and responds to mDNS probes. In addition they shall implement additional OPC UA specific items described in Annex C. The Server may not provide the caching and address resolution implemented by a full mDNS Responder.

4.3 The Discovery Process for Clients to Find Servers

4.3.1 Overview

The discovery process allows Clients to find Servers on the network and then discover how to connect to them. Once a Client has this information it can save it and use it to connect directly to the Server again without going through the discovery process. Clients that cannot connect with the saved connection information should assume the Server configuration has changed and therefore repeat the discovery process.

A Client has several choices for finding Servers:

Out-of-band discovery (i.e. entry into a GUI) of a DiscoveryUrl for a Server;

Calling FindServers on the LDS installed on the Client host;

Calling FindServers on a remote LDS, where the HostName for the remote host is manually entered;

Calling FindServersOnNetwork (see OPC 10000-4) on the LDS-ME installed on Client host;

Supporting the LDS-ME functionality locally in the Client.

Searching for Servers known to a GlobalDiscoveryServer.

The DiscoveryUrl is what a Client uses to connect to a DiscoveryEndpoint (see 4.3.2).

Clients should be aware of rogue DiscoveryServers that might direct them to rogue Servers. That said, this problem is mitigated when a Client connects to a Server and verifies that it trusts the Server. In addition, the CreateSession Service returns parameters that allow a Client to verify that the previously acquired results from a LDS have not been altered. See OPC 10000-2 and OPC 10000-4 for a detailed discussion of these issues.

A similar potential for a rogue GDS exists if the Client has not been configured to trust the GDS Certificate or if the Client does not use security when connecting to the GDS. Note that a Client that uses security but automatically trusts a GDS Certificate is not protected from a rogue GDS even though the connection itself is secure. This problem is also mitigated by verifying trust whenever a Client connects to a Server discovered via the GDS.

4.3.2 Simple Discovery with a DiscoveryUrl

Every Server has one or more DiscoveryUrls that allow access to its Endpoints. Once a Client obtains (e.g. via manual entry into a form) the DiscoveryUrl for the Server, it reads the EndpointDescriptions using the GetEndpoints Service defined in OPC 10000-4.

The discovery process for this scenario is illustrated in Figure 2.

4.3.3 Local Discovery

In many cases Clients do not know which Servers exist but possibly know which hosts might have Servers on them. In this situation the Client will look for the LocalDiscoveryServer on a host by constructing a DiscoveryUrl using the well-known addresses defined in OPC 10000-6.

If a Client finds a LocalDiscoveryServer then it will call the FindServers Service on the LDS to obtain a list of Servers and their DiscoveryUrls. The Client would then call the GetEndpoints service for one of the Servers returned. The discovery process for this scenario is illustrated in Figure 3.

4.3.4 MulticastSubnet Discovery

In some situations, Clients will not know which hosts have Servers. In these situations, the Client will look for a LocalDiscoveryServer with the MulticastExtension on its local host and requests a list of DiscoveryUrls for Servers and DiscoveryServers available on the MulticastSubnet.

The discovery process for this scenario is illustrated in Figure 4.

In this scenario the Server uses the RegisterServer2 Service to tell a LocalDiscoveryServer to announce the Server on the MulticastSubnet. The Client will receive the DiscoveryUrl and CapabilityIdentifiers for the Server when it calls FindServersOnNetwork and then connects directly to the Server. When a Client calls FindServers it only receives the Servers running on the same host as the LDS.

Clients running on embedded systems may not have a LDS-ME available on the system, These Clients can support an mDNS Responder which understands how OPC UA concepts are mapped to mDNS messages and maintains the same table of Servers as maintained by the LDS-ME. This mapping is described in Annex C.

4.3.5 Global Discovery

A GDS is an OPC UA Server which allows Clients to search for Servers within the administrative domain of the GDS. It provides Methods that allow applications to search for other applications (see 6). To access the GDS, the Client uses the Call service to invoke the QueryApplications Method (see 6.5.11) to retrieve a list of Servers that meet the filter criteria provided. The QueryApplications Method is similar to the FindServers service except that it provides more advanced search and filter criteria. The discovery process is illustrated in Figure 5.

The GDS may be coupled with any of the previous network architectures. For each MulticastSubnet, one or more LDSs may be registered with a GDS.

The Client can also be configured with the URL of the GDS using an out of band mechanism.

The complete discovery process is shown in Figure 6.

4.3.6 Combined Discovery Process for Clients

The use cases in the preceding clauses imply a number of choices that should be made by Clients when a Client connects to a Server. These choices are combined together in Figure 6.

FindServersOnNetwork can be called on the local LDS, however, it can also be called on a remote LDS which is part of a different MulticastSubnet.

An out-of-band mechanism is a way to find a URL or a HostName that is not described by this standard. For example, a user could manually enter a URL or use system specific APIs to browse the network neighbourhood.

A Client that goes through the discovery process can save the URL that was discovered. If the Client restarts later it can use that URL and bypass the discovery process. If reconnection fails the Client will have to go through the process again.

4.4 The Discovery Process for Reverse Connections

4.4.1 Overview

The discovery process for reverse connect does not serve the same purpose as the discovery process for normal connections because reverse connections require the Server to be configured to automatically attempt to connect to the Client and the Client to be configured so it knows what to do with the Server when it receives the connection. The limited mechanisms discussed here may help SecurityAdmins with the configuration of Servers.

A SecurityAdmin tasked with configuring Servers determines the ClientUrls for Clients that support reverse connect.

The following choices are available:

Out-of-band discovery (i.e. entry into a GUI) of a ClientUrl for a Client;

Searching for Clients known to a GlobalDiscoveryServer.

The mechanisms based on an LDS are not available since Clients do not register with the LDS.

4.4.2 Out-of-band Discovery

Every Client that supports reverse connect has one or more ClientUrls that allow Servers to connect. Once the SecurityAdmin acquires the ClientUrl via an out-of-band mechanism, it can configure the Server to use it.

4.4.3 Global Discovery for Reverse Connections

A GDS is a Server which allows other SecurityAdmins to search for Clients that support reverse connect within the administrative domain of the GDS. The SecurityAdmin uses the Call service to invoke the QueryApplications Method (see 6.5.11) with “RCP” as a ServerCapabilityFilter to get a list of Clients that support reverse connect from the GDS.

The discovery process is illustrated in Figure 5.

The ClientUrls are returned in the DiscoveryUrls parameter of the ApplicationDescription record and have the ‘rcp+’ prefix. DiscoveryUrls without the prefix are used for forward connections. Once the SecurityAdmin has a ClientUrl it can configure the Server to use it.

5 Local Discovery Server

5.1 Overview

Each host that could have multiple discoverable applications installed should have a standalone LocalDiscoveryServer installed. The LocalDiscoveryServer shall expose one or more Endpoints which support the FindServers and GetEndpoints services defined in OPC 10000-4. In addition, the LocalDiscoveryServer shall provide at least one Endpoint which implements the RegisterServer service for these applications.

The FindServers Service returns the information for the LocalDiscoveryServer and all Servers that are known to the LDS. The GetEndpoints Service returns the EndpointDescriptions for the LocalDiscoveryServer that allow Servers to call the RegisterServer or RegisterServer2 Services. The LocalDiscoveryServer does not support Sessions so information needed for establishing Sessions, such as supported UserTokenPolicies, is not provided.

In systems (usually embedded systems) with exactly one Server installed this Server may also be the LDS (see 4.2.3).

An LDS-ME will announce all applications that it knows about on the local MulticastSubnet. In order to support this, a LocalDiscoveryServer supports the RegisterServer2 Service defined in OPC 10000-4. For backward compatibility a LocalDiscoveryServer also supports the RegisterServer Service which is defined in OPC 10000-4.

Each host with OPC UA Applications (Clients and Servers) installed should have a LocalDiscoveryServer with a MulticastExtension.

The MulticastExtension incorporates the functionality of the mDNS Responder described in the Multicast DNS (mDNS) specification (see mDNS). In addition, the LocalDiscoveryServer that supports the MulticastExtension supports the FindServersOnNetwork Service described in OPC 10000-4.

5.2 Security Considerations for Multicast DNS

The Multicast DNS (mDNS) specification is used for various commercial and consumer applications. This provides a benefit in that implementations exist; however, system administrators could choose to disable Multicast DNS operations. For this reason, Applications shall not rely on Multicast DNS Capabilities.

Multicast DNS operations are insecure because of their nature; therefore, they should be disabled in environments where an attacker could cause problems by impersonating another host. This risk is minimized if OPC UA security is enabled and all Applications use Certificate TrustLists to control access.

5.3 Network Architectures

5.3.1 Overview

The discovery mechanisms defined in this standard are expected to be used in many different network architectures. The following three architectures are Illustrated:

Single MulticastSubnet;

Multiple MulticastSubnets;

No MulticastSubnet (or multiple MulticastSubnets with exactly one host each);

A MulticastSubnet is a network segment where all hosts on the segment can receive multicast packets from the other hosts on the segment. A physical LAN segment is typically a MulticastSubnet unless the administrator has specifically disabled multicast communication. In some cases multiple physical LAN segments can be connected as a single MulticastSubnet.

5.3.2 Single MulticastSubnet

The Single MulticastSubnet Architecture is shown in Figure 8.

In this architecture every host has an LDS-ME and uses mDNS to maintain a cache of the applications on the MulticastSubnet. A Client can call FindServersOnNetwork on any LDS-ME and receive the same set of applications. When a Client calls FindServers it only receives the applications running on the same host as the LDS.

5.3.3 Multiple MulticastSubnet

The Multiple MulticastSubnet Architecture is shown in Figure 9.

This architecture is the same as the previous architecture except in this architecture the mDNS messages do not pass through routers connecting the MulticastSubnets. This means that a Client calling FindServersOnNetwork will only receive a list of applications running on the MulticastSubnets that the LDS-ME is connected to.

A Client that wants to connect to a remote MulticastSubnet shall use out of band discovery (i.e. manual entry) of a HostName or DiscoveryUrl. Once a Client finds an LDS-ME on a remote MulticastSubnet it can use FindServersOnNetwork to discover all applications on that MulticastSubnet.

5.3.4 No MulticastSubnet

The No MulticastSubnet Architecture is shown in Figure 10.

In this architecture the mDNS is not used at all because the Administrator has disabled multicast at a network level or by turning off multicast Capabilities of each LDS-ME.

A Client that wants to discover applications uses an out of band mechanism to find the HostName and call FindServers on the LDS of that host. FindServersOnNetwork may also work but it will never return more than what FindServers returns. Clients could also use a GDS if one is available.

5.3.5 Domain Names and MulticastSubnets

The mDNS specification requires that fully qualified domain name be announced on the network. If a Server is not configured with a fully qualified domain name then mDNS requires that the ‘local’ top level domain be appended to the domain names. The ‘local’ top level domain indicates that the domain can only be considered to be unique within the subnet where the domain name was used. This means Clients should to be aware that URLs received from any LDS-ME other than the one on the Client’s computer could contain ‘local’ domains which are not reachable or will connect to a different computer with the same domain name that happens to be on the same subnet as the Client. It is recommended that Clients ignore all URLs with the ‘local’ top level domain unless they are returned from the LDS-ME running on the same computer.

System administrators can eliminate this problem by configuring a normal DNS with the fully qualified domain names for all computers that are accessed by Clients outside the MulticastSubnet.

Servers configured with fully qualified domain names should specify the fully qualified domain name in its ApplicationInstance Certificate. Servers shall not append the ‘local’ top level domain to any domains declared in their Certificate; an unqualified domain name is used if a more appropriate qualifier does not exist. Clients using a URL returned from an LDS-ME shall ignore the ‘local’ top level domain when checking the domain against the Server Certificate.

Note that domain name validation is a necessary but not sufficient check against rogue Servers or man-in-the-middle attacks when Server Certificates do not contain fully qualified domain names. The Certificate trust relationship established by administrators is the primary mechanism used to protect against these risks.

6 Global Discovery Server

6.1 Overview

The LocalDiscoveryServer is useful for networks where the host names can be discovered. However, this is typically not the case in large systems with multiple Servers on multiple subnets. For this reason, there is a need for an enterprise wide DiscoveryServer called a GlobalDiscoveryServer.

The GlobalDiscoveryServer (GDS) is an OPC UA Server which allows Clients to search for OPC UA Applications within the administrative domain. When compared to the LDS, the GDS provides an authoritative source for OPC UA Applications which have been verified by administrators and accessed via a secure communication channel.

The GDS provides Methods that allow administrators to register applications and allow applications to search for other applications.

Some GDS implementations may provide a front-end to an existing DirectoryService such as LDAP (see Annex E). By standardizing on an OPC UA based interface, Clients are not required to have knowledge of different DirectoryServices.

6.2 Roles and Privileges

GlobalDiscoveryServers restrict access to many of the features they provide. These restrictions are described either by referring to well-known Roles which a Session must have access to or by referring to Privileges which are assigned to Sessions using mechanisms other than the well-known Roles. The well-known Roles used in for a GDS are listed in Table 1.

The Privileges used in for a GDS are listed in Table 2.

6.3 Client connections to global services

A GlobalDiscoveryServer is a Server implementing different global services for discovery, Certificate management, user or PubSub key management, user authorization, software and device management.

The number of applications using the different services may be large and a GDS is most likely not able to handle connections from all Clients at the same time. Therefore, a Client connected to a GDS should minimize the time it is connected to the GDS. The application shall disconnect as soon as it completes the sequence of actions needed to interact with the services. The applications shall not keep connections open between the execution of sequences.

If it runs out of connection resources, a GDS is allowed to close Sessions with Clients which have not be authenticated as one of the GDS administrative Roles. If the GDS has to close Sessions, it should first close Sessions without GDS management Privileges. Otherwise, it may close the Session that was inactive for the longest time.

It is also recommended to use a short maximum session timeout on the GDS.

Actions performed cyclically by applications during PullManagement shall start the second cycle with a random delay that is between one and at least ten percent of the cycle period.

6.4 Application Registration Workflow

The application to be registered or a configuration tool operating on the application’s behalf performs the initial application registration. This requires a user that has the DiscoveryAdmin Role or the ApplicationAdmin Privilege on the GDS.

The workflow for the application registration is shown in Figure 11.

The description of the OPC UA Application registration workflow steps is provided in Table 3.

6.5 Information Model

6.5.1 Overview

The GlobalDiscoveryServer Information Model used for discovery is shown in Figure 12. Most of the interactions between the GlobalDiscoveryServer and Application administrator or the Client will be via Methods defined on the Directory folder.

6.5.2 Directory

This Object is the root of the GlobalDiscoveryServer AddressSpace and it is the target of an Organizes reference from the Objects folder defined in OPC 10000-5. It organizes the information that can be accessed into subfolders. The implementation of a GDS can customize and organize the folders in any manner it desires. For example folders can exist for information models, or for optional services or for various locations in an administrative domain. It is defined in Table 4.

6.5.3 DirectoryType

DirectoryType is the ObjectType for the root of the GlobalDiscoveryServer AddressSpace. It organizes the information that can be accessed into subfolders It also provides methods that allow applications to register or find applications. It is defined in Table 5.

The Applications folder may contain Objects representing the Applications known to the GDS. These Objects may be organized into subfolders as determined by the GDS. Some characteristics for organizing applications are the networks, the physical location, or the supported profiles. The QueryApplications Method can be used to search for OPC UA Applications based on various criteria.

A GDS is not required to expose its Applications as browsable Objects in its AddressSpace, however, each application shall have a unique NodeId which can be passed to Methods used to administer the GDS.

The FindApplications Method returns the Applications associated with an ApplicationUri. It can be called by any Client.

The RegisterApplication Method is used to add a new application to the GDS. It requires administrative privileges.

The UpdateApplication Method is used to update an existing application in the GDS. It requires administrative privileges.

The UnregisterApplication Method is used to remove an application from the GDS. It requires administrative privileges.

The QueryApplications Method is used to find Client or Server applications that meet the criteria provided. This Method replaces the QueryServers Method.

The QueryServers Method is used to find Servers that meet the criteria specified. It does not require any permissions to call. This Method has been replaced by the QueryApplications Method

6.5.4 FindApplications

FindApplications is used to find the ApplicationId for an approved OPC UA Application (see 6.5.6). The returned applications array shall be of size 1 or 0.

If the returned array is null or zero length then the GDS does not have an entry for the ApplicationUri.

Signature

FindApplications(
	[in]  String ApplicationUri
	[out] ApplicationRecordDataType[] Applications
);

Method Result Codes (defined in Call Service)

Table 6 specifies the AddressSpace representation for the FindApplications Method.

6.5.5 ApplicationRecordDataType

This type defines a DataType which represents a record in the GDS.

If the ApplicationType is Client, and the Client supports reverse connect then the ServerCapabilities shall include RCP and all DiscoveryUrls shall begin with the rcp+ prefix which indicates that reverse connections are supported.

If the application does not support OPC UA then the ApplicationType is Client and the ServerCapabilities shall be NA.

If the ApplicationType is ClientAndServer the ServerCapabilities may include RCP and all DiscoveryUrls that support reverse connect have the rcp+ prefix. If the same URL supports normal connections and reverse connection then there shall be two elements in the DiscoveryUrls array with and without the rcp+ prefix.

Its representation in the AddressSpace is defined in Table 8.

6.5.6 RegisterApplication

The RegisterApplication Method is used to register a new applicationwith a GlobalDiscoveryServer.

This Method shall be called from an authenticated SecureChannel and from a Client that has access to the DiscoveryAdmin Role or the ApplicationAdmin Privilege (see 6.2).

Servers that support transparent redundancy shall register as a single application and pass the DiscoveryUrls for all available instances and/or network paths.

Servers that support non-transparent redundancy shall register as different applications. In addition, OPC 10000-4 requires the use of the NTRS ServerCapability defined in Annex D.

RegisterApplication shall not create duplicate records. If the ApplicationUri already exists the Method returns Bad_EntryExists.

If RegisterApplication succeeds the application is added to the list of applications that can be returned by QueryApplications and FindApplications.

If registration was successful and auditing is supported, the GDS shall generate the ApplicationRegistrationChanged AuditEventType (see 6.5.12).

Signature

RegisterApplication(
	[in]  ApplicationRecordDataType Application
	[out] NodeId ApplicationId
);

Method Result Codes (defined in Call Service)

Table 9 specifies the AddressSpace representation for the RegisterApplication Method.

6.5.7 UpdateApplication

The UpdateApplication Method is used to update an existing application in a GlobalDiscoveryServer.

This Method shall be called from an authenticated SecureChannel and from a Client that has access to the DiscoveryAdmin Role, the ApplicationSelfAdmin Privilege, or the ApplicationAdmin Privilege (see 6.2).

When updating an existing application the ApplicationUri cannot be changed. If it is changed the Method returns Bad_WriteNotSupported.

If the update was successful and auditing is supported, the GDS shall generate the ApplicationRegistrationChanged AuditEventType (see 6.5.12).

Signature

UpdateApplication(
	[in] ApplicationRecordDataType Application
);

Method Result Codes (defined in Call Service)

Table 10 specifies the AddressSpace representation for the UpdateApplication Method.

6.5.8 UnregisterApplication

The UnregisterApplication Method is used to remove an application from a GlobalDiscoveryServer.

This Method shall be called from an authenticated SecureChannel and from a Client that has access to the DiscoveryAdmin Role, the ApplicationSelfAdmin Privilege, or the ApplicationAdmin Privilege (see 6.2).

A Server application that is unregistered may be automatically added again if the GDS is configured to populate itself by calling FindServersOnNetwork and the Server application is still registered with its local LDS.

If an application has Certificates issued by the CertificateManager, these Certificates shall be revoked when this Method is called.

If un-registration was successful and auditing is supported, the GDS shall generate the ApplicationRegistrationChanged AuditEventType (see 6.5.12).

Signature

UnregisterApplication(
	[in] NodeId ApplicationId
);

Method Result Codes (defined in Call Service)

Table 11 specifies the AddressSpace representation for the UnregisterApplication Method.

6.5.9 GetApplication

The GetApplication Method is used to find an application known to the GDS.

Signature

GetApplication(
	[in]  NodeId ApplicationId
	[out] ApplicationRecordDataType Application
);

Method Result Codes (defined in Call Service)

Table 12 specifies the AddressSpace representation for the GetApplication Method.

6.5.10 QueryApplications

QueryApplications is used to find Clients that support reverse-connect or Servers that meet the specified filters.

QueryApplications returns ApplicationDescriptions instead of the ServerOnNetwork Structures returned by QueryServers. This is more useful to some Clients because it matches the return type of FindServers.

Any Client is able to call this Method, however, the set of results returned may be restricted based on the Client’s user credentials.

The applications returned shall pass all of the filters provided (i.e. the filters are combined in an AND operation). The Capabilities parameter is an array and an application will pass this filter if it supports all of the specified Capabilities.

This Method shall not return records with a ServerCapabilities that includes NA.

Each time the GDS creates or updates an application record it shall assign a monotonically increasing identifier to the record. This allows Clients to request records in batches by specifying the identifier for the last record received in the last call to QueryApplications. To support this the GDS shall return records in order starting from the lowest record identifier. The GDS shall also return the last time the counter was reset. If a Client detects that this time is more recent than the last time the Client called the Method it shall call the Method again with a StartingRecordId of 0.

The LastCounterResetTime parameter is used to indicate that the counters on records had to be reset for some reason such as a Server restart. The Client cannot use any NextRecordId received prior to this time to set the value for the StartingRecordId in a new call.

The return parameter is a list of ApplicationDescriptions. The mapping from a ApplicationRecord to an ApplicationDescriptions is shown in Table 13.

Signature

QueryApplications(
	[in]  UInt32 StartingRecordId
	[in]  UInt32 MaxRecordsToReturn
	[in]  String ApplicationName
	[in]  String ApplicationUri
	[in]  UInt32 ApplicationType
	[in]  String ProductUri
	[in]  String[] Capabilities
	[out] UtcTime LastCounterResetTime
	[out] UInt32 NextRecordId
	[out] ApplicationDescription[] Applications
);

Table 14 specifies the AddressSpace representation for the QueryApplications Method.

6.5.11 QueryServers (deprecated)

QueryServers is used to find Server applications that meet the specified filters.

Any Client is able to call this Method, however, the set of results returned may be restricted based on the Client’s user credentials.

The applications returned shall pass all of the filters provided (i.e. the filters are combined in an AND operation). The ServerCapabilities parameter is an array and an application will pass this filter if it supports all of the specified Capabilities.

This Method shall not return records with a ServerCapabilities that includes NA.

Each time the GDS creates or updates an application record it shall assign a monotonically increasing identifier to the record. This allows Clients to request records in batches by specifying the identifier for the last record received in the last call to QueryServers. To support this the GDS shall return records in order starting from the lowest record identifier. The GDS shall also return the last time the counter was reset. If a Client detects that this time is more recent than the last time the Client called the Method it shall call the Method again with a StartingRecordId of 0.

The LastCounterResetTime parameter is used to indicate that the counters on records had to be reset for some reason such as a Server restart. The Client cannot use any recordId received prior to this time to set the value for the StartingRecordId in a new call.

The return parameter is a list of ServerOnNetwork Structures. The mapping from a ApplicationRecordDataType to an ServerOnNetwork is shown in Table 15.

Signature

QueryServers(
	[in]  UInt32 StartingRecordId
	[in]  UInt32 MaxRecordsToReturn
	[in]  String ApplicationName
	[in]  String ApplicationUri
	[in]  String ProductUri
	[in]  String[] ServerCapabilities
	[out] UtcTime LastCounterResetTime
	[out] ServerOnNetwork[] Servers
);

Method Result Codes (defined in Call Service)

Table 16 specifies the AddressSpace representation for the QueryServers Method.

6.5.12 ApplicationRegistrationChangedAuditEventType

This event is raised when the RegisterApplication, UpdateApplication or UnregisterApplication Methods are called.

Its representation in the AddressSpace is formally defined in Table 17.

This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantics are defined in OPC 10000-5.

7 Certificate Management

7.1 Overview

Certificate management functions comprise the management and distribution of certificates and TrustLists for OPC UA Applications. An application that provides the certificate management functions is called CertificateManager. GDS and CertificateManager will typically be combined in one application. The basic concepts regarding Certificate management are described in OPC 10000-2.

There are two primary models for Certificate management: PullManagement and PushManagement. In PullManagement, the application acts as a Client and uses the Methods on the CertificateManager to request and update Certificates and TrustLists. The application is responsible for ensuring the Certificates and TrustLists are kept up to date. In PushManagement the application acts as a Server and exposes Methods which the CertificateManager can call to update the Certificates and TrustLists as required.

The CertificateManager is intended to work in conjunction with different Certificate management services such as Active Directory. The CertificateManager provides a standard OPC UA based information model that all OPC UA Applications can support without needing to know the specifics of a particular Certificate management system.

The CertificateManager should support the following features:

Onboarding (first time setup for a device/application);

Renewal (renewing expired or compromised certificates);

TrustList Update (updating the TrustLists including the Revocation Lists);

Revocation (removing a device/application from the system).

Although it is generally assumed that Client applications will use the Pull model and Server applications will use the Push model, this is not required.

OPC 10000-21 defines the complete process to automatically authenticate and onboard new Devices that depends on the Devices having support built in by the Manufacturer. If this support is not present, Devices and OPC UA Applications shall be manually onboarded using the mechanisms defined in this document.

During manual onboarding, the CertificateManager shall be able to operate in a mode where any Client is allowed to connect securely with any valid Certificate and user credentials are used to determine the rights a Client has; this eliminates the need to configure TrustLists before connecting to the CertificateManager for application setup, application vendors may decide to build the interaction with the CertificateManager as a separate component, e.g. as part of an administration application with access to the OPC UA configuration of this application. This is transparent for the CertificateManager and will not be considered further in the rest of this chapter.

Clients shall only connect to a CertificateManager which the Client has been configured to trust. This may require an out of band configuration step which is completed prior to starting the manual onboarding process.

This standard does not define how to administer a CertificateManager but a CertificateManager shall provide an integrated system that includes both push and PullManagement.

7.2 Roles and Privileges

CertificateManagers restrict access to many of the features they provide. These restrictions are described either by referring to well-known Roles which a Session must have access to or by referring to Privileges which are assigned to Sessions using mechanisms other than the well-known Roles. The well-known Roles used for CertificateManagers are listed in Table 18.

The well-known Roles for Server managed by a CertificateManager are listed in Table 19.

The Privileges used in for CertificateManagers are listed in Table 20.

7.3 Pull Management

PullManagement is performed by using the CertificateManager information model, in particular the Methods defined in 7.9. The interactions between application and CertificateManager during PullManagement are illustrated in Figure 13.

The Application Administration component may be part of the Client or Server or a standalone utility that understands how the application persists its configuration information in its Configuration Database.

A similar process is used to renew certificates or to periodically update TrustList.

Security in PullManagement requires an encrypted channel and authorized credentials. These credentials may be user credentials for a CertificateAuthorityAdmin or application credentials determined by the Certificate used to create the SecureChannel. Examples of the application credentials include Certificates previously issued to the application being accessed, Device Certificates issued by the Registrar defined in OPC 10000-21 or Certificates issued to an application with access to the ApplicationAdmin Privilege (see 6.2).

The CertificateManager shall ensure that any application with a Certificate issued by the CertificateManager may connect securely to the CertificateManager using that Certificate (i.e. all CAs and CRLs needed to verify a Certificate are added to the CertificateManager’s TrustList).

Before a Client provides any secrets associated with credentials to a CertificateManager it needs to know that it can trust the CertificateManager. This can be done by an administrator that adds the CertificateManager to the Client TrustList before the Client attempts to connect to the CertificateManager. If the Client finds a CertificateManager on a network via mDNS or other insecure mechanism it could trust the CertificateManager if it has some independently acquired information that allows it to trust the CertificateManager. For example, the DNS address of the CertificateManager could be provided by a trusted authority and this address appears in the Certificate of the CertificateManager being used and the address was used to connect.

Once the Client finds a CertificateManager that it can trust, it needs to provide credentials that allows the CertificateManager to know that it can issue Certificates. The Certificate used by the Client can be the credential if there is an out of band process to provide the Certificate to the CertificateManager. The CertificateManager could provide a one-time password to the Client via email or other mechanisms.

The CertificateManager can only issue Certificates to authenticated Clients. There are a number of ways to authenticate Clients:

The CertificateManager is pre-configured with information about the Client Certificate that allows the CertificateManager to know that the Client can request Certificates even if anonymous user credentials are used. The Client may be a DCA authenticated by a Registrar (see OPC 10000-21), a Client with a previously issued Certificate, or a Client authorized to create Certificates on behalf of other applications.

The CertificateManager may have a manual process where an administrator reviews each request before issuing a Certificate.

The Client provides user credentials. A Client shall not provide a secret (e.g. a password) to an untrusted CertificateManager.

7.4 Push Management

PushManagement is targeted at applications that can be configured with a CertificateManager or agent acting as a Client. The Methods defined in 7.10 are used to create a CertificateRequest which can be passed onto the registration authority managed by the CertificateManager. After the registration authority signs the Certificate, the new Certificate is pushed to the Server with the UpdateCertificate Method.

There are two use cases for PushManagement:

Management of a Server via the ServerConfiguration Object (see 7.10.4);

Management of a Server, Client or non-OPC UA application via an ApplicationConfiguration Object (see 7.10.16).

The second use case requires a Server acting as a proxy for the application being managed.

The interactions between an application and CertificateManager during PushManagement are illustrated in Figure 14.

The Administration Component may be part of the CertificateManager or a standalone utility that uses OPC UA to communicate with the CertificateManager (see 7.3 for a more complete description of the interactions required for this use case). The Configuration Database is used by the Server to persist its configuration information. The RegisterApplication Method (or internal equivalent) is assumed to have been called before the sequence in the diagram starts.

A similar process is used to renew certificates or to periodically update TrustList. In Figure 14 the TrustList update is shown to happen first. This is necessary to ensure any CRLs are provided to the Server before the new Certificate is updated. The TrustList update may be skipped If the current TrustList allows the Server to validate the new Certificate.

Security when using the PushManagement model requires an encrypted channel and a Client with access to the SecurityAdmin Role. For example, SecurityAdmin Role could be mapped to user credentials for an administrator or to a ApplicationInstance Certificate issued to a configuration tool. OPC 10000-21 defines a mechanism to install administrative Client Certificates into the Server TrustList.

7.5 Application Setup

Application Setup is the initial installation of an OPC UA Server or Client into a system in which a GDS is available and managing Certificates. Applications using a Client interface can be setup using the PullManagement. Applications using a Server interface can be setup using the PushManagement.

PushManagement and PullManagement are also integrated into OPC 10000-21 which specifies how new Devices can be authenticated when they are added to the network. Once a Device is authenticated the Device is trusted and can use the push or PullManagement without additional administrator credentials.

OPC UA Servers that do not support OPC 10000-21 typically auto-generate a self-signed Certificate when they first start. They may also have a pre-configured TrustList with Applications that are allowed to setup the Server. For example, a machine vendor may use a CA that is used to issue Certificates to Applications used by their field technicians.

For embedded devices, the Server should allow any Client that provides the proper SecurityAdmin credentials to create the secure connection needed for setup using PushManagement. Once the Server has been given its initial TrustList the Server should then restrict access to those Clients with Certificates in the TrustList. A vendor specific process for setup is required if a device restricts the Clients allowed to connect securely.

See Annex G for more specific instructions on how to provision an application when OPC 10000-21 is not used.

7.6 Pull Management Workflow

In this workflow the application that gets Certificates from the CertificateManager is the Client that executes the workflow and the CertificateManager is the Server processing the request in the workflow.

The application is authenticated with the Certificate signed by the CertificateManager (or the Certificate assigned during registration). The UserTokenType is always Anonymous using the ApplicationSelfAdmin Privilege.

The workflow for PullManagement is shown in Figure 15 and the steps are described in Table 21. The two options for the key pair creation are described in Figure 16. The boxes with blue text indicate Method calls.

The steps of the PullManagement workflow are described in detail in Table 21.

7.7 Push Management Workflows

7.7.1 Overview

There are a few common workflows that a CertificateManager, as a Client, executes against the ServerConfiguration Object or a BaseApplicationConfiguration Object in the ManagedApplications Folder.

7.7.2 Update Certificates Workflow

This workflow is started if the CertificateManager determines that an update to one or more Certificates used for an existing Endpoints is required. It is shown in Figure 17. The boxes with blue text indicate Method calls.

The steps of the workflow are described in Table 22.

7.7.3 Update TrustList Workflow

The Update TrustList workflow starts if the CertificateManager determines that an update to an existing TrustList is required. This update can be part of another workflow or a standalone workflow. It is shown in Figure 18. The boxes with blue text indicate Method calls.

The steps of the PushManagement Update TrustList workflow are described in Table 23.

7.7.4 Update Single Certificate Workflow

The Update Single Certificate workflow is part of the Update Certificates workflow in 7.7.2. It starts when the CertificateManager determines that an update to a Certificate assigned to a CertificateGroup is required. It is shown in Figure 19. The boxes with blue text indicate Method calls.

The steps of the workflow are described in Table 24.

7.7.5 Create Endpoint Workflow

The Create Endpoint workflow starts if the CertificateManager determines it needs to create a new Endpoint. This update is always part of another workflow. It is shown in Figure 20. The boxes with blue text indicate Method calls.

The steps of the workflow are described in Table 25.

7.7.6 Update Configuration Workflow

The Update Configuration workflow is always part of another workflow. It is shown in Figure 21. The boxes with blue text indicate Method calls.

The steps of the workflow are described in Table 26.

7.8 Common Information Model

7.8.1 Overview

The common information model defines types that are used in both the Push and the Pull Model.

7.8.2 TrustLists

7.8.2.1 TrustListType

This type defines a FileType that can be used to access a TrustList.

The CertificateManager uses this type to implement the Pull Model.

Servers use this type when implementing the Push Model.

An instance of a TrustListType shall restrict access to appropriate users or applications. This may be a CertificateManager administrative user that can change the contents of a TrustList, it may be an administrative user that is reading a TrustList to configure applications or it may be an application that can only access the TrustList assigned to it.

The TrustList file is a UA Binary encoded stream containing an instance of TrustListDataType (see 7.8.2.8). The encoded structure is not wrapped in an ExtensionObject.

The Size Property inherited from FileType has no meaning for TrustList and returns the error code defined in OPC 10000-20.

When a Client opens the file for writing the Server will not actually update the TrustList until the CloseAndUpdate Method is called. Simply calling Close will discard the updates. The bit Masks in TrustListDataType structure allow the Client to only update part of the TrustList.

Its representation in the AddressSpace is formally defined in Table 27.

The LastUpdateTime indicates when the TrustList was last updated. The LastUpdateTime shall reflect changes made using the TrustList Object Methods. A TrustList Object in a CertificateManager shall also reflect changes made in other ways.

The LastUpdateTime of a TrustList Object in a CertificateManager allows Clients using the PullManagement to know whether the TrustList has changed since the last time they accessed it. The LastUpdateTime of a TrustList Object in the ServerConfiguration allows administration Clients to verify the date of TrustLists. If a Server is not able to determine the LastUpdateTime after an event such as a restart, then the LastUpdateTime shall be DateTime.MinValue.

The UpdateFrequency Property specifies how often the TrustList shall be checked for changes. When the CertificateManager specifies this value, all Clients that read a copy of the TrustList should connect to the CertificateManager and check for updates to the TrustList within 2 times the UpdateFrequency. The choice of UpdateFrequency depends on how quickly system changes are required to be detected and the performance constraints of the system. UpdateFrequencies that are too long create security risks because of out of date CRLs. UpdateFrequencies that are too short negatively impact system performance. If the TrustList Object is contained within a ServerConfiguration Object then this Property is not present.

When a CertificateManager is updating a TrustList as part of PushManagement, it sets this UpdateFrequency based on when the Server should raise Alarms if the CRLs are about to expire (see 7.8.3.1). If the Server supports this Property, it shall make it writeable to Clients authorized to update the TrustList.

The ActivityTimeout Property specifies the maximum elapsed time between the calls to Methods on the TrustList Object after Open or OpenWithMasks is called. If this time elapses the TrustList is automatically closed by the Server and any changes are discarded. The default value is 60 000 milliseconds (1 minute).

The DefaultValidationOptions Property specifies the default options to use when validating Certificates with the TrustList. The TrustListValidationOptions DataType is defined in 7.8.2.10. This Property may be updated by Clients with access to the SecurityAdmin Role.

If auditing is supported, the CertificateManager shall generate the TrustListUpdatedAuditEventType (see 7.8.2.13) when the TrustList is updated via the CloseAndUpdate (see 7.8.2.5), AddCertificate (see 7.8.2.6), RemoveCertificate (see 7.8.2.7) or ApplyChanges (see 7.10.9) Methods. The Event is only raised once after the asynchronous update process completes.

7.8.2.2 Open

The Open Method is inherited from FileType which is defined in OPC 10000-5.

The Open Method shall not support modes other than Read (0x01) and the Write + EraseExisting (0x06). If other modes are requested the return code is Bad_NotSupported.

If a transaction is in progress (see 7.10.9) on another Session then the Server shall return Bad_TransactionPending if Open is called with the Write Mode bit set. If the Server supports transactions, then the Server creates a new transaction or continues an existing transaction if Open is called with the Write Mode bit set.

If the SecureChannel is not authenticated the Server shall return Bad_SecurityModeInsufficient.

Method Result Codes

7.8.2.3 OpenWithMasks

The OpenWithMasks Method allows a Client to read only a portion of the TrustList.

This Method can only be used to read the TrustList.

After calling this Method, the Client calls Read one or more times to get the TrustList. If the Server is able to detect out of band changes to theTrustList before the Client calls the Close Method, then the next Read returns Bad_InvalidState. If the Server cannot detect out of band changes it shall ensure the Client receives a consistent snapshot.

For PullManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the CertificateAuthorityAdmin Role, the ApplicationSelfAdmin Privilege, or the ApplicationAdmin Privilege (see 7.2).

For PushManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).

Signature

OpenWithMasks(
	[in]  UInt32 Masks
	[out] UInt32 FileHandle
);

Method Result Codes (defined in Call Service)

Table 28 specifies the AddressSpace representation for the OpenWithMasks Method.

7.8.2.4 Read

The Read Method is inherited from FileType which is defined in OPC 10000-5.

If the Server is able to detect out of band changes to the TrustList before the Client calls the Close Method, then this Method returns Bad_InvalidState.

Additional Method Result Codes

7.8.2.5 CloseAndUpdate

The CloseAndUpdate Method closes the TrustList and applies the changes to the TrustList. It can only be called if the TrustList was opened for writing. If the Close Method is called any cached data is discarded and the TrustList is not changed.

If only part of the TrustList is being updated the Server creates a new TrustList that includes the existing TrustList plus any updates and validates the new TrustList.

The Purpose of the associated CertificateGroup determines the validation rules for Certificates placed in the TrustList. For ApplicationCertificateType, the Server shall verify that every Certificate in the new TrustList is valid using the validation process defined in OPC 10000-4. All suppressible errors shall be ignored; however, they may be logged as warnings. If the validation fails, the appropriate StatusCode defined in OPC 10000-4 shall be reported.

For Purposes other than ApplicationCertificateType, the validation rules are not defined by this specification.

If the Server does not support transactions, it applies the changes immediately and sets ApplyChangesRequired to FALSE. If the Server supports transactions, then the Server creates a new transaction or continues an existing transaction and sets ApplyChangesRequired to TRUE.

If a transaction exists on the current Session, the Server does not update the TrustList until ApplyChanges (see 7.10.9) is called. Any Clients that read the TrustList before ApplyChanges is called will receive the existing TrustList before the transaction started.

If any errors occur, the new TrustList shall be discarded.

When the TrustList changes the Server shall re-evaluate the Certificate associated with any open Sessions and SecureChannels. Sessions or SecureChannels with an untrusted or revoked Certificate shall be closed. This process may not complete before the Method returns and could take a significant amount of time on systems with limited resources.

The structure uploaded includes a mask (see 7.8.2.9) which specifies which fields are updated. If a bit is not set then the associated field is not changed.

For PullManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the CertificateAuthorityAdmin Role, the ApplicationSelfAdmin Privilege, or the ApplicationAdmin Privilege (see 7.2).

For PushManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).

Signature

CloseAndUpdate(
	[in]  UInt32 FileHandle
	[out] Boolean ApplyChangesRequired
);

Method Result Codes (defined in Call Service)

Table 29 specifies the AddressSpace representation for the CloseAndUpdate Method.

7.8.2.6 AddCertificate

The AddCertificate Method allows a Client to add a single Certificate to the TrustList.

The Purpose of the associated CertificateGroup determines the validation rules for the Certificate. For ApplicationCertificateType, the Server shall verify that the Certificate is valid using the validation process defined in OPC 10000-4. All suppressible errors shall be ignored; however, they may be logged as warnings. If the validation fails, the appropriate StatusCode defined in OPC 10000-4 shall be reported.

For Purposes other than ApplicationCertificateType, the validation rules are not defined by this specification.

This Method will return a validation error if the Certificate is issued by a CA and the Certificate for the issuer is not in the TrustList.

This Method cannot provide CRLs so issuer Certificates cannot be added with this Method. Instead, CA Certificates and their CRLs shall be managed with the Write Method on the containing TrustList Object.

This Method cannot be called if the containing TrustList Object is open.

This Method returns Bad_TransactionPending if a transaction is in progress (see 7.10.9).

This Method returns Bad_NotWritable if the TrustList Object is read only.

For PullManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the CertificateAuthorityAdmin Role (see 7.2).

For PushManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).

Signature

AddCertificate(
	[in] ByteString Certificate
	[in] Boolean IsTrustedCertificate
);

Method Result Codes (defined in Call Service)

Table 30 specifies the AddressSpace representation for the AddCertificate Method.

7.8.2.7 RemoveCertificate

The RemoveCertificate Method allows a Client to remove a single Certificate from the TrustList. It returns Bad_InvalidArgument if the Thumbprint does not match a Certificate in the TrustList.

If the Certificate is a CA Certificate that has CRLs then all CRLs for that CA are removed as well.

This Method returns Bad_CertificateChainIncomplete if the Certificate is a CA Certificate needed to validate another Certificate in the TrustList.

This Method returns Bad_TransactionPending if a transaction is in progress (see 7.10.9).

This Method returns Bad_NotWritable if the TrustList Object is read only. For PullManagement, this Method shall be called from an authenticated SecureChannel and from a Session that has access to the CertificateAuthorityAdmin Role (see 7.2).

For PushManagement, this Method shall be called from an authenticated SecureChannel and from a Session that has access to the SecurityAdmin Role (see 7.2).

Signature

RemoveCertificate(
	[in] String Thumbprint
	[in] Boolean IsTrustedCertificate
);

Method Result Codes (defined in Call Service)

Table 31 specifies the AddressSpace representation for the RemoveCertificate Method.

7.8.2.8 TrustListDataType

This type defines a DataType which stores the TrustList of a Server. Its values are defined in Table 32.

Its representation in the AddressSpace is defined in Table 33.

7.8.2.9 TrustListMasks

This is a DataType that defines the values used for the SpecifiedLists field in the TrustListDataType. Its values are defined in Table 34.

Its representation in the AddressSpace is defined in Table 35.

7.8.2.10 TrustListValidationOptions

This DataType defines flags for TrustListValidationOptions is formally defined in Table 36.

If CheckRevocationStatusOnline is set, the Certificate validation process defined in OPC 10000-4 will look for the authorityInformationAccess extension to find an OCSP (RFC 6960) endpoint which can be used to determine if the Certificate has been revoked.

If the OCSP endpoint is not reachable then the Certificate validation process looks for offline CRLs if the CheckRevocationStatusOffline bit is set. Otherwise, validation fails.

The revocation status flags only have meaning for issuer Certificates and are used when validating Certificates issued by that issuer.

The default value for this DataType only has the CheckRevocationStatusOffline bit set.

The TrustListValidationOptions representation in the AddressSpace is defined in Table 37.

7.8.2.11 TrustListOutOfDateAlarmType

This SystemOffNormalAlarmType is raised by the Server when the UpdateFrequency elapses and the TrustList has not been updated. This alarm automatically returns to normal when the TrustList is updated.

Its representation in the AddressSpace is defined in Table 38.

TrustListId Property specifies the NodeId of the out-of-date TrustList Object.

LastUpdateTime Property specifies when the TrustList was last updated.

UpdateFrequency Property specifies how frequently the TrustList is updated.

7.8.2.12 TrustListUpdateRequestedAuditEventType

This event is raised when a Method that changes the TrustList is called

It is raised when CloseAndUpdate, AddCertificate or RemoveCertificate Method on a TrustListType Object is called.

Its representation in the AddressSpace is formally defined in Table 39.

This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.

7.8.2.13 TrustListUpdatedAuditEventType

This event is raised when a TrustList is successfully changed.

This is the result of a CloseAndUpdate Method on a TrustListType Object or the result of a ApplyChanges Method on the ServerConfigurationType Object being called.

It shall also be raised when the AddCertificate or RemoveCertificate Method causes an update to the TrustList.

Its representation in the AddressSpace is formally defined inTable 40.

This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.

The TrustListId Property is the NodeId of the TrustList Object that was changed.

7.8.3 CertificateGroups

7.8.3.1 CertificateGroupType

This ObjectType is used for Objects which represent CertificateGroups in the AddressSpace. A CertificateGroup is a context that contains a TrustList and one or more CertificateTypes that can be assigned to an application. This ObjectType allows an application which has multiple TrustLists and/or ApplicationInstance Certificates to express them in its AddressSpace.

A CertificateManager can have many CertificateGroups which manage CertificateTypes and TrustLists for the applications in the system.

A Server has one or more CertificateGroups which specify the CertificateTypes and TrustLists managed by the Server. Typically, there is a mapping between a CertificateGroup in a Server and a CertificateGroup in the CertificateManager. The mechanisms for creating that mapping are outside the scope of this specification.

This type is defined in Table 41.

The TrustList Object is the TrustList associated with the CertificateGroup.

The CertificateTypes Property specifies the NodeIds of the CertificateTypes which may be assigned to applications which belong to the CertificateGroup. For example, a CertificateGroup with the NodeId of RsaMinApplicationCertificateType (see 7.8.4.8) and the NodeId RsaSha256ApplicationCertificate (see 7.8.4.9) specified allows an OPC UA Application to have one ApplicationInstance Certificates for each type. If this list is empty then the CertificateGroup does not allow Certificates to be assigned to Applications (i.e. a UserToken CertificateGroup only exists to allow the associated TrustList to be read or updated). All CertificateTypes for a given CertificateGroup shall be subtypes of a single common type (see Purpose in 7.8.3.4).

The Purpose Property specifies the allowed CertificateTypes. It shall be a direct subtype of CertificateType. See 7.8.3.4 for more details.

The CertificateExpired Alarm which is raised when a Certificate associated with the CertificateGroup is about to expire. If multiple Certificates are about to expire an Alarm for each Certificate is raised. The CertificateExpirationAlarmType is defined in OPC 10000-9.

The TrustListOutOfDate Alarm which is raised when a CRL or an IssuerCertificate is about to expire. The Alarm is raised no later than the period specified by the UpdateFrequency before the actual expiry time (see 7.8.2.1). The TrustListOutOfDateAlarmType is defined in 7.8.2.11.

The Alarm instances are optional and should not appear on TrustList instances even when the TrustList generates the Alarms. If a specific TrustList instance generates the CertificateExpired or TrustListOutOfDate Alarms, the corresponding HasCondition References shall be specified on the instance.

The GetRejectedList Method returns the list of Certificates that have been rejected by the Server when using the TrustList associated with the CertificateGroup. It can be used to track activity or allow administrators to move a rejected Certificate into the TrustList. This Method shall only be present on CertificateGroups which are part of the ServerConfiguration Object defined in 7.10.4.

7.8.3.2 GetRejectedList

GetRejectedList Method returns the list of Certificates that have been rejected by the Server.

No rules are defined for how the Server updates this list or how long a Certificate is kept in the list. It is recommended that every valid but untrusted Certificate be added to the rejected list as long as storage is available. Servers can delete entries from the list returned if the maximum message size is not large enough to allow the entire list to be returned.

Servers only add Certificates to this list that have no unsuppressed validation errors but are not trusted.

For PullManagement, this Method is not present on the CertificateGroup.

For PushManagement, this Method shall be called from an authenticated SecureChannel and from a Client that has access to the SecurityAdmin Role (see 7.2).

Signature

GetRejectedList(
	[out] ByteString[] Certificates
);

Method Result Codes (defined in Call Service)

Table 42 specifies the AddressSpace representation for the GetRejectedList Method.

7.8.3.3 CertificateGroupFolderType

This type is used for Folders which organize CertificateGroups in the AddressSpace. This type is defined in Table 43.

The DefaultApplicationGroup Object represents the default CertificateGroup for Applications. It is used to access the default application TrustList and to define the CertificateTypes allowed for the Certificates used by the application when communicating with peers:

For OPC UA Applications and CertificateManagers these CertificateTypes specify what is allowed for ApplicationInstance Certificates. They shall specify one or more subtypes of ApplicationCertificateType (see 7.8.4.2).

For NonUaApplications, these CertificateTypes specify what is allowed for the NonUaApplications Certificates. They shall specify one or more subtypes of CertificateType (see 7.8.4.1 and Table 99).

The DefaultHttpsGroup Object represents the default CertificateGroup for HTTPS communication. It is used to access the default HTTPS TrustList and to define the CertificateTypes allowed for the HTTPS Certificate. This Object shall specify the HttpsCertificateType NodeId (see 7.8.4.3) as a single entry in the CertificateTypes list or it shall specify one or more subtypes of HttpsCertificateType.

This DefaultUserTokenGroup Object represents the default CertificateGroup for validating user credentials. It is used to access the default user credential TrustList and to define the CertificateTypes allowed for user credentials Certificate. This Object shall leave CertificateTypes list empty.

Any additional CertificateGroups shall have a BrowseName where the Name is unique within the CertificateGroupFolder.

7.8.3.4 CertificateGroupDataType

This type is used to serialize a single CertificateGroup configuration. It is defined in Table 44.

This type is used as part of the ApplicationConfigurationDataType defined in 7.10.19 which allows multiple of CertificateGroups in a Server to be updated at once.

The Name of the record is the name portion of the BrowseName of the associated CertificateGroup Object in the AddressSpace.

It may not be possible to delete CertificateGroups such as DefaultApplicationGroup.

Note that when a new CertificateGroup is added, Clients need to browse the CertificateGroups folder to discover the NodeId assigned by the Server that is needed for Certificate management Methods.

Each element in the CertificateTypes list shall be unique and not abstract. The set of permitted CertificateTypes is defined by the ApplicationConfigurationFileType Object (see 7.10.20).

When the CertificateTypes list is updated, if an element already exists it is not changed, if an element does not exist a new CertificateType is added. If existing CertificateTypes are not in the list they are deleted if no Certificate is assigned. The update is rejected if a Certificate is assigned to a deleted CertificateType. The DeleteCertificate Method is used to remove Certificates.

The Purpose imposes restrictions on the allowed CertificateTypes. The update to the CertificateGroup is rejected if the Purpose is changed and the CertificateTypes are not consistent.

The set of permitted Purposes is defined by the ApplicationConfigurationFileType Object (see 7.10.20).

This type is defined in Table 44.

Its representation in the AddressSpace is defined in Table 45.

7.8.4 CertificateTypes

7.8.4.1 CertificateType

This type is an abstract base type for types that describe the purpose of a Certificate. This type is defined in Table 46.

7.8.4.2 ApplicationCertificateType

This type is an abstract base type for types that describe the purpose of an ApplicationInstanceCertificate. This type is defined in Table 47.

7.8.4.3 HttpsCertificateType

This type is used to describe Certificates that are intended for use as HTTPS Certificates. This type is defined in Table 48.

7.8.4.4 UserCertificateType

This type is used to describe Certificates that are intended to identify users. This type is defined in Table 48.

7.8.4.5 TlsCertificateType

This type is used to describe Certificates that are intended for use as TLS Certificates. This type is defined in Table 48.

7.8.4.6 TlsServerCertificateType

This type is used to describe a Certificates that is a TLS server Certificate. This type is defined in Table 51.

7.8.4.7 TlsClientCertificateType

This type is used to describe a Certificates that is a TLS client Certificate. This type is defined in Table 52.

7.8.4.8 RsaMinApplicationCertificateType

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an RSA key size of 1024 or 2048 bits. All Applications which support the Basic128Rsa15 and Basic256 profiles (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 53.

7.8.4.9 RsaSha256ApplicationCertificateType

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an RSA key size of 2048, 3072 or 4096 bits. All Applications which support the Basic256Sha256 profile (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 54.

7.8.4.10 EccApplicationCertificateType

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC Public Key. Applications which support the ECC profiles (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 55.

7.8.4.11 EccNistP256ApplicationCertificateType

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC nistP256 Public Key. Applications which support the ECC NIST P256 curve profiles (see OPC 10000-7) shall have a Certificate of this type or a Certificate of the EccNistP384ApplicationCertificateType defined in 7.8.4.12. This type is defined in Table 56.

7.8.4.12 EccNistP384ApplicationCertificateType

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC nistP384 Public Key. Applications which support the ECC NIST P384 curve profiles (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 57.

7.8.4.13 EccBrainpoolP256r1ApplicationCertificateType

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC brainpoolP256r1 Public Key. Applications which support the ECC brainpoolP256r1 curve profiles (see OPC 10000-7) shall have a Certificate of this type or a Certificate of the EccBrainpoolP384r1ApplicationCertificateType defined in 7.8.4.14. This type is defined in Table 58.

7.8.4.14 EccBrainpoolP384r1ApplicationCertificateType

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC brainpoolP384r1 Public Key. Applications which support the ECC brainpoolP384r1 curve profiles (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 59.

7.8.4.15 EccCurve25519ApplicationCertificateType

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC curve25519 Public Key. Applications which support the ECC curve25519 curve profiles (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 60.

7.8.4.16 EccCurve448ApplicationCertificateType

This type is used to describe Certificates intended for use as an ApplicationInstanceCertificate. They shall have an ECC curve448 Public Key. Applications which support the ECC curve448 curve profiles (see OPC 10000-7) shall have a Certificate of this type. This type is defined in Table 61.

7.8.5 ConfigurationFiles

7.8.5.1 ConfigurationFileType

This type defines a FileType that can be used to access the configuration associated with an Object.

The file is a stream containing an instance of UABinaryFileDataType serialized using one of the DataEncodings defined in OPC 10000-6. The DataEncoding used depends on the DataEncoding used for the messages sent to the Server. The body of the UABinaryFileDataType shall be an instance of the DataType specified by the SupportedDataType Property.

An instance of a ConfigurationFileType shall restrict access to appropriate users or applications. This should be ConfigureAdmin, SecurityAdmin or an equivalent administrative Role.

The Open Method shall not support modes other than Read (0x01) and Read + Write (0x03).

When a Client opens the file for reading and writing, the Client shall follow the following steps.

Read the existing configuration with the FileType Read Method.

Set the position to the beginning of the file with the FileType SetPosition Method.

Write the changes with the FileType Write Method.

Apply the changes with the CloseAndUpdate Method.

Servers shall automatically Close ConfigurationFiles if there are no calls to Methods on the ConfigurationFile Object within the time specified by the ActivityTimeout Property.

The Size Property inherited from FileType has no meaning for ConfigurationFile and returns the error code defined in OPC 10000-20.

When the CloseAndUpdate Method is called the Server will validate the configuration and then schedules the update. The Server returns initial results in the CloseAndUpdate response and may return additional errors after applying the changes in the response to ConfirmUpdate.

If CloseAndUpdate succeeds it returns a UpdateId that is used to confirm that the Client can connect after the update by calling the ConfirmUpdate Method. If it is not necessary to call ConfirmUpdate, the Server returns a empty value for the UpdateId.

The LastUpdateTime Property indicates when the configuration was last updated. The LastUpdateTime shall reflect changes made using the ConfigurationFile Object Methods. A ConfigurationFile Object should also reflect changes made in other ways.

The CurrentVersion Property is the value of the Version for the currently active configuration.

The ActivityTimeout Property specifies the maximum elapsed time between the calls to Methods on the ConfigurationFile Object after Open is called. If this time elapses the ConfigurationFile is automatically closed by the Server and any changes are discarded. The default value is 60 000 milliseconds (1 minute).

The SupportedDataType Property specifies the NodeId of the DataType that is put into the body of the UABinaryFileDataType during reading and writing. Any DataType shall be a subtype of BaseConfigurationDataType which is defined in 7.8.5.4.

The CloseAndUpdate Method validates the configuration and returns any validation errors.

The ConfirmUpdate Method is used to confirm that the Client can reconnect after the changes were applied.

7.8.5.2 CloseAndUpdate

The CloseAndUpdate Method closes the ConfigurationFile and applies the changes to the configuration. It can only be called if the ConfigurationFile was opened for writing. If the Close Method is called any cached data is discarded and the configuration is not changed.

The Client may partially update the configuration by specifying one or more targets. Each target refers to a component of the configuration that will be inserted, updated or deleted. The Server shall attempt to apply all changes. If any errors occur then all changes are rolled back.

Updating the configuration will often require the endpoints to be closed and all active Sessions be interrupted. When the new configuration is applied it is possible that a configuration error made the Server unreachable. The RestartDelayTime argument is used to delay the restart process to give the Client a chance to receive results from the CloseAndUpdate call. The RevertAfterTime argument is used to automatically restore the previous configuration if the Client is not able to reconnect and call the ConfirmUpdate Method.

If auditing is supported, the Server shall generate the ConfigurationUpdatedAuditEventType (see 7.8.5.8) when the configuration is updated. This may occur before CloseAndUpdate completes or when the update is scheduled to occur based on the RestartDelayTime.

Signature

CloseAndUpdate(
	[in]  0:UInt32 FileHandle
	[in]  0:VersionTime VersionToUpdate
	[in]  0:ConfigurationUpdateTargetType[] Targets
	[in]  0:Duration RevertAfterTime
	[in]  0:Duration RestartDelayTime
	[out] 0:StatusCode[] UpdateResults
	[out] 0:VersionTime NewVersion
	[out] 0:Guid UpdateId
);

Method Result Codes (defined in Call Service)

Operation Result Codes (Returned in UpdateResults)

Table 29 specifies the AddressSpace representation for the CloseAndUpdate Method.

7.8.5.3 ConfirmUpdate

The ConfirmUpdate Method allows a Client to confirm that it can connect after the configuration has been applied. The Client shall disconnect from the Server and reconnect before calling ConfirmUpdate. The RevertAfterTime parameter passed to the CloseAndUpdate Method specifies how long the Server shall wait for confirmation.

If the Server could not apply all changes then the return code is Bad_TransactionFailed and no changes were applied.

If the Method is called too soon the Server returns Bad_InvalidState.

The permissions needed to call this method shall be specified by the subtype and should require one of the administrator Roles.

Signature

ConfirmUpdate(
	[in]  0:Guid UpdateId
);

Method Result Codes (defined in Call Service)

Table 28 specifies the AddressSpace representation for the ConfirmUpdate Method.