Errata exists for this version of the document.
This Service Set defines Services used to discover the Endpoints implemented by a Server and to read the security configuration for those Endpoints. The Discovery Services are implemented by individual Servers and by dedicated Discovery Servers. OPC 10000-12 describes how to use the Discovery Services with dedicated Discovery Servers.
Every Server shall have a DiscoveryEndpoint that Clients can access without establishing a Session. This Endpoint may or may not be the same Session Endpoint that Clients use to establish a SecureChannel. Clients read the security information necessary to establish a SecureChannel by calling the GetEndpoints Service on the DiscoveryEndpoint.
In addition, Servers may register themselves with a well-known Discovery Server using the RegisterServer Service. Clients can later discover any registered Servers by calling the FindServers Service on the Discovery Server.
The discovery process using FindServers is illustrated in Figure 9. The establishment of a SecureChannel (with MessageSecurityMode NONE) for FindServers and GetEndpoints is omitted from the figure for clarity.
The URL for a DiscoveryEndpoint shall provide all of the information that the Client needs to connect to the DiscoveryEndpoint.
Once a Client retrieves the Endpoints, the Client can save this information and use it to connect directly to the Server again without going through the discovery process. If the Client finds that it cannot connect then the Server configuration may have changed and the Client needs to go through the discovery process again.
DiscoveryEndpoints shall not require any message security, but it may require transport layer security. In production systems, Administrators may disable discovery for security reasons and Clients shall rely on cached EndpointDescriptions. To provide support for systems with disabled Discovery Services Clients shall allow Administrators to manually update the EndpointDescriptions used to connect to a Server. Servers shall allow Administrators to disable the DiscoveryEndpoint.
A Client shall be careful when using the information returned from a DiscoveryEndpoint since it has no security. A Client does this by comparing the information returned from the DiscoveryEndpoint to the information returned in the CreateSession response. A Client shall verify that:
- The ApplicationUri specified in the Server Certificate is the same as the ApplicationUri provided in the EndpointDescription.
- The Server Certificate returned in CreateSession response is the same as the Certificate used to create the SecureChannel.
- The EndpointDescriptions returned from the DiscoveryEndpoint are the same as the EndpointDescriptions returned in the CreateSession response.
If the Client detects that one of the above requirements is not fulfilled, then the Client shall close the SecureChannel and report an error.
A Client shall verify the HostName specified in the Server Certificate is the same as the HostName contained in the endpointUrl provided in the EndpointDescription returned by CreateSession. If there is a difference then the Client shall report the difference and may close the SecureChannel. Servers shall add all possible HostNames like MyHost and MyHost.local into the Server Certificate. This includes IP addresses of the host or the HostName exposed by a NAT router used to connect to the Server.
This Service returns the Servers known to a Server or Discovery Server. The behaviour of Discovery Servers is described in detail in OPC 10000-12.
The Client may reduce the number of results returned by specifying filter criteria. A Discovery Server returns an empty list if no Servers match the criteria specified by the client. The filter criteria supported by this Service are described in 5.4.2.2.
Every Server shall provide a DiscoveryEndpoint that supports this Service. The Server shall always return a record that describes itself, however in some cases more than one record may be returned. Gateway Servers shall return a record for each Server that they provide access to plus (optionally) a record that allows the Gateway Server to be accessed as an ordinary OPC UA Server. Non-transparent redundant Servers shall provide a record for each Server in the Redundant Server Set.
Every Server shall 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 ServerUri returned by this Service shall be the same value that appears in index 0 of the ServerArray property (see OPC 10000-5). The ServerUri is returned as the applicationUri field in the ApplicationDescription (see 7.1)
Every Server shall also have a human readable identifier called the ServerName which is not necessarily globally unique. This identifier may be available in multiple locales.
A Server may have multiple HostNames. For this reason, the Client shall pass the URL it used to connect to the Endpoint to this Service. The implementation of this Service shall use this information to return responses that are accessible to the Client via the provided URL.
This Service shall not require message security but it may require transport layer security.
Some Servers may be accessed via a Gateway Server and shall have a value specified for gatewayServerUri in their ApplicationDescription (see 7.1). The discoveryUrls provided in ApplicationDescription shall belong to the Gateway Server. Some Discovery Servers may return multiple records for the same Server if that Server can be accessed via multiple paths.
This Service can be used without security and it is therefore vulnerable to Denial of Service (DOS) attacks. A Server should minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance. The Server should also add a short delay before starting processing of a request during high traffic conditions.
Table 3 defines the parameters for the Service.
Table 3 – FindServers Service Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters. The authenticationToken is always null. The authenticationToken shall be ignored if it is provided. The type RequestHeader is defined in 7.28. |
|
endpointUrl |
String |
The network address that the Client used to access the DiscoveryEndpoint. The Server uses this information for diagnostics and to determine what URLs to return in the response. The Server should return a suitable default URL if it does not recognize the HostName in the URL. |
|
localeIds [] |
LocaleId |
List of locales to use. The Server should return the applicationName in the ApplicationDescription defined in 7.1 using one of locales specified. If the Server supports more than one of the requested locales then the Server shall use the locale that appears first in this list. If the Server does not support any of the requested locales it chooses an appropriate default locale. The Server chooses an appropriate default locale if this list is empty. |
|
serverUris [] |
String |
List of servers to return. All known servers are returned if the list is empty. A serverUri matches the applicationUri from the ApplicationDescription defined in 7.1. |
|
|
|
|
|
Response |
|
|
|
responseHeader |
ResponseHeader |
Common response parameters. The ResponseHeader type is defined in 7.29. |
|
servers [] |
ApplicationDescription |
List of Servers that meet criteria specified in the request. This list is empty if no servers meet the criteria. The ApplicationDescription type is defined in 7.1. |
Common StatusCodes are defined in Table 177.
This Service returns the Servers known to a Discovery Server. Unlike FindServers, this Service is only implemented by Discovery Servers.
The Client may reduce the number of results returned by specifying filter criteria. An empty list is returned if no Server matches the criteria specified by the Client.
This Service shall not require message security but it may require transport layer security.
Each time the Discovery Server creates or updates a record in its cache 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 FindServersOnNetwork. To support this the Discovery Server shall return records in numerical order starting from the lowest record identifier. The Discovery Server shall also return the last time the counter was reset for example due to a restart of the Discovery Server. If a Client detects that this time is more recent than the last time the Client called the Service it shall call the Service again with a startingRecordId of 0.
This Service can be used without security and it is therefore vulnerable to denial of service (DOS) attacks. A Server should minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance.
Table 4 defines the parameters for the Service.
Table 4 – FindServersOnNetwork Service Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters. The authenticationToken is always null. The authenticationToken shall be ignored if it is provided. The type RequestHeader is defined in 7.28. |
|
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 Server capability filters. The set of allowed Server capabilities are defined in OPC 10000-12. Only records with all of the specified Server capabilities are returned. The comparison is case insensitive. If this list is empty then no filtering is performed. |
|
|
|
|
|
Response |
|
|
|
responseHeader |
ResponseHeader |
Common response parameters. The ResponseHeader type is defined in 7.29. |
|
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 Servers meet the criteria. |
|
recordId |
UInt32 |
A unique identifier for the record. This can be used to fetch the next batch of Servers in a subsequent call to FindServersOnNetwork. |
|
serverName |
String |
The name of the Server specified in the mDNS announcement (see OPC 10000-12). This may be the same as the ApplicationName for the Server. |
|
discoveryUrl |
String |
The URL of the DiscoveryEndpoint. |
|
serverCapabilities |
String[] |
The set of Server capabilities supported by the Server. The set of allowed Server capabilities are defined in OPC 10000-12. |
Common StatusCodes are defined in Table 177.
This Service returns the Endpoints supported by a Server and all of the configuration information required to establish a SecureChannel and a Session.
This Service shall not require message security but it may require transport layer security.
A Client may reduce the number of results returned by specifying filter criteria based on LocaleIds and Transport Profile URIs. The Server returns an empty list if no Endpoints match the criteria specified by the client. The filter criteria supported by this Service are described in 5.4.4.2.
A Server may support multiple security configurations for the same Endpoint. In this situation, the Server shall return separate EndpointDescription records for each available configuration. Clients should treat each of these configurations as distinct Endpoints even if the physical URL happens to be the same.
The security configuration for an Endpoint has four components:
Server Application Instance Certificate
Message Security Mode
Security Policy
Supported User Identity Tokens
The ApplicationInstanceCertificate is used to secure the OpenSecureChannel request (see 5.5.2). The MessageSecurityMode and the SecurityPolicy tell the Client how to secure messages sent via the SecureChannel. The UserIdentityTokens tell the Client which type of user credentials shall be passed to the Server in the ActivateSession request (see 5.6.3).
If the securityPolicyUri is NONE and none of the UserTokenPolicies requires encryption, the Client shall ignore the ApplicationInstanceCertificate.
Each EndpointDescription also specifies a URI for the Transport Profile that the Endpoint supports. The Transport Profiles specify 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 SecurityPolicy for the Endpoint. OPC 10000-7 defines Profiles for 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 Client cannot connect to an Endpoint that does not support a SecurityPolicy that it recognizes.
An EndpointDescription may 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 NONE then it is possible for Clients to deliberately or accidentally hijack Sessions created by other Clients.
A Server may have multiple HostNames. For this reason, the Client shall pass the URL it used to connect to the Endpoint to this Service. The implementation of this Service shall use this information to return responses that are accessible to the Client via the provided URL.
This Service can be used without security and it is therefore vulnerable to Denial of Service (DOS) attacks. A Server should minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance. The Server should also add a short delay before starting processing of a request during high traffic conditions.
Some of the EndpointDescriptions returned in a response shall specify the Endpoint information for a Gateway Server that can be used to access another Server. In these situations, the gatewayServerUri is specified in the EndpointDescription and all security checks used to verify Certificates shall use the gatewayServerUri (see 6.1.3) instead of the serverUri.
To connect to a Server via the gateway the Client shall first establish a SecureChannel with the Gateway Server. Then the Client shall call the CreateSession service and pass the serverUri specified in the EndpointDescription to the Gateway Server. The Gateway Server shall then connect to the underlying Server on behalf of the Client. The process of connecting to a Server via a Gateway Server is illustrated in Figure 10.
Figure 10 – Using a Gateway Server
Table 5 defines the parameters for the Service.
Table 5 – GetEndpoints Service Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters. The authenticationToken is always null. The authenticationToken shall be ignored if it is provided. The type RequestHeader is defined in 7.28. |
|
endpointUrl |
String |
The network address that the Client used to access the DiscoveryEndpoint. The Server uses this information for diagnostics and to determine what URLs to return in the response. The Server should return a suitable default URL if it does not recognize the HostName in 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 Profile that the returned Endpoints shall support. OPC 10000-7 defines URIs for the Transport Profiles. All Endpoints are returned if the list is empty. If the URI is a URL, this URL may have a query string appended. The Transport Profiles that support query strings are defined in OPC 10000-7. |
|
|
|
|
|
Response |
|
|
|
responseHeader |
ResponseHeader |
Common response parameters. The ResponseHeader type is defined in 7.29. |
|
Endpoints [] |
EndpointDescription |
List of Endpoints that meet criteria specified in the request. This list is empty if no Endpoints meet the criteria. The EndpointDescription type is defined in 7.10. |
Common StatusCodes are defined in Table 177.
This Service is implemented by Discovery Servers.
This Service registers a Server with a Discovery Server. This Service will be called by a Server or a separate configuration utility. Clients will not use this Service.
A Server shall establish a SecureChannel with the Discovery Server before calling this Service. The SecureChannel is described in 5.5. The Administrator of the Server shall provide the Server with an EndpointDescription for the Discovery Server as part of the configuration process. Discovery Servers shall reject registrations if the serverUri provided does not match the applicationUri in Server Certificate used to create the SecureChannel.
This Service can only be invoked via SecureChannels that support Client authentication (i.e. HTTPS cannot be used to call this Service).
A Server only provides its serverUri and the URLs of the DiscoveryEndpoints to the Discovery Server. Clients shall use the GetEndpoints Service to fetch the most up to date configuration information directly from the Server.
The Server shall provide a localized name for itself in all locales that it supports.
Servers shall be able to register themselves with a Discovery Server running on the same machine. The exact mechanisms depend on the Discovery Server implementation and are described in OPC 10000-6.
There are two types of Server applications: those which are manually launched including a start by the operating system at boot and those that are automatically launched when a Client attempts to connect. The registration process that a Server shall use depends on which category it falls into.
The registration process for manually launched Servers is illustrated in Figure 11.
Figure 11 – The Registration Process – Manually Launched Servers
The registration process for automatically launched Servers is illustrated in Figure 12.
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, Servers shall register themselves more than once.
Under normal conditions, manually launched Servers shall periodically register with the Discovery Server as long as they are able to receive connections from Clients. If a Server goes 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 Server is not running) then the Server shall 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 Server it shall provide a path to a semaphore file which the Discovery Server can use to determine if the Server has been uninstalled from the machine. The Discovery Server shall have read access to the file system that contains the file.
Table 6 defines the parameters for the Service.
Table 6 – RegisterServer Service Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters. The authenticationToken is always null. The type RequestHeader is defined in 7.28. |
|
Server |
RegisteredServer |
The Server to register. The type RegisteredServer is defined in 7.27. |
|
|
|
|
|
Response |
|
|
|
ResponseHeader |
ResponseHeader |
Common response parameters. The type ResponseHeader is defined in 7.29. |
Table 7 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.
Table 7 – RegisterServer Service Result Codes
|
Symbolic Id |
Description |
|
Bad_InvalidArgument |
See Table 177 for the description of this result code. |
|
Bad_ServerUriInvalid |
See Table 177 for the description of this result code. |
|
Bad_ServerNameMissing |
No ServerName was 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 Service allows a Server to register its DiscoveryUrls and capabilities with a Discovery Server. It extends the registration information from RegisterServer with information necessary for FindServersOnNetwork. This Service will be called by a Server or a separate configuration utility. Clients will not use this Service.
Servers that support RegisterServer2 shall try to register with the Discovery Server using this Service and shall fall back to RegisterServer if RegisterServer2 fails with the status Bad_ServiceUnsupported.
A Discovery Server that implements this Service needs to assign unique record ids each time this Service is called. See 5.4.3 for more details.
This Service can only be invoked via SecureChannels that support Client authentication (i.e. HTTPS cannot be used to call this Service).
Table 8 defines the parameters for the Service.
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters. The authenticationToken is always null. The type RequestHeader is defined in 7.28. |
|
Server |
RegisteredServer |
The Server to register. The type RegisteredServer is defined in 7.27. |
|
discoveryConfiguration [] |
ExtensibleParameter DiscoveryConfiguration |
Additional configuration settings for the Server to register. The discoveryConfiguration is an extensible parameter type defined in 7.9. Discovery Servers that do not understand a configuration shall return Bad_NotSupported for this configuration. |
|
|
|
|
|
Response |
|
|
|
ResponseHeader |
ResponseHeader |
Common response parameters. The type ResponseHeader is defined in 7.29. |
|
configurationResults [] |
StatusCode |
List of results for the discoveryConfiguration parameters. |
|
diagnosticInfos [] |
DiagnosticInfo |
List of diagnostic information for the discoveryConfiguration parameters. 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 9 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.
Table 9 – RegisterServer2 Service Result Codes
|
Symbolic Id |
Description |
|
Bad_InvalidArgument |
See Table 177 for the description of this result code. |
|
Bad_ServerUriInvalid |
See Table 177 for the description of this result code. |
|
Bad_ServerNameMissing |
No ServerName was specified. |
|
Bad_DiscoveryUrlMissing |
No discovery URL was specified. |
|
Bad_SemaphoreFileMissing |
The semaphore file specified is not valid. |
|
Bad_ServiceUnsupported |
See Table 177 for the description of this result code. |
Table 10 defines values for the operation level statusCode parameters that are specific to this Service. Common StatusCodes are defined in Table 178.
Table 10 – RegisterServer2 Operation Level Result Codes
|
Symbolic Id |
Description |
|
Bad_NotSupported |
See Table 178 for the description of this result code. |