7 Common parameter type definitions

7.1 AdditionalParametersType

The AdditionalParametersType parameter is used as value of the additionalHeader field of the RequestHeader and ResponseHeader parameters. It allows Clients and Servers to pass additional named parameters with Service requests or responses. These named parameters may be defined by the OPC UA specification, a companion specification or be specific to a vendor implementation. The name is a QualifiedName which allows the same name to be used in different contexts. The value is a Variant which allows Structures to be passed in addition to basic types such as Strings.

Note that the calls to CreateSession/ActivateSession are made before the Client can read the Server’s current NamespaceArray. This means that only names with a NamespaceIndex of 0 or 1 may be used in the requests for these Services. Companion specifications and vendors can define names in for use with NamespaceIndex 1 if they add prefix that ensures uniqueness. The same restriction applies to values which contain DataTypes with NamespaceIndexes.

The components of this structure are defined in Table 108.

7.2 ApplicationDescription

The components of this parameter are defined in Table 109.

7.3 ApplicationInstanceCertificate

An ApplicationInstanceCertificate is a ByteString containing an encoded Certificate. The encoding of an ApplicationInstanceCertificate depends on the security technology mapping and is defined completely in OPC 10000-6. Table 110 specifies the information that should be contained in an ApplicationInstanceCertificate.

7.4 ApplicationType

The ApplicationType is an enumeration that specifies the type of OPC UA Application. The possible values are described in Table 111.

7.5 BrowseDirection

The BrowseDirection is an enumeration that specifies the direction of References to follow. The possible values are described in Table 112.

7.6 BrowseResult

The components of this parameter are defined in Table 113.

7.7 ContentFilter

7.7.1 ContentFilter structure

The ContentFilter structure defines a collection of elements that define filtering criteria. Each element in the collection describes an operator and an array of operands to be used by the operator. The operators that can be used in a ContentFilter are described in Table 118. The filter is evaluated by evaluating the first entry in the element array starting with the first operand in the operand array. The operands of an element may contain References to sub-elements resulting in the evaluation continuing to the referenced elements in the element array. The evaluation shall not introduce loops. For example evaluation starting from element “A” shall never be able to return to element “A”. However there may be more than one path leading to another element “B”. If an element cannot be traced back to the starting element it is ignored. Extra operands for any operator shall result in an error. Annex B provides examples using the ContentFilter structure.

Table 114 defines the ContentFilter structure.

7.7.2 ContentFilterResult

The components of this data type are defined in Table 115.

Table 116 defines values for the StatusCode parameter that are specific to this structure. Common StatusCodes are defined in Table 179.

Table 117 defines values for the operandStatusCodes parameter that are specific to this structure. Common StatusCodes are defined in Table 179.

7.7.3 FilterOperator

Table 118 defines the basic operators that can be used in a ContentFilter. See Table 119 for a description of advanced operators. See 7.7.4 for a definition of operands.

Many operands have restrictions on their type. This requires the operand to be evaluated to determine what the type is. In some cases the type is specified in the operand (i.e. a LiteralOperand). In other cases the type requires that the value of an attribute be read. An ElementOperand evaluates to a Boolean value unless the operator is a Cast or a nested RelatedTo operator.

Operands that resolve to an ordered value are restricted to the DataTypes Byte, Int16, Int32, Int64, SByte, UInt16, UInt32, UInt64, Float, Double and DateTime.

When testing for equality, a Server shall treat null and empty arrays of the same DataType as equal. This also applies to Strings and ByteStrings.

Table 119 defines complex operators that require a target node (i.e. row) to evaluate. These operators shall be re-evaluated for each possible target node in the result set.

The RelatedTo operator can be used to identify if a given type, set as operand[1], is a subtype of another type set as operand[0] by setting operand[2] to the HasSubtype ReferenceType and operand[3] to 0.

The Like operator can be used to perform wildcard comparisons. Several special characters can be included in the second operand of the Like operator. The valid characters are defined in Table 120. The wildcard characters can be combined in a single string (i.e. ‘Th[ia][ts]%’ would match ‘That is fine’, ‘This is fine’, ‘That as one’, ‘This it is’, ‘Then at any’, etc.). The Like operator is case sensitive.

Table 121 defines the conversion rules for the operand values. The types are automatically converted if an implicit conversion exists (I). If an explicit conversion exists (E) then type can be converted with the cast operator. If no conversion exists (X) the then types cannot be converted, however, some Servers may support application specific explicit conversions. The types used in the table are defined in OPC 10000-3. A data type that is not in the table does not have any defined conversions.

Arrays of a source type can be converted to arrays of the target type by converting each element. A conversion error for any element causes the entire conversion to fail.

Arrays of length 1 can be implicitly converted to a scalar value of the same type.

Guid, NodeId and ExpandedNodeId are converted to and from String using the syntax defined in OPC 10000-6.

Floating point values are rounded by adding 0.5 and truncating when they are converted to integer values.

Converting a negative value to an unsigned type causes a conversion error. If the conversion fails the result is a null value.

Converting a value that is outside the range of the target type causes a conversion error. If the conversion fails the result is a null value.

ByteString is converted to String by formatting the bytes as a sequence of hexadecimal digits.

LocalizedText values are converted to Strings by dropping the Locale. Strings are converted to LocalizedText values by setting the Locale to “”.

QualifiedName values are converted to Strings by dropping the NamespaceIndex. Strings are converted to QualifiedName values by setting the NamespaceIndex to 0.

A StatusCode can be converted to and from a UInt32 and Int32 by copying the bits. Only the top 16-bits if the StatusCode are copied when it is converted to and from a UInt16 or Int16 value. Since Event fields can have a StatusCode instead of the expected DataType, a StatusCode can only be converted to an integer with an explicit conversion.

Boolean values are converted to ‘1’ when true and ‘0’ when false. Non zero numeric values are converted to true Boolean values. Numeric values of 0 are converted to false Boolean values. String values containing “true”, “false”, “1” or “0” can be converted to Boolean values. Other string values cause a conversion error. In this case Strings are case-insensitive.

It is sometimes possible to use implicit casts when operands with different data types are used in an operation. In this situation the precedence rules defined in Table 122 are used to determine which implicit conversion to use. The first data type in the list (top down) has the most precedence. If a data type is not in this table then it cannot be converted implicitly while evaluating an operation.

