This Service Setdefines Servicesused to discover the Endpointsimplemented by a Serverand to read the security configuration for those Endpoints. The Discovery Servicesare implemented by individual Serversand by dedicated Discovery Servers. OPC 10000-12describes how to use the Discovery Services with dedicatedDiscovery Servers.

Every Servershall have a DiscoveryEndpointthat Clientscan access without establishing a Session. This Endpointmay or may not be the same Session Endpointthat Clientsuse to establish a SecureChannel. Clientsread the security information necessary to establish a SecureChannelby calling the GetEndpoints Serviceon the DiscoveryEndpoint.

In addition, Serversmay register themselves with a well-known Discovery Serverusing the RegisterServerService. Clientscan later discover any registered Serversby calling the FindServers Serviceon the Discovery Server.

The discovery process using FindServersis illustrated in Figure 9. The establishment of a SecureChannel(with MessageSecurityMode NONE) for FindServersand GetEndpointsis omitted from the figure for clarity.

image012.png

Figure 9– Discovery process

The URL for a DiscoveryEndpoint shall provide all of the information that the Clientneeds to connect to theDiscoveryEndpoint.

Once a Clientretrieves the Endpoints, the Client can save this information and use it to connect directly to the Serveragain without going through the discovery process. If the Clientfinds that it cannot connect then the Serverconfiguration may have changed and the Clientneeds to go through the discovery process again.

DiscoveryEndpointsshall not require any message security, but it may require transport layer security. In production systems, Administrators may disable discovery for security reasons and Clientsshall rely on cached EndpointDescriptions. To provide support for systems with disabled Discovery Services Clientsshall allow Administratorsto manually update the EndpointDescriptionsused to connect to a Server. Serversshall allow Administratorsto disable the DiscoveryEndpoint.

A Clientshall be careful when using the information returned from a DiscoveryEndpointsince it has no security. A Clientdoes this by comparing the information returned from the DiscoveryEndpointto the information returned in the CreateSessionresponse. A Clientshall verify that:

  1. The ApplicationUrispecified in the Server Certificateis the same as the ApplicationUri provided in the EndpointDescription.
  2. The Server Certificatereturned in CreateSessionresponse is the same as the Certificateused to create the SecureChannel.
  3. The EndpointDescriptionsreturned from the DiscoveryEndpointare the same as the EndpointDescriptionsreturned in the CreateSessionresponse.

If the Clientdetects that one of the above requirements is not fulfilled, then the Clientshall close the SecureChanneland report an error.

A Clientshall verify the HostNamespecified in the Server Certificateis the same as the HostNamecontained in the endpointUrlprovided in the EndpointDescriptionreturned by CreateSession. If there is a difference then the Clientshall report the difference and may close the SecureChannel. Serversshall add all possible HostNameslike MyHost and MyHost.local into the Server Certificate. This includes IP addresses of the host or the HostNameexposed by a NAT router used to connect to the Server.

This Servicereturns the Serversknown to aServeror Discovery Server. The behaviour of Discovery Servers is described in detail in OPC 10000-12.

The Clientmay reduce the number of results returned by specifying filter criteria. A Discovery Serverreturns an empty list if no Serversmatch the criteria specified by the Client. The filter criteria supported by this Serviceare described in 5.4.2.2.

Every Servershall provide a DiscoveryEndpointthat supports this Service. The Servershall always return a record that describes itself, however in some cases more than one record may be returned. Gateway Serversshall return a record for each Serverthat they provide access to plus (optionally) a record that allows the Gateway Serverto be accessed as an ordinary OPC UA Server. Non-transparent redundant Serversshall provide a record for each Serverin the Redundant Server Set.

Every Servershall have a globally unique identifier called the ServerUri. This identifier should be a fully qualified domain name; however, it may be a GUID or similar construct that ensures global uniqueness. The ServerUrireturned by this Serviceshall be the same value that appears in index 0 of the ServerArrayproperty (see OPC 10000-5). The ServerUriis returned as the applicationUrifield in the ApplicationDescription(see 7.2)

Every Servershall also have a human readable identifier called the ServerNamewhich is not necessarily globally unique. This identifier may be available in multiple locales.

A Servermay have multiple HostNames. For this reason, the Clientshall pass the URL it used to connect to the Endpointto this Service. The implementation of this Serviceshall use this information to return responses that are accessible to the Clientvia the provided URL.

This Serviceshall not require message security but it may require transport layer security.

Some Serversmay be accessed via a Gateway Serverand shall have a value specified for gatewayServerUriin their ApplicationDescription(see 7.2). The discoveryUrlsprovided in ApplicationDescriptionshall belong to the Gateway Server.Some Discovery Serversmay return multiple records for the same Serverif that Servercan be accessed via multiple paths.

