This Service Setdefines Servicesfor an application layer connection establishment in the context of a Session.

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.

image017.png

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

The Serverhas reached its maximum number of Sessions.

Bad_ServerUriInvalid

See Table 177for the description of this result code.

This Serviceis used by the Clientto specify the identity of the user associated with the Session. This Servicerequest shall be issued by the Clientbefore it issues any Servicerequest other than CloseSessionafter CreateSession. Failure to do so shall cause the Serverto close the Session.

Whenever the Clientcalls this Servicethe Clientshall prove that it is the same application that called the CreateSession Service. The Clientdoes this by creating a signature with the private key associated with the clientCertificatespecified in the CreateSessionrequest. This signature is created by appending the last serverNonceprovided by the Serverto the serverCertificateand calculating the signature of the resulting sequence of bytes.

Once used, a serverNoncecannot be used again. For that reason, the Serverreturns a new serverNonceeach time the ActivateSession Serviceis called.

When the ActivateSession Service is called for the first time then the Server shall reject the request if the SecureChannelis not same as the one associated with the CreateSessionrequest. Subsequent calls toActivateSession may be associated with different SecureChannels. If this is the case thenthe Servershall verify that the Certificatethe Clientused to create the new SecureChannelis the same as the Certificateused to create the original SecureChannel. In addition, the Server shall verify that the Clientsupplied a UserIdentityTokenthat is identical to the token currently associated with the Session. Once the Server accepts the new SecureChannelit shall reject requests sent via the old SecureChannel.

The ActivateSession Service is used to associate a user identity with a Session. When a Clientprovides a user identity then it shall provide proof that it is authorized to use that user identity. The exact mechanism used to provide this proof depends on the type of the UserIdentityToken. If the tokenis aUserNameIdentityTokenthen the proof is the passwordthat is included in the token. If the token is an X509IdentityToken then the proof is a signature generated with private key associated with the Certificate. The data to sign is created by appending the last serverNonceto the serverCertificatespecified in the CreateSessionresponse. If a token includes a secret then it should be encrypted using the public key from the serverCertificate.

Serversshall take proper measures to protect against attacks on user identity tokens. Such an attack is assumed if repeated connection attempts with invalid user identity tokens happen. One option is to lock out an OPC UA Clientfor a period of time if the user identity token validation fails several times. The OPC UA Clientis either detected by IP address for unsecured connections or by the ApplicationInstanceUrifor secured connections. Another option is delaying the Serviceresponse when the validation of a user identity fails. This delay time could be increased with repeated failures. Sporadic failures shall not delay connections with valid tokens.

Clientscan change the identity of a user associated with a Sessionby calling the ActivateSession Service. The Servervalidates the signatures provided with the request and then validates the new user identity. If no errors occur the Serverreplaces the user identity for the Session. Changing the user identity for a Sessionmay cause discontinuities in active Subscriptionsbecause the Servermay have to tear down connections to an underlying system and re-establish them using the new credentials.

When a Clientsupplies a list of locale ids in the request, each locale id is required to contain the language component. It may optionally contain the <country/region> component. When the Serverreturns a LocalizedTextin the context of the Session, it also may return both the language and the country/region or just the language as its default locale id.

When a Serverreturns a string to the Client, it first determines if there are available translations for it. If there are, then the Serverreturns the string whose locale id exactly matches the locale id with the highest priority in the Client-supplied list.

If there are no exact matches, then the Serverignores the <country/region> component of the locale id, and returns the string whose <language> component matches the <language> component of the locale id with the highest priority in the Clientsupplied list.

If there still are no matches, then the Serverreturns the string that it has along with the locale id.

A Gateway Serveris expected to impersonate the user provided by the Clientwhen it connects to the underlying Server. This means it shall re-calculate the signatures on the UserIdentityTokenusing the nonce provided by the underlying Server. The Gateway Serverwill have to use its own user credentials if the UserIdentityTokenprovided by the Clientdoes not support impersonation.

Table 17defines the parameters for the Service.

Table 17– ActivateSession Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters. The type RequestHeaderis defined in 7.28.

clientSignature

SignatureData

This is a signature generated with the private key associated with the clientCertificate. This parameter is calculated by appending the serverNonceto the serverCertificateand signing the resulting sequence of bytes.

If the serverCertificatecontains a chain, the signature calculation shall be done only with the leaf Certificate. For backward compatibility a Servershall 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.