For example, assume that A = 1,1 (Float) and B = 1 (Int32) and that these values are used with an Equals operator. This operation would be evaluated by casting the Int32 value to a Float since the Float data type has more precedence.

Operands may contain null values (i.e. values which do not exist). When this happens, the element always evaluates to NULL (unless the IsNull operator has been specified).
Table 123 defines how to combine elements that evaluate to NULL with other elements in a logical AND operation.

Table 124 defines how to combine elements that evaluate to NULL with other elements in a logical OR operation.

The NOT operator always evaluates to NULL if applied to a NULL operand.

A ContentFilter which evaluates to NULL after all elements are evaluated is evaluated as FALSE.

For any fatal errors like out of memory situations, the operator either evaluates to FALSE or NULL.

7.7.4 FilterOperand parameters

7.7.4.1 Overview

The ContentFilter structure specified in 7.7 defines a collection of elements that makes up filter criteria and contains different types of FilterOperands. The FilterOperand parameter is an extensible parameter. This parameter is defined in Table 125. The ExtensibleParameter type is defined in 7.17.

7.7.4.2 ElementOperand

The ElementOperand provides the linking to sub-elements within a ContentFilter. The link is in the form of an integer that is used to index into the array of elements contained in the ContentFilter. An index is considered valid if its value is greater than the element index it is part of and it does not Reference a non-existent element. Clients shall construct filters in this way to avoid circular and invalid References. Servers should protect against invalid indexes by verifying the index prior to using it.

Table 126 defines the ElementOperand type.

7.7.4.3 LiteralOperand

Table 127 defines the LiteralOperand type.

7.7.4.4 AttributeOperand

Table 128 defines the AttributeOperand type.

7.7.4.5 SimpleAttributeOperand

The SimpleAttributeOperand is a simplified form of the AttributeOperand and all of the rules that apply to the AttributeOperand also apply to the SimpleAttributeOperand. The examples provided in B.1 only use AttributeOperand, however, the AttributeOperand can be replaced by a SimpleAttributeOperand whenever all ReferenceTypes in the RelativePath are subtypes of HierarchicalReferences and the targets are Object or Variable Nodes and an Alias is not required.

Table 129 defines the SimpleAttributeOperand type.

7.8 Counter

This primitive data type is a UInt32 that represents the value of a counter. The initial value of a counter is specified by its use. Modulus arithmetic is used for all calculations, where the modulus is max value + 1. Therefore,

x + y = (x + y)mod(max value + 1)

For example:

• max value + 1 = 0

• max value + 2 = 1

7.9 ContinuationPoint

A ContinuationPoint is used to pause a Browse, QueryFirst or HistoryRead operation and allow it to be restarted later by calling BrowseNext, QueryNext or HistoryRead. Operations are paused when the number of results found exceeds the limits set by either the Client or the Server.

The Client specifies the maximum number of results per operation in the request message. A Server shall not return more than this number of results but it may return fewer results. The Server allocates a ContinuationPoint if there are more results to return.

Servers shall support at least one ContinuationPoint per Session. Servers specify a maximum number of ContinuationPoints per Session in the ServerCapabilities Object defined in OPC 10000-5. ContinuationPoints remain active until the Client retrieves the remaining results, the Client releases the ContinuationPoint or the Session is closed. A Server shall automatically free ContinuationPoints from prior requests from a Session if they are needed to process a new request from this Session. The Server returns a Bad_ContinuationPointInvalid error if a Client tries to use a ContinuationPoint that has been released. A Client can avoid this situation by completing paused operations before starting new operations. For Session-less Service invocations, the ContinuationPoints are shared across all Session-less Service invocations from all Clients. The Server shall support at least the maximum number of ContinuationPoints it would allow for one Session. A Server may support an infinite number of ContinuationPoints by adding all information necessary to continue the operation into the ContinuationPoint. In this case the Server shall not allocate memory for a ContinuationPoint.

Requests will often specify multiple operations that may or may not require a ContinuationPoint. A Server shall process the operations until it uses the maximum number of continuation points in this response. Once that happens the Server shall return a Bad_NoContinuationPoints error for any remaining operations. A Client can avoid this situation by sending requests with a number of operations that do not exeed the maximum number of ContinuationPoints per Session defined for the Service in the ServerCapabilities Object defined in OPC 10000-5.

A Client restarts an operation by passing the ContinuationPoint back to the Server. Server should always be able to reuse the ContinuationPoint provided so Servers shall never return Bad_NoContinuationPoints error when continuing a previously halted operation.

A ContinuationPoint is a subtype of the ByteString data type.

7.10 DataChangeTrigger

The DataChangeTrigger is an enumeration that specifies the conditions under which a data change notification should be reported. The possible values are described in Table 130.

7.11 DataValue

7.11.1 General

The components of this parameter are defined in Table 131.

7.11.2 PicoSeconds

Some applications require high resolution timestamps. The PicoSeconds fields allow applications to specify timestamps with a resolution of 10 picoseconds. The actual size of the PicoSeconds field depends on the resolution of the UtcTime DataType. For example, if the UtcTime DataType has a resolution of 100 nanoseconds then the PicoSeconds field would need to store values up to 10 000 in order to provide the resolution of 10 picoseconds. The resolution of the UtcTime DataType depends on the Mappings defined in OPC 10000-6.

7.11.3 SourceTimestamp

The sourceTimestamp is used to reflect the timestamp that was applied to a Variable value by the data source. Once a value has been assigned a source timestamp, the source timestamp for that value instance never changes. In this context, “value instance” refers to the value received, independent of its actual value.

The sourceTimestamp shall be UTC time and should indicate the time of the last change of the value or statusCode.

The sourceTimestamp should be generated as close as possible to the source of the value but the timestamp needs to be set always by the same physical clock. In the case of redundant sources, the clocks of the sources should be synchronized.

If the OPC UA Server receives the Variable value from another OPC UA Server, then the OPC UA Server shall always pass the source timestamp without changes. If the source that applies the timestamp is not available, the source timestamp is set to null. For example, if a value could not be read because of some error during processing like invalid arguments passed in the request then the sourceTimestamp shall be null.