This Servicecan be used without security and it is therefore vulnerable to Denial of Service (DOS) attacks. A Servershould minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance. The Servershould also add a short delay before starting processing of a request during high traffic conditions.

Table 3defines the parameters for the Service.

Table 3– FindServers Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters. The authenticationTokenis always null. The authenticationTokenshall be ignored if it is provided.

The type RequestHeaderis defined in 7.33.

endpointUrl

String

The network address that the Clientused to access the DiscoveryEndpoint.

The Serveruses this information for diagnostics and to determine what URLs to return in the response.

The Servershould return a suitable default URL if it does not recognize the HostNamein the URL.

localeIds []

LocaleId

List of locales to use.

The Servershould return the applicationName in the ApplicationDescription defined in 7.2using one of locales specified. If the Serversupports more than one of the requested locales then the Servershall use the locale that appears first in this list. If the Serverdoes not support any of the requested locales it chooses an appropriate default locale.

The Serverchooses an appropriate default locale if this list is empty.

serverUris []

String

List of Serversto return.

All known Serversare returned if the list is empty.

A serverUri matches the applicationUrifrom the ApplicationDescriptiondefined in 7.2.

Response

responseHeader

ResponseHeader

Common response parameters.

The ResponseHeadertype is defined in 7.34.

servers []

ApplicationDescription

List of Serversthat meet criteria specified in the request.

This list is empty if no Serversmeet the criteria.

The ApplicationDescriptiontype is defined in 7.2.

Common StatusCodesare defined in Table 182.

This Servicereturns the Servers known to a Discovery Server. Unlike FindServers, this Serviceis only implemented by Discovery Servers.

The Clientmay reduce the number of results returned by specifying filter criteria. An empty list is returned if no Servermatches the criteria specified by the Client.

This Serviceshall not require message security but it may require transport layer security.

Each time the Discovery Servercreates or updates a record in its cache it shall assign a monotonically increasing identifier to the record. This allows Clientsto request records in batches by specifying the identifier for the last record received in the last call to FindServersOnNetwork. To support this the Discovery Servershall return records in numerical order starting from the lowest record identifier. The Discovery Servershall also return the last time the counter was reset for example due to a restart of the Discovery Server. If a Clientdetects that this time is more recent than the last time the Clientcalled the Serviceit shall call the Service again with a startingRecordId of 0.

This Servicecan be used without security and it is therefore vulnerable to denial of service (DOS) attacks. A Servershould minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance.

Table 4defines the parameters for the Service.

Table 4– FindServersOnNetwork Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters. The authenticationTokenis always null. The authenticationTokenshall be ignored if it is provided.

The type RequestHeaderis defined in 7.33.

startingRecordId

Counter

Only records with an identifier greater than this number will be returned.

Specify 0 to start with the first record in the cache.

maxRecordsToReturn

UInt32

The maximum number of records to return in the response.

0 indicates that there is no limit.

serverCapabilityFilter[]

String

List of Servercapability filters. The set of allowed Servercapabilities are defined in OPC 10000-12.

Only records with all of the specified Servercapabilities are returned.

The comparison is case insensitive.

If this list is empty then no filtering is performed.

Response

responseHeader

ResponseHeader

Common response parameters.

The ResponseHeadertype is defined in 7.34.

lastCounterResetTime

UtcTime

The last time the counters were reset.

servers[]

ServerOnNetwork

List of DNS service records that meet criteria specified in the request.

This list is empty if no Serversmeet the criteria.

recordId

UInt32

A unique identifier for the record.

This can be used to fetch the next batch of Serversin a subsequent call to FindServersOnNetwork.

serverName

String

The name of the Serverspecified in the mDNS announcement (see OPC 10000-12).

This may be the same as the ApplicationNamefor the Server.

discoveryUrl

String

The URL of the DiscoveryEndpoint.

serverCapabilities

String[]

The set of Servercapabilities supported by the Server.

The set of allowed Servercapabilities are defined in OPC 10000-12.

Common StatusCodesare defined in Table 182.

This Servicereturns the Endpointssupported by a Serverand all of the configuration information required to establish a SecureChannel and a Session.

This Serviceshall not require message security but it may require transport layer security.

A Clientmay reduce the number of results returned by specifying filter criteria based on LocaleIdsand Transport ProfileURIs. The Serverreturns an empty list if no Endpointsmatch the criteria specified by the Client. The filter criteria supported by this Serviceare described in 5.4.4.2.

A Servermay support multiple security configurations for the same Endpoint. In this situation, the Servershall return separate EndpointDescriptionrecords for each available configuration. Clientsshould treat each of these configurations as distinct Endpointseven if the physical URL happens to be the same.

The security configuration for an Endpointhas four components:

Server Application Instance Certificate

Message Security Mode

Security Policy

Supported User Identity Tokens

