5 Service Sets ToC Previous Next

5.6 Session Service Set ToC Previous Next

5.6.2 CreateSession ToC Previous Next

5.6.2.1 Description ToC

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.

readme_files/image017.png

Figure 14 – Multiplexing Users on a Session

5.6.2.2 Parameters ToC

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.
   revisedSession Timeout 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.

5.6.2.3 Service results ToC

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 The Server has reached its maximum number of Sessions.
Bad_ServerUriInvalid See Table 177 for the description of this result code.

Previous Next