In the case of a bad or uncertain status sourceTimestamp is used to reflect the time that the source recognized the non-good status or the time the Server last tried to recover from the bad or uncertain status.

The sourceTimestamp is only returned with a Value Attribute. For all other Attributes the returned sourceTimestamp is set to null.

7.11.4 ServerTimestamp

The serverTimestamp is used to reflect the time that the Server received a Variable value or knew it to be accurate.

In the case of a bad or uncertain status, serverTimestamp is used to reflect the time that the Server received the status or that the Server last tried to recover from the bad or uncertain status.

In the case where the OPC UA Server subscribes to a value from another OPC UA Server, each Server applies its own serverTimestamp. This is in contrast to the sourceTimestamp in which only the originator of the data is allowed to apply the sourceTimestamp.

If the Server subscribes to the value from another Server every ten seconds and the value changes, then the serverTimestamp is updated each time a new value is received. If the value does not change, then new values will not be received on the Subscription. However, in the absence of errors, the receiving Server applies a new serverTimestamp every ten seconds because not receiving a value means that the value has not changed. Thus, the serverTimestamp reflects the time at which the Server knew the value to be accurate.

This concept also applies to OPC UA Servers that receive values from exception-based data sources. For example, suppose that a Server is receiving values from an exception-based device, and that

1. the device is checking values every 0,5 seconds,

2. the connection to the device is good,

3. the device sent an update 3 minutes ago with a value of 1,234.

In this case, the Server value would be 1,234 and the serverTimestamp would be updated every 0,5 seconds after the receipt of the value.

7.11.5 StatusCode assigned to a value

The StatusCode is used to indicate the conditions under which a Variable value was generated, and thereby can be used as an indicator of the usability of the value. The StatusCode is defined in 7.38.

Overall condition (severity)

• A StatusCode with severity Good means that the value is of good quality.

• A StatusCode with severity Uncertain means that the quality of the value is uncertain for reasons indicated by the SubCode.

• A StatusCode with severity Bad means that the value is not usable for reasons indicated by the SubCode.

Rules

• The StatusCode indicates the usability of the value. Therefore, It is required that Clients minimally check the StatusCode Severity of all results, even if they do not check the other fields, before accessing and using the value.

• A Server, which does not support status information, shall return a severity code of Good. It is also acceptable for a Server to simply return a severity and a non-specific (0) SubCode.

• If the Server has no known value - in particular when Severity is BAD, it shall return a NULL value. If the DataType of the Variable is not BaseDataType, the Severity shall be BAD if the value is NULL for a non-nullable Datatype. If a Variable is created and no default value or initial value is available, the StatusCode shall be Bad_NoValue.

7.12 DiagnosticInfo

The components of this parameter are defined in Table 132.

The DiagnosticInfo shall not contain any security related information.

7.13 DiscoveryConfiguration parameters

7.13.1 Overview

The DiscoveryConfiguration structure used in the RegisterServer2 Service allows Servers to provide additional configuration parameters to Discovery Servers for registration. Table 133 defines the current set of discovery configuration options. The ExtensibleParameter type is defined in 7.17.

7.13.2 MdnsDiscoveryConfiguration

Table 134 defines the MdnsDiscoveryConfiguration parameter.

7.14 EndpointDescription

The components of this parameter are defined in Table 135.

7.15 EphemeralKeyType

The EphemeralKeyType parameter is used to return an ECC EphemeralKey needed to provide encrypted data back to the owner of the key. This Structure is used in the additionalHeader with the AdditionalParametersType defined in 7.1. See OPC 10000-6 for a discussion of ECC EphemeralKeys. The EphemeralKey is created based on an ECC named curve specified by a SecurityPolicy. The SecurityPolicy to use depends on the context in which this parameter is used.

The components of this structure are defined in Table 136.

7.16 ExpandedNodeId

The components of this parameter are defined in Table 137. ExpandedNodeId allows the namespace to be specified explicitly as a string or with an index in the Server's namespace table.

7.17 ExtensibleParameter

The extensible parameter types can only be extended by additional parts of OPC 10000.

The ExtensibleParameter defines a data structure with two elements. The parameterTypeId specifies the data type encoding of the second element. Therefore the second element is specified as “--”. The ExtensibleParameter base type is defined in Table 138.

Concrete extensible parameters that are common to OPC UA are defined in Clause 7. Additional parts of OPC 10000 can define additional extensible parameter types.

7.18 Index

This primitive data type is a UInt32 that identifies an element of an array.

7.19 IntegerId

This primitive data type is a UInt32 that is used as an identifier, such as a handle. All values, except for 0, are valid.

7.20 MessageSecurityMode

The MessageSecurityMode is an enumeration that specifies what security should be applied to messages exchanges during a Session. The possible values are described in Table 139.

7.21 MonitoringParameters

The components of this parameter are defined in Table 140.

7.22 MonitoringFilter parameters

7.22.1 Overview

The CreateMonitoredItem Service allows specifying a filter for each MonitoredItem. The MonitoringFilter is an extensible parameter whose structure depends on the type of item being monitored. The parameterTypeIds are defined in Table 141. Other types can be defined by additional parts of this multi-part specification or other specifications based on OPC UA. The ExtensibleParameter type is defined in 7.17.

Each MonitoringFilter may have an associated MonitoringFilterResult structure which returns revised parameters and/or error information to Clients in the response. The result structures, when they exist, are described in the section that defines the MonitoringFilter.

7.22.2 DataChangeFilter

The DataChangeFilter defines the conditions under which a DataChange Notification should be reported and, optionally, a range or band for value changes where no DataChange Notification is generated. This range is called Deadband. The DataChangeFilter is defined in Table 142.

The DataChangeFilter does not have an associated result structure.

7.22.3 EventFilter

The EventFilter provides for the filtering and content selection of Event Subscriptions.

If an Event Notification conforms to the filter defined by the where parameter of the EventFilter, then the Notification is sent to the Client.

Each Event Notification shall include the fields defined by the selectClauses parameter of the EventFilter. The defined EventTypes are specified in OPC 10000-5.