The ApplicationInstanceCertificateis used to secure the OpenSecureChannelrequest (see 5.5.2). The MessageSecurityModeand the SecurityPolicy tell the Clienthow to secure messages sent via the SecureChannel. The UserIdentityTokenstell the Clientwhich type of user credentials shall be passed to the Serverin the ActivateSessionrequest (see 5.6.3).

If the securityPolicyUriis Noneand none of the UserTokenPoliciesrequires encryption, the Clientshall ignore the ApplicationInstanceCertificate.

Each EndpointDescriptionalso specifies a URI for the Transport Profilethat the Endpointsupports. TheTransport Profilesspecify information such as message encoding format and protocol version and are defined in OPC 10000-7.

Messages are secured by applying standard cryptography algorithms to the messages before they are sent over the network. The exact set of algorithms used depends on the SecurityPolicyfor the Endpoint. OPC 10000-7defines Profilesfor common SecurityPolicies and assigns a unique URI to them. It is expected that applications have built in knowledge of the SecurityPolicies that they support, as a result, only the Profile URI for the SecurityPolicy is specified in the EndpointDescription. A Clientcannot connect to an Endpointthat does not support a SecurityPolicy that it recognizes.

An EndpointDescriptionmay specify that the message security mode is NONE. This configuration is not recommended unless the applications are communicating on a physically isolated network where the risk of intrusion is extremely small. If the message security is NONEthen it is possible for Clientsto deliberately or accidentally hijack Sessionscreated by other Clients.

A Servermay have multiple HostNames. For this reason, the Clientshall pass the URL it used to connect to the Endpointto this Service. The implementation of this Serviceshall use this information to return responses that are accessible to the Clientvia the provided URL.

This Servicecan be used without security and it is therefore vulnerable to Denial of Service (DOS) attacks. A Servershould minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance. The Servershould also add a short delay before starting processing of a request during high traffic conditions.

Some of the EndpointDescriptionsreturned in a response shall specify the Endpointinformation for a Gateway Serverthat can be used to access another Server. In these situations, the gatewayServerUriis specified in the EndpointDescriptionand all security checks used to verify Certificatesshall use the gatewayServerUri(see 6.1.3) instead of the serverUri.

To connect to a Servervia the gateway the Clientshall first establish a SecureChannelwith the Gateway Server. Then the Clientshall call the CreateSessionservice and pass the serverUrispecified in the EndpointDescriptionto the Gateway Server. The Gateway Servershall then connect to the underlying Serveron behalf of the Client. The process of connecting to a Servervia a Gateway Serveris illustrated in Figure 10.

image013.png

Figure 10– Using a Gateway Server

Table 5defines the parameters for the Service.

Table 5– GetEndpoints Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters.

The authenticationTokenis always null. The authenticationTokenshall be ignored if it is provided.

The type RequestHeaderis defined in 7.33.

endpointUrl

String

The network address that the Clientused to access the DiscoveryEndpoint.

The Serveruses this information for diagnostics and to determine what URLs to return in the response.

The Servershould return a suitable default URL if it does not recognize the HostNamein the URL.

localeIds []

LocaleId

List of locales to use.

Specifies the locale to use when returning human readable strings.

This parameter is described in 5.4.2.2.

profileUris []

String

List of Transport Profilethat the returned Endpointsshall support. OPC 10000-7defines URIs for the Transport Profiles.

All Endpointsare returned if the list is empty.

If the URI is a URL, this URL may have a query string appended. The Transport Profilesthat support query strings are defined in OPC 10000-7.

Response

responseHeader

ResponseHeader

Common response parameters.

The ResponseHeadertype is defined in 7.34.

Endpoints []

EndpointDescription

List of Endpointsthat meet criteria specified in the request.

This list is empty if no Endpointsmeet the criteria.

The EndpointDescriptiontype is defined in 7.14.

Common StatusCodesare defined in Table 182.

This Service is implemented by Discovery Servers.

This Serviceregisters a Serverwith a Discovery Server. This Servicewill be called by a Serveror a separate configuration utility. Clientswill not use this Service.

A Servershall establish a SecureChannelwith the Discovery Serverbefore calling this Service. The SecureChannelis described in 5.5. The Administratorof the Servershall provide the Serverwith an EndpointDescriptionfor the Discovery Server as part of the configuration process. Discovery Serversshall reject registrations if the serverUriprovided does not match the applicationUriin Server Certificateused to create the SecureChannel.

This Servicecan only be invoked via SecureChannelsthat support Clientauthentication (i.e. HTTPS cannot be used to call this Service).

A Serveronly provides its serverUriand the URLs of the DiscoveryEndpointsto the Discovery Server. Clientsshall use the GetEndpoints Serviceto fetch the most up to date configuration information directly from the Server.

The Servershall provide a localized name for itself in all locales that it supports.

