This Serviceis used by an OPC UA Clientto create a Sessionand the Serverreturns two values which uniquely identify the Session. The first value is the sessionIdwhich is used to identify the Sessionin the audit logs and in the Server’s AddressSpace. The second is the authenticationTokenwhich is used to associate an incoming request with a Session.
Before calling this Service, the Clientshall create a SecureChannelwith the OpenSecureChannel Serviceto ensure the Integrityof all Messagesexchanged during a Session. This SecureChannelhas a unique identifier which the Servershall associate with the authenticationToken. The Servermay accept requests with the authenticationToken only if they are associated with the same SecureChannelthat was used to create the Session. The Clientmay associate a new SecureChannelwith the Sessionby calling the ActivateSessionmethod.
The SecureChannelis always managed by the Communication Stackwhich means it shall provide APIs which the Servercan use to find out information about the SecureChannelused for any given request. The Communication Stackshall, at a minimum, provide the SecurityPolicyand SecurityModeused by the SecureChannel. It shall also provide a SecureChannelIdwhich uniquely identifies the SecureChannelor the Client Certificateused to establish the SecureChannel. The Serveruses one of these to identify the SecureChannelused to send a request. Clause 7.31describes how to create the authenticationToken for different types of Communication Stack.
Depending upon on the SecurityPolicyand the SecurityModeof the SecureChannel,the exchange of ApplicationInstanceCertificatesand Noncesmay be optional and the signatures may be empty. See OPC 10000-7for the definition of SecurityPoliciesand the handling of these parameters.
The Serverreturns its EndpointDescriptionsin the response. Clientsuse this information to determine whether the list of EndpointDescriptionsreturned from the DiscoveryEndpointmatches the Endpointsthat the Serverhas. If there is a difference then the Clientshall close the Sessionand report an error. The Serverreturns all EndpointDescriptionsfor the serverUrispecified by the Clientin the request. The Clientonly verifies EndpointDescriptionswith a transportProfileUrithat matches the profileUrispecified in the original GetEndpointsrequest. A Clientmay skip this check if the EndpointDescriptionswere provided by a trusted source such as the Administrator.
The Sessioncreated with this Serviceshall not be used until the Clientcalls the ActivateSession Serviceand provides its SoftwareCertificatesand proves possession of its Application Instance Certificateand any user identity token that it provided.
A Serverapplication should limit the number of Sessions. To protect against misbehaving Clientsand denial of service attacks, the Servershall close the oldest Sessionthat is not activated before reaching the maximum number of supported Sessions.
The SoftwareCertificatesparameter in the Serverresponse is deprecated to reduce the message size for OPC UA Applications with limited resources. The SoftwareCertificatesare provided in the Server’s AddressSpaceas defined in OPC 10000-5. A SoftwareCertificateidentifies the capabilities of the Serverand also contains the list of OPC UA Profilessupported by the Server. OPC UA Profilesare defined in OPC 10000-7.
Additional Certificatesissued by other organisations may be included to identify additional Servercapabilities. Examples of these Profilesinclude support for specific information models and support for access to specific types of devices.
When a Sessionis created, the Serveradds an entry for the Clientin its SessionDiagnosticsArray Variable. See OPC 10000-5for a description of this Variable.
Sessionsare created to be independent of the underlying communications connection. Therefore, if a communications connection fails, the Sessionis 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.
Sessionsare terminated by the Serverautomatically if the Clientfails to issue a Servicerequest on the Sessionwithin the timeout period negotiated by the Serverin the CreateSession Serviceresponse. This protects the Serveragainst Clientfailures and against situations where a failed underlying connection cannot be re-established. Clientsshall be prepared to submit requests in a timely manner to prevent the Sessionfrom closing automatically. Clientsmay explicitly terminate Sessionsusing the CloseSession Service.
When a Sessionis terminated, all outstanding requests on the Sessionare aborted and Bad_SessionClosed StatusCodesare returned to the Client. In addition, the Serverdeletes the entry for the Clientfrom its SessionDiagnosticsArray Variableand notifies any other Clientswho were subscribed to this entry.
If a Clientinvokes the CloseSession Servicethen all Subscriptionsassociated with the Sessionare also deleted if the deleteSubscriptionsflag is set to TRUE. If a Serverterminates a Sessionfor any other reason, Subscriptionsassociated with the Session, are not deleted. Each Subscriptionhas its own lifetime to protect against data loss in the case of a Sessiontermination. In these cases, the Subscriptioncan be reassigned to another Clientbefore its lifetime expires.
Some Servers, such as aggregating Servers, also act as Clientsto other Servers. These Serverstypically support more than one system user, acting as their agent to the Serversthat they represent. Security for these Serversis supported at two levels.
First, each OPC UA Servicerequest contains a string parameter that is used to carry an audit record id. A Client, or any Serveroperating 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 Clientto pass the identifier for this entry with the request. If the Serveralso 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-2for additional information on auditing. A Serverthat maintains an audit log shall provide the information in the audit log entries via event Messages defined in this standard. The Servermay choose to only provide the Auditinformation via event Messages. The Audit EventTypeis defined in OPC 10000-3.
Second, these aggregating Serversmay open independent Sessionsto the underlying Serversfor each Clientthat accesses data from them. Figure 14illustrates this concept.
Figure 14– Multiplexing Users on a Session
Table 15defines the parameters for the Service.
Table 15– CreateSession Service Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters. The authenticationTokenis always null. The type RequestHeaderis defined in 7.28. |
|
clientDescription |
Application Description |
Information that describes the Clientapplication. The type ApplicationDescriptionis defined in 7.1. |
|
serverUri |
String |
This value is only specified if the EndpointDescriptionhas a gatewayServerUri. This value is the applicationUrifrom the EndpointDescriptionwhich is the applicationUrifor the underlying Server. The type EndpointDescriptionis defined in 7.10. |
|
endpointUrl |
String |
The network address that the Clientused to access the Session Endpoint. The HostNameportion of the URL should be one of the HostNamesfor the application that are specified in the Server’s ApplicationInstanceCertificate(see 7.2). The Servershall 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 EndpointDescriptionsto return in the response. |
|
sessionName |
String |
Human readable string that identifies the Session. The Servermakes this name and the sessionIdvisible in its AddressSpacefor diagnostic purposes. The Clientshould provide a name that is unique for the instance of the Client. If this parameter is not specified the Servershall 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 Servershall use this value to prove possession of its Application Instance Certificatein the response. |
|
clientCertificate |
ApplicationInstance Certificate |
The Application Instance Certificateissued to the Client. The ApplicationInstanceCertificatetype is defined in 7.2. If the securityPolicyUriis None, the Servershall ignore the ApplicationInstanceCertificate. |
|
Requested SessionTimeout |
Duration |
Requested maximum number of milliseconds that a Sessionshould remain open without activity. If the Clientfails to issue a Servicerequest within this interval, then the Servershall automatically terminate the Client Session. |
|
maxResponse MessageSize |
UInt32 |
The maximum size, in bytes, for the body of any response message. The Servershould return a Bad_ResponseTooLargeservice 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-6may 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.29for ResponseHeadertype). |
|
sessionId |
NodeId |
A unique NodeIdassigned by the Serverto the Session. This identifier is used to access the diagnostics information for the Sessionin the Server AddressSpace. It is also used in the audit logs and any events that report information related to the Session. The Sessiondiagnostic 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 Serverto the Session. This identifier shall be passed in the RequestHeaderof each request and is used with the SecureChannelIdto determine whether a Clienthas access to the Session. This identifier shall not be reused in a way that the Clientor the Serverhas a chance of confusing them with a previous or existing Session. The SessionAuthenticationTokentype is described in 7.31. |
|
revisedSessionTimeout |
Duration |
Actual maximum number of milliseconds that a Sessionshall remain open without activity. The Servershould attempt to honour the Clientrequest 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 Clientshall use this value to prove possession of its Application Instance Certificatein the ActivateSessionrequest. This value may also be used to prove possession of the userIdentityTokenit specified in the ActivateSessionrequest. |
|
serverCertificate |
ApplicationInstance Certificate |
The Application Instance Certificateissued to the Server. A Servershall prove possession by using the private key to sign the Nonceprovided by the Clientin the request. The Clientshall verify that this Certificateis the same as the one it used to create the SecureChannel. The ApplicationInstanceCertificatetype is defined in 7.2. If the securityPolicyUriis NONE and none of the UserTokenPoliciesrequires encryption, the Clientshall ignore the ApplicationInstanceCertificate. |
|
serverEndpoints [] |
EndpointDescription |
List of Endpointsthat the Serversupports. The Servershall return a set of EndpointDescriptionsavailable for the serverUrispecified in the request. The EndpointDescriptiontype is defined in 7.10. The Clientshall verify this list with the list from a DiscoveryEndpointif it used a DiscoveryEndpointto fetch the EndpointDescriptions. It is recommended that Serversonly include the server.applicationUri, endpointUrl, securityMode, securityPolicyUri, userIdentityTokens, transportProfileUriand securityLevelwith 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 SoftwareCertificatesare provided in the Server AddressSpaceas 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 clientNonceto the clientCertificateand signing the resulting sequence of bytes. If the clientCertificatecontains a chain, the signature calculation shall be done only with the leaf Certificate. For backward compatibility a Clientshall check the signature with the full chain if the check with the leaf Certificatefails. The SignatureAlgorithmshall be the AsymmetricSignatureAlgorithmspecified in the SecurityPolicyfor the Endpoint. The SignatureDatatype is defined in 7.32. |
|
maxRequest MessageSize |
UInt32 |
The maximum size, in bytes, for the body of any request message. The Client Communication Stackshould return a Bad_RequestTooLargeerror to the application if a request message exceeds this limit. The value zero indicates that this parameter is not used. See OPC 10000-6for protocol specific minimum or default values. 5.3provides more information on the use of this parameter. |
Table 16defines the Serviceresults specific to this Service. Common StatusCodesare defined in Table 177.
Table 16– CreateSession Service Result Codes
|
Symbolic Id |
Description |
|
Bad_SecureChannelIdInvalid |
See Table 177for the description of this result code. |
|
Bad_NonceInvalid |
See Table 177for the description of this result code. A Servershall check the minimum length of the Clientnonce 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 177for the description of this result code. |
|
Bad_CertificateTimeInvalid |
See Table 177for the description of this result code. |
|
Bad_CertificateIssuerTimeInvalid |
See Table 177for the description of this result code. |
|
Bad_CertificateHostNameInvalid |
See Table 177for the description of this result code. |
|
Bad_CertificateUriInvalid |
See Table 177for the description of this result code. |
|
Bad_CertificateUseNotAllowed |
See Table 177for the description of this result code. |
|
Bad_CertificateIssuerUseNotAllowed |
See Table 177for the description of this result code. |
|
Bad_CertificateUntrusted |
See Table 177for the description of this result code. |
|
Bad_CertificateRevocationUnknown |
See Table 177for the description of this result code. |
|
Bad_CertificateIssuerRevocationUnknown |
See Table 177for the description of this result code. |
|
Bad_CertificateRevoked |
See Table 177for the description of this result code. |
|
Bad_CertificateIssuerRevoked |
See Table 177for the description of this result code. |
|
Bad_TooManySessions |
|
|
Bad_ServerUriInvalid |
See Table 177for the description of this result code. |