The selectClauses and whereClause parameters are specified with the SimpleAttributeOperand structure (see 7.7.4.5). This structure requires the NodeId of an EventType supported by the Server and a path to an InstanceDeclaration. An InstanceDeclaration is a Node which can be found by following forward hierarchical references from the fully inherited EventType where the Node is also the source of a HasModellingRule reference. EventTypes, InstanceDeclarations and Modelling Rules are described completely in OPC 10000-3.

In some cases the same SimpleAttributeOperand.browsePath will apply to multiple EventTypes. If the Client specifies the BaseEventType in the SimpleAttributeOperand.typeDefinitionId then the Server shall evaluate the SimpleAttributeOperand.browsePath without considering the SimpleAttributeOperand.typeDefinitionId.

Each InstanceDeclaration in the path shall be Object or Variable Node. The final Node in the path may be an Object Node; however, Object Nodes are only available for Events which are visible in the Server’s AddressSpace.

The SimpleAttributeOperand structure allows the Client to specify any Attribute; however, the Server is only required to support the Value Attribute for Variable Nodes and the NodeId Attribute for Object Nodes. That said, profiles defined in OPC 10000-7 may make support for additional Attributes mandatory.

The SimpleAttributeOperand structure is used in the selectClauses to select the value to return if an Event meets the criteria specified by the whereClause. A null value is returned in the corresponding event field in the Publish response if the selected field is not part of the Event or an error was returned in the selectClauseResults of the EventFilterResult. If the selected field is supported but not available at the time of the event notification, the event field shall contain a StatusCode that indicates the reason for the unavailability. For example, the Server shall set the event field to Bad_UserAccessDenied if the value is not accessible to the user associated with the Session. If a Value Attribute has an uncertain or bad StatusCode associated with it then the Server shall provide the StatusCode instead of the Value Attribute. The Server shall set the event field to Bad_EncodingLimitsExceeded if a value exceeds the maxResponseMessageSize. The EventId, EventType and ReceiveTime cannot contain a StatusCode or a null value.

The Server shall validate the selectClauses when a Client creates or updates the EventFilter. Any errors which are true for all possible Events are returned in the selectClauseResults parameter described in Table 144. Some Servers, like aggregating Servers, may not know all possible EventTypes at the time the EventFilter is set. These Servers do not return errors for unknown EventTypes or BrowsePaths. The Server shall not report errors that might occur depending on the state or the Server or type of Event. For example, a selectClauses that requests a single element in an array would always produce an error if the DataType of the Attribute is a scalar. However, even if the DataType is an array an error could occur if the requested index does not exist for a particular Event, the Server would not report an error in the selectClauseResults parameter if the latter situation existed.

The SimpleAttributeOperand is used in the whereClause to select a value which forms part of a logical expression. These logical expressions are then used to determine whether a particular Event should be reported to the Client. The Server shall use a null value if any error occurs when a whereClause is evaluated for a particular Event. If a Value Attribute has an uncertain or bad StatusCode associated with it, then the Server shall use a null value instead of the Value.

Any basic FilterOperator in Table 118 may be used in the whereClause, however, only the OfType FilterOperator from Table 119 is permitted.

The Server shall validate the whereClause when a Client creates or updates the EventFilter. Any structural errors in the construction of the filter and any errors which are true for all possible Events are returned in the whereClauseResult parameter described in Table 144. Errors that could occur depending on the state of the Server or the Event are not reported. Some Servers, like aggregating Servers, may not know all possible EventTypes at the time the EventFilter is set. These Servers do not return errors for unknown EventTypes or BrowsePaths.

EventQueueOverflowEventType Events are special Events which are used to provide control information to the Client. These Events are only published to the MonitoredItems in the Subscription that produced the EventQueueOverflowEventType Event. These Events bypass the whereClause.

Table 143 defines the EventFilter structure.

Table 144 defines the EventFilterResult structure. This is the MonitoringFilterResult associated with the EventFilter MonitoringFilter.

Table 145 defines values for the selectClauseResults parameter. Common StatusCodes are defined in Table 179.

7.22.4 AggregateFilter

The AggregateFilter defines the Aggregate function that should be used to calculate the values to be returned. See OPC 10000-13 for details on possible Aggregate functions. It specifies a startTime of the first Aggregate to be calculated. The samplingInterval of the MonitoringParameters (see 7.21) defines how the Server should internally sample the underlying data source. The processingInterval specifies the size of a time-period where the Aggregate is calculated. The queueSize from the MonitoringAttributes specifies the number of processed values that should be kept.

The intention of the AggregateFilter is not to read historical data, the HistoryRead service should be used for this purpose. However, it is allowed that the startTime is set to a time that is in the past when received from the Server. The number of Aggregates to be calculated in the past should not exceed the queueSize defined in the MonitoringAttributes since the values exceeding the queueSize would directly be discharged and never returned to the Client.

The startTime and the processingInterval can be revised by the Server, but the startTime should remain in the same boundary (startTime + revisedProcessingInterval * n = revisedStartTime). That behaviour simplifies accessing historical values of the Aggregates using the same boundaries by calling the HistoryRead service. The extensible Parameter AggregateFilterResult is used to return the revised values for the AggregateFilter.

Some underlying systems may poll data and produce multiple samples with the same value. Other systems may only report changes to the values. The definition for each Aggregate type explains how to handle the two different scenarios.

The MonitoredItem only reports values for intervals that have completed when the publish timer expires. Unused data is carried over and used to calculate a value returned in the next publish.

The ServerTimestamp for each interval shall be the time of the end of the processing interval.

The AggregateFilter is defined in Table 146.

The AggregateFilterResult defines the revised AggregateFilter the Server can return when an AggregateFilter is defined for a MonitoredItem in the CreateMonitoredItems or ModifyMonitoredItems Services. The AggregateFilterResult is defined in Table 147. This is the MonitoringFilterResult associated with the AggregateFilter MonitoringFilter.

7.23 MonitoringMode

The MonitoringMode is an enumeration that specifies whether sampling and reporting are enabled or disabled for a MonitoredItem. The value of the publishing enabled parameter for a Subscription does not affect the value of the monitoring mode for a MonitoredItem of the Subscription. The values of this parameter are defined in Table 148.

7.24 NodeAttributes parameters

7.24.1 Overview