Serversshall be able to register themselves with a Discovery Serverrunning on the same machine. The exact mechanisms depend on the Discovery Serverimplementation and are described in OPC 10000-6.

There are two types of Serverapplications: those which are manually launched including a start by the operating system at boot and those that are automatically launched when a Clientattempts to connect. The registration process that a Servershall use depends on which category it falls into.

The registration process for manually launched Serversis illustrated in Figure 11.

image014.png

Figure 11– The Registration Process – Manually Launched Servers

The registration process for automatically launched Serversis illustrated in Figure 12.

image015.png

Figure 12– The Registration Process – Automatically Launched Servers

The registration process is designed to be platform independent, robust and able to minimize problems created by configuration errors. For that reason, Serversshall register themselves more than once.

Under normal conditions, manually launched Serversshall periodically register with the Discovery Serveras long as they are able to receive connections from Clients. If a Servergoes offline then it shall register itself once more and indicate that it is going offline. The period of the recurring registration should be configurable; however, the maximum is 10 minutes. If an error occurs during registration (e.g. the Discovery Serveris not running) then the Servershall periodically re-attempt registration. The frequency of these attempts should start at 1 second but gradually increase until the registration frequency is the same as what it would be if no errors occurred. The recommended approach would be to double the period of each attempt until reaching the maximum.

When an automatically launched Server(or its install program) registers with the Discovery Serverit shall provide a path to a semaphore file which the Discovery Servercan use to determine if the Serverhas been uninstalled from the machine. The Discovery Server shall have read access to the file system that contains the file.

Table 6defines the parameters for the Service.

Table 6– RegisterServer Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters.

The authenticationTokenis always null.

The type RequestHeaderis defined in 7.33.

Server

RegisteredServer

The Serverto register. The type RegisteredServeris defined in 7.32.

Response

ResponseHeader

ResponseHeader

Common response parameters.

The type ResponseHeaderis defined in 7.34.

Table 7defines the Serviceresults specific to this Service. Common StatusCodesare defined in Table 182.

Table 7– RegisterServer Service Result Codes

Symbolic Id

Description

Bad_InvalidArgument

See Table 182for the description of this result code.

Bad_ServerUriInvalid

See Table 182for the description of this result code.

Bad_ServerNameMissing

No ServerNamewas specified.

Bad_DiscoveryUrlMissing

No discovery URL was specified.

Bad_SemaphoreFileMissing

The semaphore file specified is not valid.

This Service is implemented by Discovery Servers.

This Serviceallows a Serverto register its DiscoveryUrlsand capabilities with a Discovery Server. It extends the registration information from RegisterServerwith information necessary for FindServersOnNetwork. This Servicewill be called by a Serveror a separate configuration utility. Clientswill not use this Service.

Serversthat support RegisterServer2shall try to register with the Discovery Serverusing this Service and shall fall back to RegisterServerif RegisterServer2fails with the status Bad_ServiceUnsupported.

A Discovery Serverthat implements this Serviceneeds to assign unique record ids each time this Serviceis called. See 5.4.3for more details.

This Servicecan only be invoked via SecureChannelsthat support Clientauthentication (i.e. HTTPS cannot be used to call this Service).

Table 8defines the parameters for the Service.

Table 8– RegisterServer2

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters.

The authenticationTokenis always null.

The type RequestHeaderis defined in 7.33.

Server

RegisteredServer

The Serverto register. The type RegisteredServeris defined in 7.32.

discoveryConfiguration []

ExtensibleParameter DiscoveryConfiguration

Additional configuration settings for the Serverto register.

The discoveryConfigurationis an extensible parameter type defined in 7.13.

Discovery Serversthat do not understand a configuration shall return Bad_NotSupported for this configuration.

Response

responseHeader

ResponseHeader

Common response parameters.

The type ResponseHeaderis defined in 7.34.

configurationResults []

StatusCode

List of results for the discoveryConfigurationparameters.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the discoveryConfigurationparameters. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

Table 9defines the Serviceresults specific to this Service. Common StatusCodesare defined in Table 182.

Table 9– RegisterServer2 Service Result Codes

Symbolic Id

Description

Bad_InvalidArgument

See Table 182for the description of this result code.

Bad_ServerUriInvalid

See Table 182for the description of this result code.

Bad_ServerNameMissing

No ServerNamewas specified.

Bad_DiscoveryUrlMissing

No discovery URL was specified.

Bad_SemaphoreFileMissing

The semaphore file specified is not valid.

Bad_ServiceUnsupported

See Table 182for the description of this result code.

Table 10defines values for the operation level configurationResults parameters that are specific to this Service. Common StatusCodesare defined in Table 183.

Table 10– RegisterServer2 Operation Level Result Codes

Symbolic Id

Description

Bad_NotSupported

See Table 183for the description of this result code.