Errata exists for this version of the document.
This Service is used by an OPC UA Client to create a Session and the Server returns two values which uniquely identify the Session. The first value is the sessionId which is used to identify the Session in the audit logs and in the Server’s AddressSpace. The second is the authenticationToken which is used to associate an incoming request with a Session.
Before calling this Service, the Client shall create a SecureChannel with the OpenSecureChannel Service to ensure the Integrity of all Messages exchanged during a Session. This SecureChannel has a unique identifier which the Server shall associate with the authenticationToken. The Server may accept requests with the authenticationToken only if they are associated with the same SecureChannel that was used to create the Session. The Client may associate a new SecureChannel with the Session by calling the ActivateSession method.
The SecureChannel is always managed by the Communication Stack which means it shall provide APIs which the Server can use to find out information about the SecureChannel used for any given request. The Communication Stack shall, at a minimum, provide the SecurityPolicy and SecurityMode used by the SecureChannel. It shall also provide a SecureChannelId which uniquely identifies the SecureChannel or the Client Certificate used to establish the SecureChannel. The Server uses one of these to identify the SecureChannel used to send a request. Clause 7.31 describes how to create the authenticationToken for different types of Communication Stack.
Depending upon on the SecurityPolicy and the SecurityMode of the SecureChannel, the exchange of ApplicationInstanceCertificates and Nonces may be optional and the signatures may be empty. See OPC 10000-7 for the definition of SecurityPolicies and the handling of these parameters.
The Server returns its EndpointDescriptions in the response. Clients use this information to determine whether the list of EndpointDescriptions returned from the DiscoveryEndpoint matches the Endpoints that the Server has. If there is a difference then the Client shall close the Session and report an error. The Server returns all EndpointDescriptions for the serverUri specified by the Client in the request. The Client only verifies EndpointDescriptions with a transportProfileUri that matches the profileUri specified in the original GetEndpoints request. A Client may skip this check if the EndpointDescriptions were provided by a trusted source such as the Administrator.
The Session created with this Service shall not be used until the Client calls the ActivateSession Service and provides its SoftwareCertificates and proves possession of its Application Instance Certificate and any user identity token that it provided.
A Server application should limit the number of Sessions. To protect against misbehaving Clients and denial of service attacks, the Server shall close the oldest Session that is not activated before reaching the maximum number of supported Sessions.
The SoftwareCertificates parameter in the Server response is deprecated to reduce the message size for OPC UA Applications with limited resources. The SoftwareCertificates are provided in the Server’s AddressSpace as defined in OPC 10000-5. A SoftwareCertificate identifies the capabilities of the Server and also contains the list of OPC UA Profiles supported by the Server. OPC UA Profiles are defined in OPC 10000-7.
Additional Certificates issued by other organisations may be included to identify additional Server capabilities. Examples of these Profiles include support for specific information models and support for access to specific types of devices.
When a Session is created, the Server adds an entry for the Client in its SessionDiagnosticsArray Variable. See OPC 10000-5 for a description of this Variable.
Sessions are created to be independent of the underlying communications connection. Therefore, if a communications connection fails, the Session is not immediately affected. The exact mechanism to recover from an underlying communication connection error depends on the SecureChannel mapping as described in OPC 10000-6.
Sessions are terminated by the Server automatically if the Client fails to issue a Service request on the Session within the timeout period negotiated by the Server in the CreateSession Service response. This protects the Server against Client failures and against situations where a failed underlying connection cannot be re-established. Clients shall be prepared to submit requests in a timely manner to prevent the Session from closing automatically. Clients may explicitly terminate Sessions using the CloseSession Service.
When a Session is terminated, all outstanding requests on the Session are aborted and Bad_SessionClosed StatusCodes are returned to the Client. In addition, the Server deletes the entry for the Client from its SessionDiagnosticsArray Variable and notifies any other Clients who were subscribed to this entry.
If a Client invokes the CloseSession Service then all Subscriptions associated with the Session are also deleted if the deleteSubscriptions flag is set to TRUE. If a Server terminates a Session for any other reason, Subscriptions associated with the Session, are not deleted. Each Subscription has its own lifetime to protect against data loss in the case of a Session termination. In these cases, the Subscription can be reassigned to another Client before its lifetime expires.
Some Servers, such as aggregating Servers, also act as Clients to other Servers. These Servers typically support more than one system user, acting as their agent to the Servers that they represent. Security for these Servers is supported at two levels.
First, each OPC UA Service request contains a string parameter that is used to carry an audit record id. A Client, or any Server operating as a Client, such as an aggregating Server, can create a local audit log entry for a request that it submits. This parameter allows the Client to pass the identifier for this entry with the request. If the Server also maintains an audit log, then it can include this id in the audit log entry that it writes. When the log is examined and the entry is found, the examiner will be able to relate it directly to the audit log entry created by the Client. This capability allows for traceability across audit logs within a system. See OPC 10000-2 for additional information on auditing. A Server that maintains an audit log shall provide the information in the audit log entries via event Messages defined in this standard. The Server may choose to only provide the Audit information via event Messages. The Audit EventType is defined in OPC 10000-3.
Second, these aggregating Servers may open independent Sessions to the underlying Servers for each Client that accesses data from them. Figure 14 illustrates this concept.
Figure 14 – Multiplexing Users on a Session
Table 15 defines the parameters for the Service.
Table 15 – CreateSession Service Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters. The authenticationToken is always null. The type RequestHeader is defined in 7.28. |
|
clientDescription |
Application Description |
Information that describes the Client application. The type ApplicationDescription is defined in 7.1. |
|
serverUri |
String |
This value is only specified if the EndpointDescription has a gatewayServerUri. This value is the applicationUri from the EndpointDescription which is the applicationUri for the underlying Server. The type EndpointDescription is defined in 7.10. |
|
endpointUrl |
String |
The network address that the Client used to access the Session Endpoint. The HostName portion of the URL should be one of the HostNames for the application that are specified in the Server’s ApplicationInstanceCertificate (see 7.2). The Server shall raise an AuditUrlMismatchEventType event if the URL does not match the Server’s HostNames. AuditUrlMismatchEventType event type is defined in OPC 10000-5. The Server uses this information for diagnostics and to determine the set of EndpointDescriptions to return in the response. |
|
sessionName |
String |
Human readable string that identifies the Session. The Server makes this name and the sessionId visible in its AddressSpace for diagnostic purposes. The Client should provide a name that is unique for the instance of the Client. If this parameter is not specified the Server shall assign a value. |
|
clientNonce |
ByteString |
A random number that should never be used in any other request. This number shall have a minimum length of 32 bytes. Profiles may increase the required length. The Server shall use this value to prove possession of its Application Instance Certificate in the response. |
|
clientCertificate |
ApplicationInstance Certificate |
The Application Instance Certificate issued to the Client. The ApplicationInstanceCertificate type is defined in 7.2. If the securityPolicyUri is None, the Server shall ignore the ApplicationInstanceCertificate. |
|
Requested SessionTimeout |
Duration |
Requested maximum number of milliseconds that a Session should remain open without activity. If the Client fails to issue a Service request within this interval, then the Server shall automatically terminate the Client Session. |
|
maxResponse MessageSize |
UInt32 |
The maximum size, in bytes, for the body of any response message. The Server should return a Bad_ResponseTooLarge service fault if a response message exceeds this limit. The value zero indicates that this parameter is not used. The transport protocols defined in OPC 10000-6 may imply minimum message sizes. More information on the use of this parameter is provided in 5.3. |
|
Response |
|
|
|
responseHeader |
ResponseHeader |
Common response parameters (see 7.29 for ResponseHeader type). |
|
sessionId |
NodeId |
A unique NodeId assigned by the Server to the Session. This identifier is used to access the diagnostics information for the Session in the Server AddressSpace. It is also used in the audit logs and any events that report information related to the Session. The Session diagnostic information is described in OPC 10000-5. Audit logs and their related events are described in 6.5. |
|
authentication Token |
Session AuthenticationToken |
A unique identifier assigned by the Server to the Session. This identifier shall be passed in the RequestHeader of each request and is used with the SecureChannelId to determine whether a Client has access to the Session. This identifier shall not be reused in a way that the Client or the Server has a chance of confusing them with a previous or existing Session. The SessionAuthenticationToken type is described in 7.31. |
|
revisedSessionTimeout |
Duration |
Actual maximum number of milliseconds that a Session shall remain open without activity. The Server should attempt to honour the Client request for this parameter, but may negotiate this value up or down to meet its own constraints. |
|
serverNonce |
ByteString |
A random number that should never be used in any other request. This number shall have a minimum length of 32 bytes. The Client shall use this value to prove possession of its Application Instance Certificate in the ActivateSession request. This value may also be used to prove possession of the userIdentityToken it specified in the ActivateSession request. |
|
serverCertificate |
ApplicationInstance Certificate |
The Application Instance Certificate issued to the Server. A Server shall prove possession by using the private key to sign the Nonce provided by the Client in the request. The Client shall verify that this Certificate is the same as the one it used to create the SecureChannel. The ApplicationInstanceCertificate type is defined in 7.2. If the securityPolicyUri is NONE and none of the UserTokenPolicies requires encryption, the Client shall ignore the ApplicationInstanceCertificate. |
|
serverEndpoints [] |
EndpointDescription |
List of Endpoints that the Server supports. The Server shall return a set of EndpointDescriptions available for the serverUri specified in the request. The EndpointDescription type is defined in 7.10. The Client shall verify this list with the list from a DiscoveryEndpoint if it used a DiscoveryEndpoint to fetch the EndpointDescriptions. It is recommended that Servers only include the server.applicationUri, endpointUrl, securityMode, securityPolicyUri, userIdentityTokens, transportProfileUri and securityLevel with all other parameters set to null. Only the recommended parameters shall be verified by the client. |
|
serverSoftware Certificates [] |
SignedSoftware Certificate |
This parameter is deprecated and the array shall be empty. The SoftwareCertificates are provided in the Server AddressSpace as defined in OPC 10000-5. |
|
serverSignature |
SignatureData |
This is a signature generated with the private key associated with the serverCertificate. This parameter is calculated by appending the clientNonce to the clientCertificate and signing the resulting sequence of bytes. If the clientCertificate contains a chain, the signature calculation shall be done only with the leaf Certificate. For backward compatibility a Client shall check the signature with the full chain if the check with the leaf Certificate fails. The SignatureAlgorithm shall be the AsymmetricSignatureAlgorithm specified in the SecurityPolicy for the Endpoint. The SignatureData type is defined in 7.32. |
|
maxRequest MessageSize |
UInt32 |
The maximum size, in bytes, for the body of any request message. The Client Communication Stack should return a Bad_RequestTooLarge error to the application if a request message exceeds this limit. The value zero indicates that this parameter is not used. See OPC 10000-6 for protocol specific minimum or default values. 5.3 provides more information on the use of this parameter. |
Table 16 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.
Table 16 – CreateSession Service Result Codes
|
Symbolic Id |
Description |
|
Bad_SecureChannelIdInvalid |
See Table 177 for the description of this result code. |
|
Bad_NonceInvalid |
See Table 177 for the description of this result code. A Server shall check the minimum length of the Client nonce and return this status if the length is below 32 bytes. A check for a duplicated nonce is optional and requires access to the nonce used to create the secure channel. |
|
Bad_SecurityChecksFailed |
See Table 177 for the description of this result code. |
|
Bad_CertificateTimeInvalid |
See Table 177 for the description of this result code. |
|
Bad_CertificateIssuerTimeInvalid |
See Table 177 for the description of this result code. |
|
Bad_CertificateHostNameInvalid |
See Table 177 for the description of this result code. |
|
Bad_CertificateUriInvalid |
See Table 177 for the description of this result code. |
|
Bad_CertificateUseNotAllowed |
See Table 177 for the description of this result code. |
|
Bad_CertificateIssuerUseNotAllowed |
See Table 177 for the description of this result code. |
|
Bad_CertificateUntrusted |
See Table 177 for the description of this result code. |
|
Bad_CertificateRevocationUnknown |
See Table 177 for the description of this result code. |
|
Bad_CertificateIssuerRevocationUnknown |
See Table 177 for the description of this result code. |
|
Bad_CertificateRevoked |
See Table 177 for the description of this result code. |
|
Bad_CertificateIssuerRevoked |
See Table 177 for the description of this result code. |
|
Bad_TooManySessions |
|
|
Bad_ServerUriInvalid |
See Table 177 for the description of this result code. |