The AddNodes Service allows specifying the Attributes for the Nodes to add. The NodeAttributes is an extensible parameter whose structure depends on the type of the NodeClass being added. It identifies the NodeClass that defines the structure of the Attributes that follow. The parameterTypeIds are defined in Table 149. The ExtensibleParameter type is defined in 7.17.

Table 150 defines the bit mask used in the NodeAttributes parameters to specify which Attributes are set by the Client.

7.24.2 ObjectAttributes parameter

Table 151 defines the ObjectAttributes parameter.

7.24.3 VariableAttributes parameter

Table 152 defines the VariableAttributes parameter.

7.24.4 MethodAttributes parameter

Table 153 defines the MethodAttributes parameter.

7.24.5 ObjectTypeAttributes parameter

Table 154 defines the ObjectTypeAttributes parameter.

7.24.6 VariableTypeAttributes parameter

Table 155 defines the VariableTypeAttributes parameter.

7.24.7 ReferenceTypeAttributes parameter

Table 156 defines the ReferenceTypeAttributes parameter.

7.24.8 DataTypeAttributes parameter

Table 157 defines the DataTypeAttributes parameter.

7.24.9 ViewAttributes parameter

Table 158 defines the ViewAttributes parameter.

7.24.10 GenericAttributes parameter

This structure should be used instead of the NodeClass specific structures defined in the other sub sections of 7.24 since it allows the handling of additional Attributes defined in future specification versions.

Table 159 defines the GenericAttributes parameter.

7.25 NotificationData parameters

7.25.1 Overview

The NotificationMessage structure used in the Subscription Service set allows specifying different types of NotificationData. The NotificationData parameter is an extensible parameter whose structure depends on the type of Notification being sent. This parameter is defined in Table 160. Other types can be defined by additional parts of OPC 10000 or other specifications based on OPC UA. The ExtensibleParameter type is defined in 7.17.

There may be multiple notifications for a single MonitoredItem in a single NotificationData structure. When that happens the Server shall ensure the notifications appear in the same order that they were queued in the MonitoredItem. These notifications do not need to appear as a contiguous block.

7.25.2 DataChangeNotification parameter

Table 161 defines the NotificationData parameter used for data change notifications. This structure contains the monitored data items that are to be reported. Monitored data items are reported under two conditions:

1. if the MonitoringMode is set to REPORTING and a change in value or its status (represented by its StatusCode) is detected;

2. if the MonitoringMode is set to SAMPLING, the MonitoredItem is linked to a triggering item and the triggering item triggers.

See 5.13 for a description of the MonitoredItem Service set, and in particular the MonitoredItem model and the Triggering model.

After creating a MonitoredItem, the current value or status of the monitored Attribute shall be queued without applying the filter. If the current value is not available after the first sampling interval the first Notification shall be queued after getting the initial value or status from the data source.

7.25.3 EventNotificationList parameter

Table 162 defines the NotificationData parameter used for Event notifications.

The EventNotificationList defines a table structure that is used to return Event fields to a Client Subscription. The structure is in the form of a table consisting of one or more Events, each containing an array of one or more fields. The selection and order of the fields returned for each Event is identical to the selected parameter of the EventFilter.

7.25.4 StatusChangeNotification parameter

Table 163 defines the NotificationData parameter used for a StatusChangeNotification.

The StatusChangeNotification informs the Client about a change in the status of a Subscription.

7.26 NotificationMessage

The components of this parameter are defined in Table 164.

7.27 NumericRange

This parameter is defined in Table 165. A formal BNF definition of the numeric range can be found in Clause A.3. Examples for the use of the parameter are shown in Table 166.

The syntax for the string contains one of the following two constructs. The first construct is the string representation of an individual integer. For example, “6” is valid, but “6,0” and “3,2” are not. The minimum and maximum values that can be expressed are defined by the use of this parameter and not by this parameter type definition. The second construct is a range represented by two integers separated by the colon (“:”) character. The first integer shall always have a lower value than the second. For example, “5:7” is valid, while “7:5” and “5:5” are not. The minimum and maximum values that can be expressed by these integers are defined by the use of this parameter, and not by this parameter type definition. No other characters, including white-space characters, are permitted.

Multi-dimensional arrays can be indexed by specifying a range for each dimension separated by a ‘,’. For example, a 2x2 block in a 4x4 matrix could be selected with the range “1:2,0:1”. A single element in a multi-dimensional array can be selected by specifying a single number instead of a range. For example, “1,1” selects the [1,1] element in a two dimensional array.

Dimensions are specified in the order that they appear in the ArrayDimensions Attribute. All dimensions shall be specified for a NumericRange to be valid.

All indexes start with 0. The maximum value for any index is one less than the length of the dimension.

When reading a value and any of the lower bounds of the indexes is out of range the Server shall return a Bad_IndexRangeNoData. If any of the upper bounds of the indexes is out of range, the Server shall return partial results. For arrays of the ByteStrings and Strings find more details in the paragraphs below.

Bad_IndexRangeInvalid is only used for invalid syntax of the NumericRange. All other invalid requests with a valid syntax shall result in Bad_IndexRangeNoData.

When writing a value, the size of the array shall match the size specified by the NumericRange. The Server shall return an error if it cannot write all elements specified by the Client.

The NumericRange can also be used to specify substrings for ByteString and String values. Arrays of ByteString and String values are treated as two dimensional arrays where the final index specifies the substring range within the ByteString or String value. The entire ByteString or String value is selected if the final index is omitted. If the last element of the specified IndexRange refers to a substring, the Server shall return partial results accordingly. For any element in the array where the lower and upper bound of the specified IndexRange for the substring are out of bounds, the Server shall return a null or empty value.

7.28 ReadValueId

The components of this parameter are defined in Table 167.

7.29 ReferenceDescription

The components of this parameter are defined in Table 168.

7.30 RelativePath

The components of this parameter are defined in Table 169.

A RelativePath can be applied to any starting Node. The targets of the RelativePath are the set of Nodes that are found by sequentially following the elements in RelativePath.

A text format for the RelativePath can be found in Clause A.2. This format is used in examples that explain the Services that make use of the RelativePath structure.

7.31 RegisteredServer

The components of this parameter are defined in Table 170.

7.32 RequestHeader

The components of this parameter are defined in Table 171.