clientSoftwareCertificates []

SignedSoftware‌Certificate

Reserved for future use.

The SignedSoftwareCertificatetype is defined in 7.33.

localeIds []

LocaleId

List of locale ids in priority order for localized strings. The first LocaleIdin the list has the highest priority. If the Serverreturns a localized string to the Client, the Servershall return the translation with the highest priority that it can. If it does not have a translation for any of the locales identified in this list, then it shall return the string value that it has and include the locale id with the string. See OPC 10000-3for more detail on locale ids. If the Clientfails to specify at least one locale id, the Servershall use any that it has.

This parameter only needs to be specified during the first call to ActivateSessionduring a single application Session. If it is not specified the Servershall keep using the current localeIdsfor the Session.

userIdentityToken

Extensible Parameter

UserIdentityToken

The credentials of the user associated with the Clientapplication. The Serveruses these credentials to determine whether the Clientshould be allowed to activate a Sessionand what resources the Clienthas access to during this Session.

The UserIdentityTokenis an extensible parameter type defined in 7.36.

The EndpointDescription specifies what UserIdentityTokensthe Server shall accept.

Null or empty user token shall always be interpreted as anonymous.

userTokenSignature

SignatureData

If the Clientspecified a user identity token that supports digital signatures, then it shall create a signature and pass it as this parameter. Otherwise the parameter is null.

The SignatureAlgorithmdepends on the identity token type.

The SignatureDatatype is defined in 7.32.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.29for ResponseHeaderdefinition).

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 next call to ActivateSessionrequest.

results []

StatusCode

List of validation results for the SoftwareCertificates(see 7.34for StatusCodedefinition).

diagnosticInfos []

DiagnosticInfo

List of diagnostic information associated with SoftwareCertificatevalidation errors (see 7.8for DiagnosticInfo definition). 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 18defines the Serviceresults specific to this Service. Common StatusCodesare defined in Table 177.

Table 18– ActivateSession Service Result Codes

Symbolic Id

Description

Bad_IdentityTokenInvalid

See Table 177for the description of this result code.

Bad_IdentityTokenRejected

See Table 177for the description of this result code.

Bad_UserAccessDenied

See Table 177for the description of this result code.

Bad_ApplicationSignatureInvalid

The signature provided by the Clientapplication is missing or invalid.

Bad_UserSignatureInvalid

The user token signature is missing or invalid.

Bad_NoValidCertificates

The Clientdid not provide at least one Software Certificatethat is valid and meets the profile requirements for the Server.

Bad_IdentityChangeNotSupported

The Serverdoes not support changing the user identity assigned to the session.

This Serviceis used to terminate a Session. The Servertakes the following actions when it receives a CloseSessionrequest:

  1. It stops accepting requests for the Session. All subsequent requests received for the Sessionare discarded.
  2. It returns negative responses with the StatusCodeBad_SessionClosed to all requests that are currently outstanding to provide for the timely return of the CloseSessionresponse. Clientsare urged to wait for all outstanding requests to complete before submitting the CloseSessionrequest.
  3. It removes the entry for the Clientin its SessionDiagnosticsArray Variable.

When the CloseSession Service is called before the Sessionis successfully activated, the Servershall reject the request if the SecureChannelis not the same as the one associated with the CreateSessionrequest.

Table 19defines the parameters for the Service.

Table 19– CloseSession Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.28for RequestHeaderdefinition).

deleteSubscriptions

Boolean

If the value is TRUE, the Server deletes all Subscriptions associated with the Session. If the value is FALSE, the Server keeps the Subscriptions associated with the Session until they timeout based on their own lifetime.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.29for ResponseHeaderdefinition).

Table 20defines the Serviceresults specific to this Service. Common StatusCodesare defined in Table 177.

Table 20– CloseSession Service Result Codes

Symbolic Id

Description

Bad_SessionIdInvalid

See Table 177for the description of this result code.

This Serviceis used to cancel outstanding Service requests. Successfully cancelled service requests shall respond with Bad_RequestCancelledByClient.

Table 21defines the parameters for the Service.

Table 21– Cancel Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.28for RequestHeaderdefinition).

requestHandle

IntegerId

The requestHandleassigned to one or more requests that should be cancelled. All outstanding requests with the matching requestHandleshall be cancelled.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.29for ResponseHeaderdefinition).

cancelCount

UInt32

Number of cancelled requests.

Common StatusCodesare defined in Table 177.