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 22.214.171.124.
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
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
|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 126.96.36.199.
|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.
|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.