7.33 ResponseHeader

The components of this parameter are defined in Table 172.

7.34 ServiceFault

The components of this parameter are defined in Table 173.

The ServiceFault parameter shall be returned instead of the Service response message when the serviceResult is a StatusCode with Severity Bad. The requestHandle in the ResponseHeader should be set to what was provided in the RequestHeader even if these values were not valid. The level of diagnostics returned in the ResponseHeader is specified by the returnDiagnostics parameter in the RequestHeader.

7.35 SessionAuthenticationToken

The SessionAuthenticationToken type is an opaque identifier that is used to identify requests associated with a particular Session. This identifier is used in conjunction with the SecureChannelId or Client Certificate to authenticate incoming messages. It is the secret form of the sessionId for internal use in the Client and Server Applications. The SessionAuthenticationToken is a subtype of NodeId.

A Server returns a SessionAuthenticationToken in the CreateSession response. The Client then sends this value with every request which allows the Server to verify that the sender of the request is the same as the sender of the original CreateSession request.

For the purposes of this discussion, a Server consists of application (code) and a Communication Stack as shown in Figure 37.

The security provided by the SessionAuthenticationToken depends on a trust relationship between the Server application and the Communication Stack. The Communication Stack shall be able to verify the sender of the message and it uses the SecureChannelId or the Client Certificate to identify the sender to the Server. In these cases, the SessionAuthenticationToken is a NodeId with a UInt32 identifier that allows the Server to distinguish between different Sessions created by the same sender.

In some cases, the application and the Communication Stack cannot exchange information at runtime which means the application will not have access to the SecureChannelId or the Certificate used to create the SecureChannel. In these cases the application shall create a random ByteString value that is at least 32 bytes long. This value shall be kept secret and shall always be exchanged over a SecureChannel with encryption enabled. The Administrator is responsible for ensuring that encryption is enabled. In this cases, the SessionAuthenticationToken is a NodeId with a ByteString identifier. The Profiles in OPC 10000-7 may define additional requirements for a ByteString SessionAuthenticationToken.

Client and Server applications should be written to be independent of the SecureChannel implementation. Therefore, they should always treat the SessionAuthenticationToken as secret information even if it is not required when using some SecureChannel implementations.

Figure 38 illustrates the information exchanged between the Client, the Server and the Server Communication Stack when the Client obtains a SessionAuthenticationToken. In this figure the GetSecureChannelInfo step represents an API that depends on the Communication Stack implementation.

The SessionAuthenticationToken is a subtype of the NodeId data type; however, it is never used to identify a Node in the AddressSpace. Servers may assign a value to the NamespaceIndex; however, its meaning is Server specific.

7.36 SignatureData

The components of this parameter are defined in Table 174.

7.37 SignedSoftwareCertificate

Table 175 specifies SignedSoftwareCertificate Structure.

7.38 StatusCode

7.38.1 General

A StatusCode in OPC UA is numerical value that is used to report the outcome of an operation performed by an OPC UA Server. This code may have associated diagnostic information that describes the status in more detail; however, the code by itself is intended to provide Client applications with enough information to make decisions on how to process the results of an OPC UA Service.

The StatusCode is a 32-bit unsigned integer. The top 16 bits represent the numeric value of the code that shall be used for detecting specific errors or conditions. The bottom 16 bits are bit flags that contain additional information but do not affect the meaning of the StatusCode.

All OPC UA Clients shall always check the StatusCode associated with a result before using it. Results that have an uncertain/warning status associated with them shall be used with care since these results might not be valid in all situations. Results with a bad/failed status shall never be used.

OPC UA Servers should return good/success StatusCodes if the operation completed normally and the result is always valid. Different StatusCode values can provide additional information to the Client.

OPC UA Servers should use uncertain/warning StatusCodes if they could not complete the operation in the manner requested by the Client, however, the operation did not fail entirely.

The list of StatusCodes is managed by OPC UA. The complete list of StatusCodes is defined in OPC 10000-6. Servers shall not define their own StatusCodes. OPC UA companion working groups may request additional StatusCodes from the OPC Foundation to be added to the list in OPC 10000-6.

The exact bit assignments are shown in Table 176.

Table 177 describes the structure of the InfoBits when the Info Type is set to DataValue (01).

7.38.2 Common StatusCodes

Table 178 defines the common StatusCodes for all Service results used in more than one service. It does not provide a complete list. These StatusCodes may also be used as operation level result code. OPC 10000-6 maps the symbolic names to a numeric value and provides a complete list of StatusCodes including codes defines in other parts.

Table 179 defines the common StatusCodes for all operation level results used in more than one service. It does not provide a complete list. OPC 10000-6 maps the symbolic names to a numeric value and provides a complete list of StatusCodes including codes defines in other parts. The common Service result codes can be also contained in the operation level.

7.39 TimestampsToReturn

The TimestampsToReturn is an enumeration that specifies the Timestamp Attributes to be transmitted for MonitoredItems or Nodes in Read and HistoryRead. The values of this parameter are defined in Table 180.

7.40 UserIdentityToken parameters

7.40.1 Overview

The UserIdentityToken structure used in the Server Service Set allows Clients to specify the identity of the user they are acting on behalf of. The exact mechanism used to identify users depends on the system configuration. The different types of identity tokens are based on the most common mechanisms that are used in systems today. Table 181 defines the current set of user identity tokens. The ExtensibleParameter type is defined in 7.17.

7.40.2 Token Encryption and Proof of Possession

7.40.2.1 Overview

The Client shall always prove possession of a UserIdentityToken when it passes it to the Server. Some tokens include a secret such as a password which the Server will accept as proof. In order to protect these secrets, the Token may be encrypted before it is passed to the Server. Other types of tokens allow the Client to create a signature with the secret associated with the Token. In these cases, the Client proves possession of a UserIdentityToken by creating a signature with the secret and passing it to the Server.

Each UserIdentityToken allowed by an Endpoint shall have a UserTokenPolicy specified in the EndpointDescription. The UserTokenPolicy specifies what SecurityPolicy to use when encrypting or signing. If this SecurityPolicy is null or empty then the Client uses the SecurityPolicy in the EndpointDescription. If the matching SecurityPolicy is set to None then no encryption or signature is required. The possible SecurityPolicies are defined in OPC 10000-7.

It is recommended that applications never set the SecurityPolicy to None for UserIdentityTokens that include a secret because these secrets could be used by an attacker to gain access to the system.

Clients shall validate the Server Certificate and ensure it is trusted before sending a UserIdentityToken encrypted with the Certificate.

The encrypted secret and Signature are embedded in a ByteString which is part of the UserIdentityToken. The format of this ByteString depends on the type of UserIdentityToken and the SecurityPolicy.

The legacy token secret format defined in 7.40.2.2 is not extensible and provides only encryption but the encrypted data is not signed. It is used together with the USERNAME UserIdentityToken. The password secret exchanged with this format shall not exceed 64 bytes. If the password exceeds 64 bytes, the EncryptedSecret format shall be used or the clear text password is sent over a SecureChannel that is encrypted.

The EncryptedSecret format defined in 7.40.2.3 provides an extensible secret format together with the definition how the secret is signed and encrypted. It allows for the layout to be updated as new token types are defined or new SecurityPolicies are added.

The EncryptedSecret format starts with a TypeId, EncodingMask and Length. These values allow a Server to determine how to handle the secret. If the TypeId does not resolve to one of the defined EncryptedSecret format DataTypes and a USERNAME UserIdentityToken has been provided then the Server may attempt to handle the secret using the legacy token secret format.

The UserIdentityToken types and the token formats supported by the Endpoint are identified by the UserTokenPolicy defined in 7.41.

To prevent the leakage of information useful to attackers, Servers shall ensure that the process of validating UserIdentityTokens completes in a fixed interval independent of whether an error occurs or not. The process of validation includes decrypting, check for padding and checking for a valid nonce. If any errors occur the return code is Bad_IdentityTokenInvalid.

Servers shall log details of any failure to validate a UserIdentityToken and shall lock out Client applications after five failures.

7.40.2.2 Legacy Encrypted Token Secret Format

When encrypting a UserIdentityToken, the Client appends the last ServerNonce to the secret. The data is then encrypted with the public key from the Server’s Certificate.

A Client should not add any padding after the secret. If a Client adds padding then all bytes shall be zero. A Server shall check for padding added by Clients and ensure that all padding bytes are zeros. Servers shall reject UserIdentityTokens with invalid padding. Administrators shall be able to configure Servers to accept UserIdentityTokens with invalid padding.

If no encryption is applied, the structure is not used and only the secret without any Nonce is passed to the Server.

Table 182 describes how to serialize UserIdentityTokens before applying encryption.

7.40.2.3 EncryptedSecret Format

The EncryptedSecret uses an extensible format which has the TypeId of a DataType Node as a prefix as defined for the ExtensionObject encoding in OPC 10000-6. The general layout of the EncryptedSecret is shown in Figure 39.

The TypeId specifies how the EncryptedSecret is serialized and secured. For example, the RsaEncryptedSecret requires that the KeyData be encrypted with the public key associated with the EncryptingCertificate before it is serialized.

The SecurityPolicyUri is used to determine what algorithms were used to encrypt and sign the data. Valid SecurityPolicyUris are defined in OPC 10000-7.

The payload is always encrypted using the symmetric encryption algorithm specified by the SecurityPolicyUri. The KeyData provides the keys needed for symmetric encryption. The structure of the KeyData depends on the EncryptedSecret DataType.

The EncryptedSecret is secured and serialized as follows:

Serialize the common header;

Serialize the KeyData;

If required, encrypt the KeyData and append the result to the common header;

Update the KeyDataLength with the length of the encrypted KeyData;

Append the Nonce and the Secret to the encrypted KeyData;

Calculate padding required on the payload and append after the Secret;

Encrypt the payload;

Calculate a Signature;

Append the Signature.

Individual fields are serialized using the UA Binary encoding (see OPC 10000-6) for the DataType specified in Table 183. The Padding is used to ensure there is enough data to fill an integer multiple of encryption blocks. The size of the encryption block depends on the encryption algorithm. The total length of the Padding, not including the PaddingSize, is encoded as a UInt16. The individual bytes of the Padding are set to the least significant byte of the PaddingSize.

The EncryptedSecret is deserilized and validated as follows:

Deserialize the common header;

Verify the Signature if the KeyData is not encrypted;

Decrypt the KeyData and verify the Signature if the KeyData is encrypted;

Decrypt the payload;

Verify the padding on the payload;

Extract the Secret;

The fields in the EncryptedSecret are described in Table 183. The first three fields TypeId, EncodingMask and Length belong to the ExtensionObject encoding defined in OPC 10000-6.

The currently available EncryptedSecret DataTypes are defined in Table 184.

7.40.2.4 RsaEncryptedSecret DataType

The RsaEncryptedSecret uses RSA based Asymmetric Cryptography.

Additional semantics for the fields in the EncryptedSecret layout for the RsaEncryptedSecret Structure are described in Table 185.

7.40.2.5 EccEncryptedSecret DataType

The EccEncryptedSecret uses ECC based Asymmetric Cryptography.

Additional semantics for the fields in the EncryptedSecret layout for the EccEncryptedSecret Structure are described in Table 186.

The EccEncryptedSecret uses ECC or RSA Diffie-Hellman (RSA-DH) Finite Field Group EphemeralKeys to create the symmetric key used to encrypt the Secret. The handshake required to create and use the EphemeralKeys is described in OPC 10000-6.

7.40.3 AnonymousIdentityToken

The AnonymousIdentityToken is used to indicate that the Client has no user credentials.

Table 187 defines the AnonymousIdentityToken parameter.

7.40.4 UserNameIdentityToken

The UserNameIdentityToken is used to pass simple username/password credentials to the Server.

This token shall be encrypted by the Client if required by the SecurityPolicy of the UserTokenPolicy. The Server should specify a SecurityPolicy for the UserTokenPolicy if the SecureChannel has a SecurityPolicy of None and no transport layer encryption is available. If None is specified for the UserTokenPolicy and SecurityPolicy is None then the password only contains the UTF-8 encoded password. The SecurityPolicy of the SecureChannel is used if no SecurityPolicy is specified in the UserTokenPolicy. The Server shall specify a SecurityPolicy for the UserTokenPolicy if the SecureChannel has a SecurityPolicy other than None and the MessageSecurityMode is not SIGNANDENCRYPT. See Table 189 for possible combinations.

If the token is to be encrypted the password shall be converted to a UTF-8 ByteString, encrypted and then serialized according to the following rules. When using an RSA based SecurityPolicy and the password exceeds 64 bytes, it is encrypted and serialized as described in 7.40.2.4. For passwords that do not exceed 64 bytes, it is encrypted and serialized as described in 7.40.2.2. When using the ECC based SecurityPolicies the password is encrypted and serialized as described in 7.40.2.5.

The Server shall decrypt the password and verify the ServerNonce.

If the SecurityPolicy is None then the password only contains the UTF-8 encoded password. This configuration should not be used unless the network traffic is encrypted in some other manner such as a VPN. The use of this configuration without network encryption would result in a serious security fault, in that it would cause the appearance of a secure user access, but it would make the password visible in clear text.

Table 188 defines the UserNameIdentityToken parameter.

Table 189 describes the dependencies for selecting the AsymmetricEncryptionAlgorithm for the UserNameIdentityToken and IssuedIdentityToken. The SecureChannel SecurityPolicy URI is specified in the EndpointDescription and used in subsequent OpenSecureChannel requests. The UserTokenPolicy SecurityPolicy URI is specified in the EndpointDescription. The encryptionAlgorithm is specified in the UserNameIdentityToken or IssuedIdentityToken provided by the Client in the ActivateSession call. The SecurityPolicy Other in the table refers to any SecurityPolicy other than None. The selection of the EncryptionAlgorithm is based on the UserTokenPolicy. The SecureChannel SecurityPolicy is used if the UserTokenPolicy is null or empty. If the SecurityMode is not NONE, it is recommended to use the same SecurityPolicy for the SecureChannel and the user token.

7.40.5 X509IdentityTokens

The X509IdentityToken is used to pass an X.509 v3 Certificate which is issued by the user.

This token shall always be accompanied by a Signature in the userTokenSignature parameter of ActivateSession if required by the SecurityPolicy. The Server should specify a SecurityPolicy for the UserTokenPolicy if the SecureChannel has a SecurityPolicy of None.

The Server shall specify a SecurityPolicy for any UserTokenPolicy if the Server supports multiple CertificateKeyAlgorithms for SecureChannels and/or UserTokenPolicies. In addition, the Server shall provide a distinct UserTokenPolicy for each CertificateKeyAlgorithm supported.

X509IdentityTokens have an validity period and a Server shall invalidate the credentials of the Session within a configurable time after the token expires. The Session shall stay valid with the Anonymous Role. If the Server does not allow anonymous users, it should close the Session. Clients should renew the token with ActivateSession before the expiration time to avoid communication interruption or other operation failures.

Table 190 defines the X509IdentityToken parameter.

7.40.6 IssuedIdentityToken

The IssuedIdentityToken is used to pass SecurityTokens issued by an external Authorization Service to the Server. These tokens may be text or binary.

OAuth2 defines a standard for Authorization Services that produce JSON Web Tokens (JWT). These JWTs are passed as an Issued Token to an OPC UA Server which uses the signature contained in the JWT to validate the token. OPC 10000-6 describes OAuth2 and JWTs in more detail. If the token is encrypted, it shall use the EncryptedSecret format defined in 7.40.2.3.

This token shall be encrypted by the Client if required by the SecurityPolicy of the UserTokenPolicy. The Server should specify a SecurityPolicy for the UserTokenPolicy if the SecureChannel has a SecurityPolicy of None and no transport layer encryption is available. The SecurityPolicy of the SecureChannel is used If no SecurityPolicy is specified in the UserTokenPolicy.

If the SecurityPolicy is not None, the tokenData shall be encoded in UTF-8 (if it is not already binary), signed and encrypted according the rules specified for the tokenType of the associated UserTokenPolicy (see 7.41).

If the SecurityPolicy is None then the tokenData only contains the UTF-8 encoded tokenData. This configuration should not be used unless the network is encrypted in some other manner such as a VPN. The use of this configuration without network encryption would result in a serious security fault, in that it would cause the appearance of a secure user access, but it would make the token visible in clear text.

IssuedIdentityTokens have an expiration time, and a Server shall invalidate the credentials of the Session within a configurable time after the token expires. The Session shall stay valid with the Anonymous Role. If the Server does not allow anonymous users, it should close the Session. Clients should renew the token with ActivateSession before the expiration time to avoid communication interruption or other operation failures.

Table 191 defines the IssuedIdentityToken parameter.

7.41 UserTokenPolicy

The components of this parameter are defined in Table 192.

When a UserTokenPolicy is returned in an EndpointDescription all of the information needed to use that UserTokenPolicy shall be in the EndpointDescription. For example, a UserTokenPolicy requiring RSA based encryption algorithms can only be returned in EndpointDescription with an RSA ServerCertificate.

If the SecurityMode is None, SecurityPolicies based on ECC or RSA_DH are not allowed and Clients shall not use UserTokenPolicies that require encryption with these SecurityPolicies. RSA based SecurityPolicies are allowed, however, the Client shall only use a ServerCertificate which it trusts to encrypt UserIdentityTokens with tokenType USERNAME or ISSUEDTOKEN.

If the SecurityMode is not None, USERNAME and ISSUEDTOKEN UserTokenPolicies should specify the same SecurityPolicy as the EndpointDescription or should not explicitly specify a SecurityPolicy. If a SecurityPolicy is specified, it shall use the same PublicKey algorithm as the SecureChannel. An EndpointDescription shall have no more than one USERNAME UserTokenPolicy and no more than one ISSUEDTOKEN UserTokenPolicy for each unique issuerEndpointUrl.

If the tokenType is CERTIFICATE, the securityPolicyUri may be any valid SecurityPolicy. The choice of SecurityPolicy is system specific and depends on the infrastructure that issue the Certificates to users. If the system supports multiple PublicKey algorithms for user Certificates then the Server returns multiple CERTIFICATE UserTokenPolicies in the EndpointDescriptions.

7.42 UserTokenType

The UserTokenType is an enumeration that specifies the user identity token type. The possible values are described in Table 193.