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 112.
Table 112 – AdditionalParametersType
|
Name |
Type |
Description |
|
AdditionalParametersType |
structure |
Specifies a list of value qualified by a name. |
|
parameters |
KeyValuePair [] |
A list of headers identified by a QualifiedName. The KeyValuePair type is defined in OPC 10000-5. |
The components of this parameter are defined in Table 113.
Table 113 – ApplicationDescription
|
Name |
Type |
Description |
|
ApplicationDescription |
structure |
Specifies an application that is available. |
|
applicationUri |
String |
The globally unique identifier for the application instance. This URI is used as ServerUri in Services if the application is a Server. |
|
productUri |
String |
The globally unique identifier for the product. |
|
applicationName |
LocalizedText |
A localized descriptive name for the application. |
|
applicationType |
Enum ApplicationType |
The type of application. The ApplicationType enumeration is defined in 7.4. |
|
gatewayServerUri |
String |
A URI that identifies the Gateway Server associated with the discoveryUrls. This value is null or empty if the Server can be accessed directly. This field is not used if the applicationType is CLIENT. |
|
discoveryProfileUri |
String |
A URI that identifies the discovery profile supported by the URLs provided. This field is not used if the applicationType is CLIENT. If this value is null or empty then the Endpoints shall support the Discovery Services defined in 5.5. Alternate discovery profiles are defined in OPC 10000-7. |
|
discoveryUrls [] |
String |
A list of URLs for the DiscoveryEndpoints provided by the application. If the applicationType is CLIENT, this field shall contain an empty list. |
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 114 specifies the information that should be contained in an ApplicationInstanceCertificate.
Table 114 – ApplicationInstanceCertificate
|
Name |
Type |
Description |
|
ApplicationInstanceCertificate |
structure |
ApplicationInstanceCertificate with signature created by a Certificate Authority. |
|
version |
String |
An identifier for the version of the Certificate encoding. |
|
serialNumber |
ByteString |
A unique identifier for the Certificate assigned by the Issuer. |
|
signatureAlgorithm |
String |
The algorithm used to sign the Certificate. The syntax of this field depends on the Certificate encoding. |
|
signature |
ByteString |
The signature created by the Issuer. |
|
issuer |
Structure |
A name that identifies the Issuer Certificate used to create the signature. |
|
validFrom |
UtcTime |
When the Certificate becomes valid. |
|
validTo |
UtcTime |
When the Certificate expires. |
|
subject |
Structure |
A name that identifies the application instance that the Certificate describes. This field should contain the productName and the name of the organization responsible for the application instance. |
|
applicationUri |
String |
The applicationUri specified in the ApplicationDescription. The ApplicationDescription is described in 7.2. |
|
hostnames [] |
String |
The name of the machine where the application instance runs. A machine may have multiple names if is accessible via multiple networks. The hostname may be a numeric network address or a descriptive name. Server Certificates should have at least one hostname defined. |
|
publicKey |
ByteString |
The public key associated with the Certificate. |
|
keyUsage [] |
String |
Specifies how the Certificate key may be used. ApplicationInstanceCertificates should support Digital Signature, Non-Repudiation Key Encryption, Data Encryption and Client/Server Authorization. The contents of this field depend on the Certificate encoding. |
The ApplicationType is an enumeration that specifies the type of OPC UA Application. The possible values are described in Table 115.
Table 115 – ApplicationType values
|
Name |
Value |
Description |
|
SERVER |
0 |
The application is a Server. |
|
CLIENT |
1 |
The application is a Client. |
|
CLIENTANDSERVER |
2 |
|
|
DISCOVERYSERVER |
3 |
The application is a DiscoveryServer. |
The BrowseDirection is an enumeration that specifies the direction of References to follow. The possible values are described in Table 116.
Table 116 – BrowseDirection values
|
Name |
Value |
Description |
|
FORWARD |
0 |
Select only forward References. |
|
INVERSE |
1 |
Select only inverse References. |
|
BOTH |
2 |
Select forward and inverse References. |
|
INVALID |
3 |
No value specified. |
The components of this parameter are defined in Table 117.
|
Name |
Type |
Description |
|
BrowseResult |
structure |
The results of a Browse operation. |
|
statusCode |
StatusCode |
The status for the BrowseDescription. This value is set to Good if there are still references to return for the BrowseDescription. |
|
continuationPoint |
ContinuationPoint |
A Server defined opaque value that identifies the continuation point. The ContinuationPoint type is defined in 7.9. |
|
References [] |
ReferenceDescription |
The set of references that meet the criteria specified in the BrowseDescription. Empty, if no References met the criteria. The Reference Description type is defined in 7.30. |
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 122. 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 118 defines the ContentFilter structure.
Table 118 – ContentFilter structure
|
Name |
Type |
Description |
|
ContentFilter |
structure |
|
|
elements [] |
ContentFilterElement |
List of operators and their operands that compose the filter criteria. The filter is evaluated by starting with the first entry in this array. This structure is defined in-line with the following indented items. |
|
filterOperator |
Enum FilterOperator |
Filter operator to be evaluated. The FilterOperator enumeration is defined in Table 122. |
|
filterOperands [] |
Extensible Parameter FilterOperand |
Operands used by the selected operator. The number and use depend on the operators defined in Table 122. This array needs at least one entry. This extensible parameter type is the FilterOperand parameter type specified in 7.7.4. It specifies the list of valid FilterOperand values. |
The components of this data type are defined in Table 119.
Table 119 – ContentFilterResult structure
|
Name |
Type |
Description |
|
ContentFilterResult |
structure |
A structure that contains any errors associated with the filter. |
|
elementResults [] |
ContentFilter ElementResult |
A list of results for individual elements in the filter. The size and order of the list matches the size and order of the elements in the ContentFilter parameter. This structure is defined in-line with the following indented items. |
|
statusCode |
StatusCode |
The status code for a single element. |
|
operandStatusCodes [] |
StatusCode |
A list of status codes for the operands in an element. The size and order of the list matches the size and order of the operands in the ContentFilterElement. This list is empty if no operand errors occurred. |
|
operandDiagnosticInfos [] |
DiagnosticInfo |
A list of diagnostic information for the operands in an element. The size and order of the list matches the size and order of the operands in the ContentFilterElement. 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 operands. |
|
elementDiagnosticInfos [] |
DiagnosticInfo |
A list of diagnostic information for individual elements in the filter. The size and order of the list matches the size and order of the elements in the filter request parameter. 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 elements. |
Table 120 defines values for the StatusCode parameter that are specific to this structure. Common StatusCodes are defined in Table 183.
Table 120 – ContentFilterResult Result Codes
|
Symbolic Id |
Description |
|
Bad_FilterOperandCountMismatch |
The number of operands provided for the filter operator was less than expected for the operand provided. |
|
Bad_FilterOperatorInvalid |
An unrecognized operator was provided in a filter. |
|
Bad_FilterOperatorUnsupported |
A valid operator was provided, but the Server does not provide support for this filter operator. |
Table 121 defines values for the operandStatusCodes parameter that are specific to this structure. Common StatusCodes are defined in Table 183.
Table 121 – ContentFilterResult Operand Result Codes
|
Symbolic Id |
Description |
|
Bad_FilterOperandInvalid |
See Table 183 for the description of this result code. |
|
Bad_FilterElementInvalid |
The referenced element is not a valid element in the content filter. |
|
Bad_FilterLiteralInvalid |
The referenced literal is not a valid BaseDataType. |
|
Bad_AttributeIdInvalid |
The attribute id is not a valid attribute id in the system. |
|
Bad_IndexRangeInvalid |
See Table 183 for the description of this result code. |
|
Bad_NodeIdInvalid |
See Table 183 for the description of this result code. |
|
Bad_NodeIdUnknown |
See Table 183 for the description of this result code. |
|
Bad_NotTypeDefinition |
The provided NodeId was not a type definition NodeId. |
Table 122 defines the basic operators that can be used in a ContentFilter. See Table 123 for a description of advanced operators. See 7.7.4 for a definition of operands.
Table 122 – Basic FilterOperator definition
|
Operator Name |
Operator Number |
Number of Operands |
Description |
|
Equals |
0 |
2 |
TRUE if operand[0] is equal to operand[1]. If the operands are of different types, the system shall perform any implicit conversion to a common type. This operator resolves to FALSE if no implicit conversion is available and the operands are of different types. This operator returns FALSE if the implicit conversion fails. See the discussion on data type precedence in Table 126 for more information how to convert operands of different types. |
|
IsNull |
1 |
1 |
TRUE if operand[0] is a null value. TRUE If the value in operand[0] is a StatusCode instead of the field DataType. |
|
GreaterThan |
2 |
2 |
TRUE if operand[0] is greater than operand[1]. The following restrictions apply to the operands: [0]: Any operand that resolves to an ordered value. [1]: Any operand that resolves to an ordered value. The same conversion rules as defined for Equals apply. |
|
LessThan |
3 |
2 |
TRUE if operand[0] is less than operand[1]. The same conversion rules and restrictions as defined for GreaterThan apply. |
|
GreaterThanOrEqual |
4 |
2 |
TRUE if operand[0] is greater than or equal to operand[1]. The same conversion rules and restrictions as defined for GreaterThan apply. |
|
LessThanOrEqual |
5 |
2 |
TRUE if operand[0] is less than or equal to operand[1]. The same conversion rules and restrictions as defined for GreaterThan apply. |
|
Like |
6 |
2 |
TRUE if operand[0] matches a pattern defined by operand[1]. See Table 124 for the definition of the pattern syntax. The following restrictions apply to the operands: [0]: Any operand that resolves to a String. [1]: Any operand that resolves to a String. This operator resolves to FALSE if no operand can be resolved to a string. |
|
Not |
7 |
1 |
TRUE if operand[0] is FALSE. The following restrictions apply to the operands: [0]: Any operand that resolves to a Boolean. If the operand cannot be resolved to a Boolean, the result is a NULL. See below for a discussion on the handling of NULL. |
|
Between |
8 |
3 |
TRUE if operand[0] is greater or equal to operand[1] and less than or equal to operand[2]. The following restrictions apply to the operands: [0]: Any operand that resolves to an ordered value. [1]: Any operand that resolves to an ordered value. [2]: Any operand that resolves to an ordered value. If the operands are of different types, the system shall perform any implicit conversion to match all operands to a common type. If no implicit conversion is available and the operands are of different types, the particular result is FALSE. See the discussion on data type precedence in Table 126 for more information how to convert operands of different types. |
|
InList |
9 |
2..n |
TRUE if operand[0] is equal to one or more of the remaining operands. The Equals Operator is evaluated for operand[0] and each remaining operand in the list. If any Equals evaluation is TRUE, InList returns TRUE. |
|
And |
10 |
2 |
TRUE if operand[0] and operand[1] are TRUE. The following restrictions apply to the operands: [0]: Any operand that resolves to a Boolean. [1]: Any operand that resolves to a Boolean. If any operand cannot be resolved to a Boolean it is considered a NULL. See below for a discussion on the handling of NULL. |
|
Or |
11 |
2 |
TRUE if operand[0] or operand[1] are TRUE. The following restrictions apply to the operands: [0]: Any operand that resolves to a Boolean. [1]: Any operand that resolves to a Boolean. If any operand cannot be resolved to a Boolean it is considered a NULL. See below for a discussion on the handling of NULL. |
|
Cast |
12 |
2 |
Converts operand[0] to a value with a data type with a NodeId identified by operand[1]. The following restrictions apply to the operands: [0]: Any operand. [1]: Any operand that resolves to a NodeId or ExpandedNodeId where the Node is of the NodeClass DataType. If there is any error in conversion or in any of the parameters then the Cast Operation evaluates to a NULL. See below for a discussion on the handling of NULL. |
|
BitwiseAnd |
16 |
2 |
The result is an integer which matches the size of the largest operand and contains a bitwise And operation of the two operands where both have been converted to the same size (largest of the two operands). The following restrictions apply to the operands: [0]: Any operand that resolves to an integer. [1]: Any operand that resolves to an integer. If any operand cannot be resolved to an integer it is considered a NULL. See below for a discussion on the handling of NULL. |
|
BitwiseOr |
17 |
2 |
The result is an integer which matches the size of the largest operand and contains a bitwise Or operation of the two operands where both have been converted to the same size (largest of the two operands). The following restrictions apply to the operands: [0]: Any operand that resolves to an integer. [1]: Any operand that resolves to an integer. If any operand cannot be resolved to an integer it is considered a NULL. See below for a discussion on the handling of NULL. |
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 123 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.
Table 123 – Complex FilterOperator definition
|
Operator Name |
Operator Number |
Number of Operands |
Description |
|
InView |
13 |
1 |
TRUE if the target Node is contained in the View defined by operand[0]. The following restrictions apply to the operands: [0]: Any operand that resolves to a NodeId that identifies a View Node. If operand[0] does not resolve to a NodeId that identifies a View Node, this operation shall always be False. |
|
OfType |
14 |
1 |
TRUE if the target Node is of type operand[0] or of a subtype of operand[0]. The following restrictions apply to the operands: [0]: Any operand that resolves to a NodeId that identifies an ObjectType or VariableType Node. If operand[0] does not resolve to a NodeId that identifies an ObjectType or VariableType Node, this operation shall always be False. |
|
RelatedTo |
15 |
6 |
TRUE if the target Node is of type operand[0] and is related to a NodeId of the type defined in operand[1] by the Reference type defined in operand[2]. operand[0] or operand[1] can also point to an element Reference where the referred to element is another RelatedTo operator. This allows chaining of relationships (e.g. A is related to B is related to C), where the relationship is defined by the ReferenceType defined in operand[2]. In this case, the referred to element returns a list of NodeIds instead of TRUE or FALSE. In this case if any errors occur or any of the operands cannot be resolved to an appropriate value, the result of the chained relationship is an empty list of nodes. Operand[3] defines the number of hops for which the relationship should be followed. If operand[3] is 1, then objects shall be directly related. If a hop is greater than 1, then a NodeId of the type described in operand[1] is checked for at the depth specified by the hop. In this case, the type of the intermediate Node is undefined, and only the Reference type used to reach the end Node is defined. If the requested number of hops cannot be followed, then the result is FALSE, i.e., an empty Node list. If operand[3] is 0, the relationship is followed to its logical end in a forward direction and each Node is checked to be of the type specified in operand[1]. If any Node satisfies this criterion, then the result is TRUE, i.e., the NodeId is included in the sub-list. Operand [4] defines if operands [0] and [1] should include support for subtypes of the types defined by these operands. A TRUE indicates support for subtypes operand [5] defines if operand [2] should include support for subtypes of the reference type. A TRUE indicates support for subtypes.
The following restrictions apply to the operands: [0]: Any operand that resolves to a NodeId or ExpandedNodeId that identifies an ObjectType or VariableType Node or a reference to another element which is a RelatedTo operator. [1]: Any operand that resolves to a NodeId or ExpandedNodeId that identifies an ObjectType or VariableType Node or a reference to another element which is a RelatedTo operator. [2]: Any operand that resolves to a NodeId that identifies a ReferenceType Node. [3]: Any operand that resolves to a value implicitly convertible to UInt32. [4]: Any operand that resolves to a value implicitly convertible to a Boolean; if this operand does not resolve to a Boolean, then a value of FALSE is used. [5]: Any operand that resolves to a value implicitly convertible to a Boolean; if this operand does not resolve to a Boolean, then a value of FALSE is used.
If none of the operands [0],[1],[2],[3] resolves to an appropriate value then the result of this operation shall always be False (or an Empty set in the case of a nested RelatedTo operand).
See examples for RelatedTo in B.2. |
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 124. 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 124 – Wildcard characters
|
Special Character |
Description |
|
% |
Match any string of zero or more characters (i.e. ‘main%’ would match any string that starts with ‘main’, ‘%en%’ would match any string that contains the letters ‘en’ such as ‘entail’, ‘green’ and ‘content’.) If a ‘%’ sign is intend in a string the list operand can be used (i.e. 5[%] would match ‘5%’). |
|
_ |
Match any single character (i.e. ‘_ould’ would match ‘would’, ‘could’). If the ‘_’ is intended in a string then the list operand can be used (i.e. 5[_] would match ‘5_’). |
|
\ |
Escape character allows literal interpretation (i.e. \\ is \, \% is %, \_ is _) |
|
[] |
Match any single character in a list (i.e. ‘abc[13-68] would match ‘abc1’, ‘abc3’, ‘abc4’, ‘abc5’, ‘abc6’, and ‘abc8’. ‘xyz[c-f]’ would match ‘xyzc’, ‘xyzd’, ‘xyze’, ‘xyzf’). |
|
[^] |
Not Matching any single character in a list. The ^ shall be the first character inside on the []. (i.e. ‘ABC[^13-5]’ would NOT match ‘ABC1’, ‘ABC3’, ‘ABC4’, and ‘ABC5’. xyz[^dgh] would NOT match ‘xyzd’, ‘xyzg’, ‘xyzh’. ) |
Table 125 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.
|
|
Target Type (To) |
|||||||||||||||||||||
|
Boolean |
Byte |
ByteString |
DateTime |
Double |
ExpandedNodeId |
Float |
Guid |
Int16 |
Int32 |
Int64 |
NodeId |
SByte |
StatusCode |
String |
LocalizedText |
QualifiedName |
UInt16 |
UInt32 |
UInt64 |
XmlElement |
|
|
Boolean |
- |
I |
X |
X |
I |
X |
I |
X |
I |
I |
I |
X |
I |
X |
E |
X |
X |
I |
I |
I |
X |
|
|
Byte |
E |
- |
X |
X |
I |
X |
I |
X |
I |
I |
I |
X |
I |
X |
E |
X |
X |
I |
I |
I |
X |
|
|
ByteString |
X |
X |
- |
X |
X |
X |
X |
E |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
|
|
DateTime |
X |
X |
X |
- |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
E |
X |
X |
X |
X |
X |
X |
|
|
Double |
E |
E |
X |
X |
- |
X |
E |
X |
E |
E |
E |
X |
E |
X |
E |
X |
X |
E |
E |
E |
X |
|
|
ExpandedNodeId |
X |
X |
X |
X |
X |
- |
X |
X |
X |
X |
X |
E |
X |
X |
I |
X |
X |
X |
X |
X |
X |
|
|
Float |
E |
E |
X |
X |
I |
X |
- |
X |
E |
E |
E |
X |
E |
X |
E |
X |
X |
E |
E |
E |
X |
|
|
Guid |
X |
X |
E |
X |
X |
X |
X |
- |
X |
X |
X |
X |
X |
X |
E |
X |
X |
X |
X |
X |
X |
|
|
Int16 |
E |
E |
X |
X |
I |
X |
I |
X |
- |
I |
I |
X |
E |
X |
E |
X |
X |
E |
I |
I |
X |
|
|
Int32 |
E |
E |
X |
X |
I |
X |
I |
X |
E |
- |
I |
X |
E |
E |
E |
X |
X |
E |
E |
I |
X |
|
|
Int64 |
E |
E |
X |
X |
I |
X |
I |
X |
E |
E |
- |
X |
E |
E |
E |
X |
X |
E |
E |
E |
X |
|
|
NodeId |
X |
X |
X |
X |
X |
I |
X |
X |
X |
X |
X |
- |
X |
X |
I |
X |
X |
X |
X |
X |
X |
|
|
SByte |
E |
E |
X |
X |
I |
X |
I |
X |
I |
I |
I |
X |
- |
X |
E |
X |
X |
I |
I |
I |
X |
|
|
StatusCode |
X |
X |
X |
X |
X |
X |
X |
X |
X |
E |
E |
X |
X |
- |
X |
X |
X |
E |
E |
E |
X |
|
|
String |
I |
I |
X |
E |
I |
E |
I |
I |
I |
I |
I |
E |
I |
X |
- |
E |
E |
I |
I |
I |
X |
|
|
LocalizedText |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
I |
- |
X |
X |
X |
X |
X |
|
|
QualifiedName |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
I |
I |
- |
X |
X |
X |
X |
|
|
UInt16 |
E |
E |
X |
X |
I |
X |
I |
X |
I |
I |
I |
X |
E |
I |
E |
X |
X |
- |
I |
I |
X |
|
|
UInt32 |
E |
E |
X |
X |
I |
X |
I |
X |
E |
I |
I |
X |
E |
E |
E |
X |
X |
E |
- |
I |
X |
|
|
UInt64 |
E |
E |
X |
X |
I |
X |
I |
X |
E |
E |
I |
X |
E |
E |
E |
X |
X |
E |
E |
- |
X |
|
|
XmlElement |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
X |
- |
|
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 126 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.
Table 126 – Data Precedence rules
|
Rank |
Data Type |
|
1 |
Double |
|
2 |
Float |
|
3 |
Int64 |
|
4 |
UInt64 |
|
5 |
Int32 |
|
6 |
UInt32 |
|
7 |
StatusCode |
|
8 |
Int16 |
|
9 |
UInt16 |
|
10 |
SByte |
|
11 |
Byte |
|
12 |
Boolean |
|
13 |
Guid |
|
14 |
String |
|
15 |
ExpandedNodeId |
|
16 |
NodeId |
|
17 |
LocalizedText |
|
18 |
QualifiedName |
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 127 defines how to combine elements that evaluate to NULL with other elements in a logical AND operation.
Table 127 – Logical AND Truth table
|
|
TRUE |
FALSE |
NULL |
|
TRUE |
TRUE |
FALSE |
NULL |
|
FALSE |
FALSE |
FALSE |
FALSE |
|
NULL |
NULL |
FALSE |
NULL |
Table 128 defines how to combine elements that evaluate to NULL with other elements in a logical OR operation.
Table 128 – Logical OR Truth table
|
|
TRUE |
FALSE |
NULL |
|
TRUE |
TRUE |
TRUE |
TRUE |
|
FALSE |
TRUE |
FALSE |
NULL |
|
NULL |
TRUE |
NULL |
NULL |
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.
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 129. The ExtensibleParameter type is defined in 7.17.
Table 129 – FilterOperand parameter TypeIds
|
Symbolic Id |
Description |
|
Element |
Specifies an index into the array of elements. This type is used to build a logic tree of sub-elements by linking the operand of one element to a sub-element. |
|
Literal |
Specifies a literal value. |
|
Attribute |
Specifies any Attribute of an Object or Variable Node using a Node in the type system and relative path constructed from ReferenceTypes and BrowseNames. |
|
SimpleAttribute |
Specifies any Attribute of an Object or Variable Node using a TypeDefinition and a relative path constructed from BrowseNames. |
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 130 defines the ElementOperand type.
|
Name |
Type |
Description |
|
ElementOperand |
structure |
ElementOperand value. |
|
index |
UInt32 |
Index into the element array. |
Table 131 defines the LiteralOperand type.
|
Name |
Type |
Description |
|
LiteralOperand |
structure |
LiteralOperand value. |
|
value |
BaseDataType |
A literal value. |
Table 132 defines the AttributeOperand type.
|
Name |
Type |
Description |
|
AttributeOperand |
structure |
Attribute of a Node in the AddressSpace. |
|
nodeId |
NodeId |
|
|
alias |
String |
An optional parameter used to identify or refer to an alias. An alias is a symbolic name that can be used to alias this operand and use it in other locations in the filter structure. |
|
browsePath |
RelativePath |
Browse path relative to the Node identified by the nodeId parameter. See 7.31 for the definition of RelativePath. |
|
attributeId |
IntegerId |
Id of the Attribute. This shall be a valid AttributeId. The IntegerId is defined in 7.19. The IntegerIds for the Attributes are defined in OPC 10000-6. |
|
indexRange |
NumericRange |
This parameter is used to identify a single element of an array or a single range of indexes for an array. The first element is identified by index 0 (zero). The NumericRange type is defined in 7.27. This parameter is not used if the specified Attribute is not an array. However, if the specified Attribute is an array and this parameter is not used, then all elements are to be included in the range. The parameter is null or empty if not used. |
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 133 defines the SimpleAttributeOperand type.
Table 133 – SimpleAttributeOperand
|
Name |
Type |
Description |
|
SimpleAttributeOperand |
structure |
Attribute of a Node in the AddressSpace. |
|
typeDefinitionId |
NodeId |
NodeId of a TypeDefinitionNode. This parameter restricts the operand to instances of the TypeDefinitionNode or one of its subtypes. If the SimpleAttributeOperand is used in an EventFilter and the typeDefinitionId is BaseEventType the Server shall evaluate the browsePath without considering the typeDefinitionId. |
|
browsePath [] |
QualifiedName |
A relative path to a Node. This parameter specifies a relative path using a list of BrowseNames instead of the RelativePath structure used in the AttributeOperand. The list of BrowseNames is equivalent to a RelativePath that specifies forward references which are subtypes of the HierarchicalReferences ReferenceType. All Nodes followed by the browsePath shall be of the NodeClass Object or Variable. If this list is empty the Node is the instance of the TypeDefinition. |
|
attributeId |
IntegerId |
Id of the Attribute. The IntegerId is defined in 7.19. The Value Attribute shall be supported by all Servers. The support of other Attributes depends on requirements set in Profiles or other parts of this specification. |
|
indexRange |
NumericRange |
This parameter is used to identify a single element of an array, or a single range of indexes for an array. The array in this context includes String and ByteString. The first element is identified by index 0 (zero). This parameter is ignored if the selected Node is not a Variable or the Value of a Variable is not an array. All values in the array are used if this parameter is null or empty. The NumericRange type is defined in 7.27. |
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
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.
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 134.
Table 134 – DataChangeTrigger values
|
Name |
Value |
Description |
|
STATUS |
0 |
Report a notification ONLY if the StatusCode associated with the value changes. See Table 183 for StatusCodes defined in this document. OPC 10000-8 specifies additional StatusCodes that are valid in particular for device data. |
|
STATUS_VALUE |
1 |
Report a notification if either the StatusCode or the value change. The Deadband filter can be used in addition for filtering value changes. For floating point values a Server shall check for NaN and only report a single notification with NaN when the value enters the NaN state. When testing for changes, a Server shall treat null and empty arrays of the same DataType as equal. This also applies to Strings and ByteStrings. This is the default setting if no filter is set. |
|
STATUS_VALUE_TIMESTAMP |
2 |
Report a notification if either StatusCode, value or the SourceTimestamp change. If a Deadband filter is specified, this trigger has the same behaviour as STATUS_VALUE. |
The components of this parameter are defined in Table 135.
|
Name |
Type |
Description |
|
DataValue |
structure |
The value and associated information. |
|
value |
BaseDataType |
The data value. If the StatusCode indicates an error then the value is to be ignored and the Server shall set it to null. |
|
statusCode |
StatusCode |
The StatusCode that defines the Server’s ability to access/provide the value. The StatusCode type is defined in 7.39 |
|
sourceTimestamp |
UtcTime |
The source timestamp for the value. |
|
sourcePicoSeconds |
UInteger |
Specifies the number of 10 picoseconds (1,0 e-11 seconds) intervals which shall be added to the sourceTimestamp. |
|
serverTimestamp |
UtcTime |
The Server timestamp for the value. |
|
serverPicoSeconds |
UInteger |
Specifies the number of 10 picoseconds (1,0 e-11 seconds) intervals which shall be added to the serverTimestamp. |
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.
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.
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
- the device is checking values every 0,5 seconds,
- the connection to the device is good,
- 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.
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.39.
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. If a Variable is created and no default value or initial value is available, the StatusCode shall be Bad_NoValue.
The components of this parameter are defined in Table 136.
The DiagnosticInfo shall not contain any security related information.
|
Name |
Type |
Description |
|
DiagnosticInfo |
structure |
Vendor-specific diagnostic information. |
|
namespaceUri |
Int32 |
The symbolicId is defined within the context of a namespace. This namespace is represented as a string and is conveyed to the Client in the stringTable parameter of the ResponseHeader parameter defined in 7.34. The namespaceUri parameter contains the index into the stringTable for this string. -1 indicates that no string is specified. The namespaceUri shall not be the standard OPC UA namespace. There are no symbolicIds provided for standard StatusCodes. |
|
symbolicId |
Int32 |
The symbolicId shall be used to identify a vendor-specific error or condition; typically the result of some Server internal operation. The maximum length of this string is 32 characters. Servers wishing to return a numeric return code should convert the return code into a string and use this string as symbolicId (e.g., "0xC0040007" or "-4"). This symbolic identifier string is conveyed to the Client in the stringTable parameter of the ResponseHeader parameter defined in 7.34. The symbolicId parameter contains the index into the stringTable for this string. -1 indicates that no string is specified. The symbolicId shall not contain StatusCodes. If the localizedText contains a translation for the description of a StatusCode, the symbolicId is -1. |
|
locale |
Int32 |
The locale part of the vendor-specific localized text describing the symbolic id. This localized text string is conveyed to the Client in the stringTable parameter of the ResponseHeader parameter defined in 7.34. The locale parameter contains the index into the stringTable for this string. -1 indicates that no string is specified. |
|
localizedText |
Int32 |
A vendor-specific localized text string describes the symbolic id. The maximum length of this text string is 256 characters. This localized text string is conveyed to the Client in the stringTable parameter of the ResponseHeader parameter defined in 7.34. The localizedText parameter contains the index into the stringTable for this string. -1 indicates that no string is specified. The localizedText refers to the symbolicId if present or the string that describes the standard StatusCode if the Server provides translations. If the index is -1, the Server has no translation to return and the Client should use the invariant StatusCode description from the specification. |
|
additionalInfo |
String |
Vendor-specific diagnostic information. |
|
innerStatusCode |
StatusCode |
The StatusCode from the inner operation. Many applications will make calls into underlying systems during OPC UA request processing. An OPC UA Server has the option of reporting the status from the underlying system in the diagnostic info. |
|
innerDiagnosticInfo |
DiagnosticInfo |
The diagnostic info associated with the inner StatusCode. |
The DiscoveryConfiguration structure used in the RegisterServer2 Service allows Servers to provide additional configuration parameters to Discovery Servers for registration. Table 137 defines the current set of discovery configuration options. The ExtensibleParameter type is defined in 7.17.
Table 137 – DiscoveryConfiguration parameterTypeIds
|
Symbolic Id |
Description |
|
MdnsDiscoveryConfiguration |
Configuration parameters for mDNS discovery. |
Table 138 defines the MdnsDiscoveryConfiguration parameter.
Table 138 – MdnsDiscoveryConfiguration
|
Name |
Type |
Description |
|
MdnsDiscoveryConfiguration |
structure |
mDNS discovery configuration. |
|
mdnsServerName |
String |
The name of the Server when it is announced via mDNS. See OPC 10000-12 for the details about mDNS. This string shall be less than 64 bytes. If null or empty the first element of the serverNames array from RegisteredServer is used (Text of LocalizedText and truncated to 63 bytes if necessary). |
|
serverCapabilities [] |
String |
The set of Server capabilities supported by the Server. A Server capability is a short identifier for a feature The set of allowed Server capabilities are defined in OPC 10000-12. |
The components of this parameter are defined in Table 139.
Table 139 – EndpointDescription
|
Name |
Type |
Description |
|
EndpointDescription |
structure |
|
|
endpointUrl |
String |
The URL for the Endpoint described. |
|
server |
ApplicationDescription |
The description for the Server that the Endpoint belongs to. The ApplicationDescription type is defined in 7.2. |
|
serverCertificate |
ApplicationInstance Certificate |
The Application Instance Certificate issued to the Server. The ApplicationInstanceCertificate type is defined in 7.3. |
|
securityMode |
Enum MessageSecurityMode |
The type of security to apply to the messages. The type MessageSecurityMode type is defined in 7.20. A SecureChannel may need to be created even if the securityMode is NONE. The exact behaviour depends on the mapping used and is described in the OPC 10000-6. |
|
securityPolicyUri |
String |
The URI for SecurityPolicy to use when securing messages. The set of known URIs and the SecurityPolicies associated with them are defined in OPC 10000-7. |
|
userIdentityTokens [] |
UserTokenPolicy |
The user identity tokens that the Server will accept. The Client shall pass one of the UserIdentityTokens in the ActivateSession request. The UserTokenPolicy type is described in 7.42. |
|
transportProfileUri |
String |
The URI of the Transport Profile supported by the Endpoint. OPC 10000-7 defines URIs for the Transport Profiles. |
|
securityLevel |
Byte |
A numeric value that indicates how secure the EndpointDescription is compared to other EndpointDescriptions for the same Server. A value of 0 indicates that the EndpointDescription is not recommended and is only supported for backward compatibility. A higher value indicates better security. |
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 140.
|
Name |
Type |
Description |
|
EphemeralKeyType |
Structure |
Specifies an ECC ephemeral Public Key and a signature created by the application that owns the associated Private Key. |
|
publicKey |
ByteString |
The Public Key associated with an EphemeralKey created by the sender. It is encoded according to the rules for the ECC SecurityPolicies (see OPC 10000-7). The size of the Public Key is specified by the current SecurityPolicyUri. |
|
signature |
ByteString |
The Signature calculated using the Application Instance Certificate of the owner of the Private Key associated with the Public Key. The value of the Public Key field is the data used to calculate the Signature. The SecurityPolicyUri used to generate the EphemeralKey is the SecurityPolicyUri used to calculate the signature. |
The components of this parameter are defined in Table 141. ExpandedNodeId allows the namespace to be specified explicitly as a string or with an index in the Server's namespace table.
|
Name |
Type |
Description |
|
ExpandedNodeId |
structure |
The NodeId with the namespace expanded to its string representation. |
|
serverIndex |
Index |
Index that identifies the Server that contains the TargetNode. This Server may be the local Server or a remote Server. This index is the index of that Server in the local Server’s Server table. The index of the local Server in the Server table is always 0. All remote Servers have indexes greater than 0. The Server table is contained in the Server Object in the AddressSpace (see OPC 10000-3 and OPC 10000-5). The Client may read the Server table Variable to access the description of the target Server. |
|
namespaceUri |
String |
The URI of the namespace. If this parameter is specified then the namespace index is ignored. 5.5 and OPC 10000-12 describes discovery mechanism that can be used to resolve URIs into URLs. |
|
namespaceIndex |
UInt16 |
The index in the Server's namespace table. This parameter shall be 0 and is ignored in the Server if the namespace URI is specified. |
|
identifierType |
IdType |
Type of the identifier element of the NodeId. |
|
identifier |
* |
The identifier for a Node in the AddressSpace of an OPC UA Server (see NodeId definition in OPC 10000-3). |
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 142.
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.
Table 142 – ExtensibleParameter base type
|
Name |
Type |
Description |
|
ExtensibleParameter |
structure |
Specifies the details of an extensible parameter type. |
|
parameterTypeId |
NodeId |
Identifies the data type of the parameter that follows. |
|
parameterData |
-- |
The details for the extensible parameter type. |
This primitive data type is a UInt32 that identifies an element of an array.
This primitive data type is a UInt32 that is used as an identifier, such as a handle. All values, except for 0, are valid.
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 143.
Table 143 – MessageSecurityMode values
|
Name |
Value |
Description |
|
INVALID |
0 |
The MessageSecurityMode is invalid. This value is the default value to avoid an accidental choice of no security is applied. This choice will always be rejected. |
|
NONE |
1 |
No security is applied. |
|
SIGN |
2 |
All messages are signed but not encrypted. |
|
SIGNANDENCRYPT |
3 |
All messages are signed and encrypted. |
The components of this parameter are defined in Table 144.
Table 144 – MonitoringParameters
|
Name |
Type |
Description |
|
MonitoringParameters |
structure |
Parameters that define the monitoring characteristics of a MonitoredItem. |
|
clientHandle |
IntegerId |
Client-supplied id of the MonitoredItem. This id is used in Notifications generated for the list Node. The IntegerId type is defined in 7.19. |
|
samplingInterval |
Duration |
The interval that defines the fastest rate at which the MonitoredItem(s) should be accessed and evaluated. This interval is defined in milliseconds. The value 0 indicates that the Server should use the fastest practical rate. The value -1 indicates that the default sampling interval defined by the publishing interval of the Subscription is requested. A different sampling interval is used if the publishing interval is not a supported sampling interval. Any negative number is interpreted as -1. The sampling interval is not changed if the publishing interval is changed by a subsequent call to the ModifySubscription Service. The Server uses this parameter to assign the MonitoredItems to a sampling interval that it supports. The assigned interval is provided in the revisedSamplingInterval parameter. The Server shall always return a revisedSamplingInterval that is equal or higher than the requested samplingInterval unless the requested samplingInterval is higher than the maximum sampling interval supported by the Server, in which case the maximum sampling interval shall be returned. |
|
filter |
Extensible Parameter MonitoringFilter |
A filter used by the Server to determine if the MonitoredItem should generate a Notification. If not used, this parameter is null. The MonitoringFilter parameter type is an extensible parameter type specified in 7.22. It specifies the types of filters that can be used. |
|
queueSize |
Counter |
The requested size of the MonitoredItem queue. The following values have special meaning for data monitored items: ValueMeaning 0 or 1the Server returns the default queue size which shall be 1 as revisedQueueSize for data monitored items. The queue has a single entry, effectively disabling queuing. For values larger than one a first-in-first-out queue is to be used. The Server may limit the size in revisedQueueSize. In the case of a queue overflow, the Overflow bit (flag) in the InfoBits portion of the DataValue statusCode is set in the new value.
The following values have special meaning for event monitored items: ValueMeaning 0the Server returns the default queue size for Event Notifications as revisedQueueSize for event monitored items. 1the Server returns the minimum queue size the Server requires for Event Notifications as revisedQueueSize. MaxUInt32the Server returns the maximum queue size that the Server can support for Event Notifications as revisedQueueSize. If a Client chooses a value between the minimum and maximum settings of the Server the value shall be returned in the revisedQueueSize. If the requested queueSize is outside the minimum or maximum, the Server shall return the corresponding bounding value. In the case of a queue overflow, an Event of the type EventQueueOverflowEventType is generated. |
|
discardOldest |
Boolean |
Specifies the discard policy when the queue is full and a new Notification is to be queued. It has the following values: TRUEthe oldest (first) Notification in the queue is discarded. The new Notification is added to the end of the queue. FALSEthe last Notification added to the queue gets replaced with the new Notification. |
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 145. 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.
Table 145 – MonitoringFilter parameterTypeIds
|
Symbolic Id |
Description |
|
DataChangeFilter |
The change in a data value that shall cause a Notification to be generated. |
|
EventFilter |
If a Notification conforms to the EventFilter, the Notification is sent to the Client. |
|
AggregateFilter |
The Aggregate and its intervals when it will be calculated and a Notification is generated. |
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 146.
|
Name |
Type |
Description |
|
DataChangeFilter |
structure |
|
|
trigger |
Enum DataChangeTrigger |
Specifies the conditions under which a data change notification should be reported. The DataChangeTrigger enumeration is defined in 7.10. If the DataChangeFilter is not applied to the monitored item, STATUS_VALUE is the default reporting behaviour. |
|
deadbandType |
UInt32 |
A value that defines the Deadband type and behaviour. ValueNameDescription 0 NoneNo Deadband calculation should be applied. 1 AbsoluteAbsoluteDeadband (see below) 2 PercentPercentDeadband (This type is specified in OPC 10000-8). |
|
deadbandValue |
Double |
The Deadband is applied only if* the trigger includes value changes and* the deadbandType is set appropriately. Deadband is ignored if the status of the data item changes. DeadbandType = AbsoluteDeadband: For this type the deadbandValue contains the absolute change in a data value that shall cause a Notification to be generated. This parameter applies only to Variables with any Number data type. An exception that causes a DataChange Notification based on an AbsoluteDeadband is determined as follows: Generate a Notification if (absolute value of (last cached value - current value) > AbsoluteDeadband) The last cached value is defined as the last value pushed to the queue. If the item is an array of values, the entire array is returned if any array element exceeds the AbsoluteDeadband, or the size or dimension of the array changes. DeadbandType = PercentDeadband: This type is specified in OPC 10000-8 |
The DataChangeFilter does not have an associated result structure.
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 148. 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 122 may be used in the whereClause, however, only the OfType FilterOperator from Table 123 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 148. 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 147 defines the EventFilter structure.
Table 147 – EventFilter structure
|
Name |
Type |
Description |
|
EventFilter |
structure |
|
|
selectClauses [] |
SimpleAttribute Operand |
List of the values to return with each Event in a Notification. At least one valid clause shall be specified. See 7.7.4.5 for the definition of SimpleAttributeOperand. |
|
whereClause |
ContentFilter |
Limit the Notifications to those Events that match the criteria defined by this ContentFilter. The ContentFilter structure is described in 7.7. The AttributeOperand structure may not be used in an EventFilter. |
Table 148 defines the EventFilterResult structure. This is the MonitoringFilterResult associated with the EventFilter MonitoringFilter.
Table 148 – EventFilterResult structure
|
Name |
Type |
Description |
|
EventFilterResult |
structure |
|
|
selectClauseResults [] |
StatusCode |
List of status codes for the elements in the select clause. The size and order of the list matches the size and order of the elements in the selectClauses request parameter. The Server returns null for unavailable or rejected Event fields. |
|
selectClauseDiagnosticInfos [] |
DiagnosticInfo |
A list of diagnostic information for individual elements in the select clause. The size and order of the list matches the size and order of the elements in the selectClauses request parameter. 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 select clauses. |
|
whereClauseResult |
ContentFilter Result |
Any results associated with the whereClause request parameter. The ContentFilterResult type is defined in 7.7.2. |
Table 149 defines values for the selectClauseResults parameter. Common StatusCodes are defined in Table 183.
Table 149 – EventFilterResult Result Codes
|
Symbolic Id |
Description |
|
Bad_TypeDefinitionInvalid |
See Table 183 for the description of this result code. The typeId is not the NodeId for BaseEventType or a subtype of it. |
|
Bad_NodeIdUnknown |
See Table 183 for the description of this result code. The browsePath is specified but it will never exist in any Event. |
|
Bad_BrowseNameInvalid |
See Table 183 for the description of this result code. The browsePath is specified and contains a null element. |
|
Bad_AttributeIdInvalid |
See Table 183 for the description of this result code. The node specified by the browse path will never allow the given AttributeId to be returned. |
|
Bad_IndexRangeInvalid |
See Table 183 for the description of this result code. |
|
Bad_TypeMismatch |
See Table 183 for the description of this result code. The indexRange is valid but the value of the Attribute is never an array. |
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 150.
Table 150 – AggregateFilter structure
|
Name |
Type |
Description |
|
AggregateFilter |
structure |
|
|
startTime |
UtcTime |
Beginning of period to calculate the Aggregate the first time. The size of each period used to calculate the Aggregate is defined by the samplingInterval of the MonitoringParameters (see 7.21). |
|
aggregateType |
NodeId |
The NodeId of the AggregateFunctionType Object that indicates the Aggregate to be used when retrieving processed data. See OPC 10000-13 for details. |
|
processingInterval |
Duration |
The period be used to compute the Aggregate. |
|
aggregateConfiguration |
Aggregate Configuration |
This parameter allows Clients to override the Aggregate configuration settings supplied by the AggregateConfiguration Object on a per monitored item basis. See OPC 10000-13 for more information on Aggregate configurations. If the Server does not support the ability to override the Aggregate configuration settings it shall return a StatusCode of Bad_AggregateListMismatch. This structure is defined in-line with the following indented items. |
|
useServerCapabilities Defaults |
Boolean |
If value = TRUE use Aggregate configuration settings as outlined by the AggregateConfiguration object. If value=FALSE use configuration settings as outlined in the following aggregateConfiguration parameters. Default is TRUE. |
|
treatUncertainAsBad |
Boolean |
As described in OPC 10000-13. |
|
percentDataBad |
Byte |
As described in OPC 10000-13. |
|
percentDataGood |
Byte |
As described in OPC 10000-13. |
|
useSloped Extrapolation |
Boolean |
As described in OPC 10000-13. |
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 151. This is the MonitoringFilterResult associated with the AggregateFilter MonitoringFilter.
Table 151 – AggregateFilterResult structure
|
Name |
Type |
Description |
|
AggregateFilterResult |
structure |
|
|
revisedStartTime |
UtcTime |
The actual StartTime interval that the Server shall use. This value is based on a number of factors, including capabilities of the Server to access historical data. The revisedStartTime should remain in the same boundary as the startTime (startTime + samplingInterval * n = revisedStartTime). |
|
revisedProcessingInterval |
Duration |
The actual processingInterval that the Server shall use.
The revisedProcessingInterval shall be at least twice the revisedSamplingInterval for the MonitoredItem. |
|
revisedAggregateConfiguration |
Aggregate Configuration |
The actual aggregateConfiguration that the Server shall use. The structure is defined in Table 150. |
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 152.
Table 152 – MonitoringMode values
|
Name |
Value |
Description |
|
DISABLED |
0 |
The item being monitored is not sampled or evaluated, and Notifications are not generated or queued. Notification reporting is disabled. |
|
SAMPLING |
1 |
The item being monitored is sampled and evaluated, and Notifications are generated and queued. Notification reporting is disabled. |
|
REPORTING |
2 |
The item being monitored is sampled and evaluated, and Notifications are generated and queued. Notification reporting is enabled. |
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 153. The ExtensibleParameter type is defined in 7.17.
Table 153 – NodeAttributes parameterTypeIds
|
Symbolic Id |
Description |
|
ObjectAttributes |
Defines the Attributes for the Object NodeClass. |
|
VariableAttributes |
Defines the Attributes for the Variable NodeClass. |
|
MethodAttributes |
Defines the Attributes for the Method NodeClass. |
|
ObjectTypeAttributes |
Defines the Attributes for the ObjectType NodeClass. |
|
VariableTypeAttributes |
Defines the Attributes for the VariableType NodeClass. |
|
ReferenceTypeAttributes |
Defines the Attributes for the ReferenceType NodeClass. |
|
DataTypeAttributes |
Defines the Attributes for the DataType NodeClass. |
|
ViewAttributes |
Defines the Attributes for the View NodeClass. |
|
GenericAttributes |
Defines an id and value list for passing in any number of Attribute values. It should be used instead of the NodeClass specific structures since it allows the handling of additional Attributes defined in future specification versions. |
Table 154 defines the bit mask used in the NodeAttributes parameters to specify which Attributes are set by the Client.
Table 154 – Bit mask for specified Attributes
|
Field |
Bit |
Description |
|
AccessLevel |
0 |
Indicates if the AccessLevel Attribute is set. |
|
ArrayDimensions |
1 |
Indicates if the ArrayDimensions Attribute is set. |
|
Reserved |
2 |
Reserved to be consistent with WriteMask defined in OPC 10000-3. |
|
ContainsNoLoops |
3 |
Indicates if the ContainsNoLoops Attribute is set. |
|
DataType |
4 |
Indicates if the DataType Attribute is set. |
|
Description |
5 |
Indicates if the Description Attribute is set. |
|
DisplayName |
6 |
Indicates if the DisplayName Attribute is set. |
|
EventNotifier |
7 |
Indicates if the EventNotifier Attribute is set. |
|
Executable |
8 |
Indicates if the Executable Attribute is set. |
|
Historizing |
9 |
Indicates if the Historizing Attribute is set. |
|
InverseName |
10 |
Indicates if the InverseName Attribute is set. |
|
IsAbstract |
11 |
Indicates if the IsAbstract Attribute is set. |
|
MinimumSamplingInterval |
12 |
Indicates if the MinimumSamplingInterval Attribute is set. |
|
Reserved |
13 |
Reserved to be consistent with WriteMask defined in OPC 10000-3. |
|
Reserved |
14 |
Reserved to be consistent with WriteMask defined in OPC 10000-3. |
|
Symmetric |
15 |
Indicates if the Symmetric Attribute is set. |
|
UserAccessLevel |
16 |
Indicates if the UserAccessLevel Attribute is set. |
|
UserExecutable |
17 |
Indicates if the UserExecutable Attribute is set. |
|
UserWriteMask |
18 |
Indicates if the UserWriteMask Attribute is set. |
|
ValueRank |
19 |
Indicates if the ValueRank Attribute is set. |
|
WriteMask |
20 |
Indicates if the WriteMask Attribute is set. |
|
Value |
21 |
Indicates if the Value Attribute is set. |
|
Reserved |
22:32 |
Reserved for future use. Shall always be zero. |
Table 155 defines the ObjectAttributes parameter.
|
Name |
Type |
Description |
|
ObjectAttributes |
structure |
Defines the Attributes for the Object NodeClass. |
|
specifiedAttributes |
UInt32 |
A bit mask that indicates which fields contain valid values. A field shall be ignored if the corresponding bit is set to 0. The bit values are defined in Table 154. |
|
displayName |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
description |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
writeMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
userWriteMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
eventNotifier |
Byte |
See OPC 10000-3 for the description of this Attribute. |
Table 156 defines the VariableAttributes parameter.
Table 156 – VariableAttributes
|
Name |
Type |
Description |
|
VariableAttributes |
structure |
Defines the Attributes for the Variable NodeClass |
|
specifiedAttributes |
UInt32 |
A bit mask that indicates which fields contain valid values. A field shall be ignored if the corresponding bit is set to 0. The bit values are defined in Table 154. |
|
displayName |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
description |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
writeMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
userWriteMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
value |
BaseDataType |
See OPC 10000-3 for the description of this Attribute. |
|
dataType |
NodeId |
See OPC 10000-3 for the description of this Attribute. |
|
valueRank |
Int32 |
See OPC 10000-3 for the description of this Attribute. |
|
arrayDimensions |
UInt32 [] |
See OPC 10000-3 for the description of this Attribute. |
|
accessLevel |
Byte |
See OPC 10000-3 for the description of this Attribute. |
|
userAccessLevel |
Byte |
See OPC 10000-3 for the description of this Attribute. |
|
minimumSamplingInterval |
Duration |
See OPC 10000-3 for the description of this Attribute. |
|
historizing |
Boolean |
See OPC 10000-3 for the description of this Attribute. |
Table 157 defines the MethodAttributes parameter.
|
Name |
Type |
Description |
|
MethodAttributes |
structure |
Defines the Attributes for the Method NodeClass |
|
specifiedAttributes |
UInt32 |
A bit mask that indicates which fields contain valid values. A field shall be ignored if the corresponding bit is set to 0. The bit values are defined in Table 154. |
|
displayName |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
description |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
writeMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
userWriteMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
executable |
Boolean |
See OPC 10000-3 for the description of this Attribute. |
|
userExecutable |
Boolean |
See OPC 10000-3 for the description of this Attribute. |
Table 158 defines the ObjectTypeAttributes parameter.
Table 158 – ObjectTypeAttributes
|
Name |
Type |
Description |
|
ObjectTypeAttributes |
structure |
Defines the Attributes for the ObjectType NodeClass. |
|
specifiedAttributes |
UInt32 |
A bit mask that indicates which fields contain valid values. A field shall be ignored if the corresponding bit is set to 0. The bit values are defined in Table 154. |
|
displayName |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
description |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
writeMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
userWriteMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
isAbstract |
Boolean |
See OPC 10000-3 for the description of this Attribute. |
Table 159 defines the VariableTypeAttributes parameter.
Table 159 – VariableTypeAttributes
|
Name |
Type |
Description |
|
VariableTypeAttributes |
structure |
Defines the Attributes for the VariableType NodeClass |
|
specifiedAttributes |
UInt32 |
A bit mask that indicates which fields contain valid values. A field shall be ignored if the corresponding bit is set to 0. The bit values are defined in Table 154. |
|
displayName |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
description |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
writeMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
userWriteMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
value |
BaseDataType |
See OPC 10000-3 for the description of this Attribute. |
|
dataType |
NodeId |
See OPC 10000-3 for the description of this Attribute. |
|
valueRank |
Int32 |
See OPC 10000-3 for the description of this Attribute. |
|
arrayDimensions |
UInt32 [] |
See OPC 10000-3 for the description of this Attribute. |
|
isAbstract |
Boolean |
See OPC 10000-3 for the description of this Attribute. |
Table 160 defines the ReferenceTypeAttributes parameter.
Table 160 – ReferenceTypeAttributes
|
Name |
Type |
Description |
|
ReferenceTypeAttributes |
structure |
Defines the Attributes for the ReferenceType NodeClass. |
|
specifiedAttributes |
UInt32 |
A bit mask that indicates which fields contain valid values. A field shall be ignored if the corresponding bit is set to 0. The bit values are defined in Table 154. |
|
displayName |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
description |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
writeMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
userWriteMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
isAbstract |
Boolean |
See OPC 10000-3 for the description of this Attribute. |
|
symmetric |
Boolean |
See OPC 10000-3 for the description of this Attribute. |
|
inverseName |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
Table 161 defines the DataTypeAttributes parameter.
Table 161 – DataTypeAttributes
|
Name |
Type |
Description |
|
DataTypeAttributes |
structure |
Defines the Attributes for the DataType NodeClass. |
|
specifiedAttributes |
UInt32 |
A bit mask that indicates which fields contain valid values. A field shall be ignored if the corresponding bit is set to 0. The bit values are defined in Table 154. |
|
displayName |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
description |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
writeMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
userWriteMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
isAbstract |
Boolean |
See OPC 10000-3 for the description of this Attribute. |
Table 162 defines the ViewAttributes parameter.
|
Name |
Type |
Description |
|
ViewAttributes |
structure |
Defines the Attributes for the View NodeClass. |
|
specifiedAttributes |
UInt32 |
A bit mask that indicates which fields contain valid values. A field shall be ignored if the corresponding bit is set to 0. The bit values are defined in Table 154. |
|
displayName |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
description |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
writeMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
userWriteMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
containsNoLoops |
Boolean |
See OPC 10000-3 for the description of this Attribute. |
|
eventNotifier |
Byte |
See OPC 10000-3 for the description of this Attribute. |
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 163 defines the GenericAttributes parameter.
|
Name |
Type |
Description |
|
GenericAttributes |
structure |
Defines a generic structure for passing in any number of Attributes. |
|
specifiedAttributes |
UInt32 |
A bit mask that indicates which fields contain valid values. A field shall be ignored if the corresponding bit is set to 0. The bit values are defined in Table 154. |
|
displayName |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
description |
LocalizedText |
See OPC 10000-3 for the description of this Attribute. |
|
writeMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
userWriteMask |
UInt32 |
See OPC 10000-3 for the description of this Attribute. |
|
attributeValues |
GenericAttributeValue [] |
Defines one attributeId and value combination. |
|
attributeId |
IntegerId |
Id of the Attribute specified. AttributeIds shall be unique in the list and shall not repeat the common Attributes in the structure. |
|
value |
BaseDataType |
Value of the Attribute specified. |
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 164. 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.
Table 164 – NotificationData parameterTypeIds
|
Symbolic Id |
Description |
|
DataChange |
Notification data parameter used for data change Notifications. |
|
Event |
Notification data parameter used for Event Notifications. |
|
StatusChange |
Notification data parameter used for Subscription status change Notifications. |
Table 165 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:
- if the MonitoringMode is set to REPORTING and a change in value or its status (represented by its StatusCode) is detected;
- 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.
Table 165 – DataChangeNotification
|
Name |
Type |
Description |
|
DataChangeNotification |
structure |
Data change Notification data. |
|
monitoredItems [] |
MonitoredItem Notification |
The list of MonitoredItems for which a change has been detected. This structure is defined in-line with the following indented items. |
|
clientHandle |
IntegerId |
Client-supplied handle for the MonitoredItem. The IntegerId type is defined in 7.19 |
|
Value |
DataValue |
The StatusCode, value and timestamp(s) of the monitored Attribute depending on the sampling and queuing configuration. If the StatusCode indicates an error then the value is to be ignored. If not every detected change has been returned since the Server's queue buffer for the MonitoredItem reached its limit and had to purge out data and the size of the queue is larger than one, the Overflow bit in the DataValue InfoBits of the statusCode is set. |
|
diagnosticInfos [] |
DiagnosticInfo |
List of diagnostic information. The size and order of this list matches the size and order of the monitoredItems parameter. There is one entry in this list for each Node contained in the monitoredItems parameter. This list is empty if diagnostics information was not requested or is not available for any of the MonitoredItems. DiagnosticInfo is a common type defined in 7.12. |
Table 166 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.
Table 166 – EventNotificationList
|
Name |
Type |
Description |
|
EventNotificationList |
structure |
Event Notification data. |
|
events [] |
EventFieldList |
The list of Events being delivered. This structure is defined in-line with the following indented items. |
|
clientHandle |
IntegerId |
Client-supplied handle for the MonitoredItem. The IntegerId type is defined in 7.19. |
|
eventFields [] |
BaseDataType |
List of selected Event fields. This shall be a one to one match with the fields selected in the EventFilter. 7.22.3 specifies how the Server shall deal with error conditions. |
Table 167 defines the NotificationData parameter used for a StatusChangeNotification.
The StatusChangeNotification informs the Client about a change in the status of a Subscription.
Table 167 – StatusChangeNotification
|
Name |
Type |
Description |
|
StatusChangeNotification |
structure |
Event Notification data |
|
status |
StatusCode |
The StatusCode that indicates the status change. |
|
diagnosticInfo |
DiagnosticInfo |
Diagnostic information for the status change |
The components of this parameter are defined in Table 168.
Table 168 – NotificationMessage
|
Name |
Type |
Description |
|
NotificationMessage |
structure |
The Message that contains one or more Notifications. |
|
sequenceNumber |
Counter |
The sequence number of the NotificationMessage. |
|
publishTime |
UtcTime |
The time that this Message was sent to the Client. If this Message is retransmitted to the Client, this parameter contains the time it was first transmitted to the Client. |
|
notificationData [] |
Extensible Parameter NotificationData |
The list of NotificationData structures. The NotificationData parameter type is an extensible parameter type specified in 7.25. It specifies the types of Notifications that can be sent. The ExtensibleParameter type is specified in 7.17. Notifications of the same type should be grouped into one NotificationData element. If a Subscription contains MonitoredItems for events and data, this array should have not more than 2 elements. If the Subscription contains MonitoredItems only for data or only for events, the array size should always be one for this Subscription. |
This parameter is defined in Table 169. A formal BNF definition of the numeric range can be found in Clause A.3.
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.
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.
|
Name |
Type |
Description |
|
NumericRange |
String |
A number or a numeric range. A null or empty string indicates that this parameter is not used. |
The components of this parameter are defined in Table 170.
|
Name |
Type |
Description |
|
QueryDataSet |
structure |
Data related to a Node returned in a Query response. |
|
nodeId |
ExpandedNodeId |
|
|
typeDefinitionNode |
ExpandedNodeId |
The NodeId for the type definition for this Node description. |
|
values [] |
BaseDataType |
Values for the selected Attributes. The order of returned items matches the order of the requested items. There is an entry for each requested item for the given TypeDefinitionNode that matches the selected instance, this includes any related nodes that were specified using a relative path from the selected instance’s TypeDefinitionNode. If no values where found for a given requested item a null value is returned for that item. If a value has a bad status, the StatusCode is returned instead of the value. If multiple values exist for a requested item then an array of values is returned. If the requested item is a reference then a ReferenceDescription or array of ReferenceDescription is returned for that item. If the QueryDataSet is returned in a QueryNext to continue a list of ReferenceDescription, the values array will have the same size but the other values already returned are null. |
The components of this parameter are defined in Table 171.
|
Name |
Type |
Description |
||||||
|
ReadValueId |
structure |
Identifier for an item to read or to monitor. |
||||||
|
nodeId |
NodeId |
|||||||
|
attributeId |
IntegerId |
Id of the Attribute. This shall be a valid Attribute id. The IntegerId is defined in 7.19. The IntegerIds for the Attributes are defined in OPC 10000-6. |
||||||
|
indexRange |
NumericRange |
This parameter is used to identify a single element of an array, or a single range of indexes for arrays. The array in this context includes String and ByteString. If a range of elements is specified, the values are returned as a composite. The first element is identified by index 0 (zero). The NumericRange type is defined in 7.27. This parameter is null or empty if the specified Attribute is not an array. However, if the specified Attribute is an array, and this parameter is null or empty, then all elements are to be included in the range. |
||||||
|
dataEncoding |
QualifiedName |
This parameter specifies the BrowseName of the DataTypeEncoding that the Server should use when returning the Value Attribute of a Variable. It is an error to specify this parameter for other Attributes. This parameter only applies if the DataType of the Variable is a subtype of Structure. It is an error to specify this parameter if the DataType of the Variable is not a subtype of Structure. A Client can discover what DataTypeEncodings are available by following the HasEncoding Reference from the DataType Node for a Variable. OPC UA defines BrowseNames which Servers shall recognize even if the DataType Nodes are not visible in the Server AddressSpace. These BrowseNames are:
Each DataType shall support at least one of these encodings. DataTypes that do not have a true binary encoding (e.g. they only have a non-XML text encoding) should use the Default Binary name to identify the encoding that is considered to be the default non-XML encoding. DataTypes that support at least one XML-based encoding shall identify one of the encodings as the Default XML encoding. Other standards bodies may define other well-known data encodings that could be supported. If this parameter is null or empty then the Server shall choose the default according to what Message encoding (see OPC 10000-6) is used for the Session. If the Server does not support the encoding that matches the Message encoding then the Server shall choose the default encoding that it does support. |
The components of this parameter are defined in Table 172.
Table 172 – ReferenceDescription
|
Name |
Type |
Description |
|
ReferenceDescription |
structure |
|
|
referenceTypeId |
NodeId |
NodeId of the ReferenceType that defines the Reference. |
|
isForward |
Boolean |
If the value is TRUE, the Server followed a forward Reference. If the value is FALSE, the Server followed an inverse Reference. |
|
nodeId |
Expanded NodeId |
NodeId of the TargetNode as assigned by the Server identified by the Server index. The ExpandedNodeId type is defined in 7.16. If the server Index indicates that the TargetNode is a remote Node, then the nodeId shall contain the absolute namespace URI. If the TargetNode is a local Node the nodeId shall contain the namespace index. |
|
browseName1 |
QualifiedName |
The BrowseName of the TargetNode. |
|
displayName |
LocalizedText |
The DisplayName of the TargetNode. |
|
nodeClass1 |
NodeClass |
NodeClass of the TargetNode. |
|
typeDefinition1 |
Expanded NodeId |
Type definition NodeId of the TargetNode. Type definitions are only available for the NodeClasses Object and Variable. For all other NodeClasses a null NodeId shall be returned. |
|
1)If the Server index in the ExpandedNodeId indicates that the TargetNode is a remote Node, then the browseName, nodeClass and typeDefinition may be null or empty. If they are not null or empty, they might not be up to date because the local Server might not continuously monitor the remote Server for changes. The displayName shall be provided for remote Nodes. |
||
The components of this parameter are defined in Table 173.
|
Name |
Type |
Description |
|
RelativePath |
structure |
Defines a sequence of References and BrowseNames to follow. |
|
elements [] |
RelativePath Element |
A sequence of References and BrowseNames to follow. This structure is defined in-line with the following indented items. Each element in the sequence is processed by finding the targets and then using those targets as the starting nodes for the next element. The targets of the final element are the target of the RelativePath. |
|
referenceTypeId |
NodeId |
The type of reference to follow from the current node. The current path cannot be followed any further if the referenceTypeId is not available on the Node instance. If the referenceTypeId is null then all References are included and the parameter includeSubtypes is ignored. This is equal to use the base References ReferenceType and includeSubtypes set to TRUE. |
|
isInverse |
Boolean |
Only inverse references shall be followed if this value is TRUE. Only forward references shall be followed if this value is FALSE. |
|
includeSubtypes |
Boolean |
Indicates whether subtypes of the ReferenceType should be followed. Subtypes are included if this value is TRUE. |
|
targetName |
QualifiedName |
The BrowseName of the target node. The final element may have an empty targetName. In this situation all targets of the references identified by the referenceTypeId are the targets of the RelativePath. The targetName shall be specified for all other elements. The current path cannot be followed any further if no targets with the specified BrowseName exist. |
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.
The components of this parameter are defined in Table 174.
|
Name |
Type |
Description |
|
RegisteredServer |
structure |
The Server to register. |
|
serverUri |
String |
The globally unique identifier for the Server instance. The serverUri matches the applicationUri from the ApplicationDescription defined in 7.2. |
|
productUri |
String |
The globally unique identifier for the Server product. |
|
serverNames [] |
LocalizedText |
A list of localized descriptive names for the Server. The list shall have at least one valid entry. |
|
serverType |
Enum ApplicationType |
The type of application. The enumeration values are defined in Table 113. The value “CLIENT” (The application is a Client) is not allowed. The Service result shall be Bad_InvalidArgument in this case. |
|
gatewayServerUri |
String |
The URI of the Gateway Server associated with the discoveryUrls. This value is only specified by Gateway Servers that wish to register the Servers that they provide access to. For Servers that do not act as a Gateway Server this parameter shall be null or empty. |
|
discoveryUrls [] |
String |
A list of DiscoveryEndpoints for the Server. The list shall have at least one valid entry. |
|
semaphoreFilePath |
String |
The path to the semaphore file used to identify an automatically-launched Server instance; Manually-launched Servers will not use this parameter. If a Semaphore file is provided, the isOnline flag is ignored. If a Semaphore file is provided and exists, the LocalDiscoveryServer shall save the registration information in a persistent data store that it reads whenever the LocalDiscoveryServer starts. If a Semaphore file is specified but does not exist the Discovery Server shall remove the registration from any persistent data store. If the Server has registered with a semaphoreFilePath, the Discovery Server shall check that this file exists before returning the ApplicationDescription to the Client. If the Server did not register with a semaphoreFilePath (it is null or empty) then the Discovery Server does not attempt to verify the existence of the file before returning the ApplicationDescription to the Client. |
|
isOnline |
Boolean |
True if the Server is currently able to accept connections from Clients. The Discovery Server shall return ApplicationDescriptions to the Client. The Server is expected to periodically re-register with the Discovery Server. False if the Server is currently unable to accept connections from Clients. The Discovery Server shall NOT return ApplicationDescriptions to the Client. This parameter is ignored if a semaphoreFilePath is provided. |
The components of this parameter are defined in Table 175.
|
Name |
Type |
Description |
||||||||||||||||||||||||||||||||||||
|
RequestHeader |
structure |
Common parameters for all requests submitted on a Session. |
||||||||||||||||||||||||||||||||||||
|
authenticationToken |
Session AuthenticationToken |
The secret Session identifier used to verify that the request is associated with the Session. The SessionAuthenticationToken type is defined in 7.36. |
||||||||||||||||||||||||||||||||||||
|
timestamp |
UtcTime |
The time the Client sent the request. The parameter is only used for diagnostic and logging purposes in the Server. |
||||||||||||||||||||||||||||||||||||
|
requestHandle |
IntegerId |
A requestHandle associated with the request. This Client defined handle can be used to cancel the request. It is also returned in the response. |
||||||||||||||||||||||||||||||||||||
|
returnDiagnostics |
UInt32 |
A bit mask that identifies the types of vendor-specific diagnostics to be returned in diagnosticInfo r esponse parameters. The value of this parameter may consist of zero, one or more of the following values. No value indicates that diagnostics are not to be returned.
Each of these values is composed of two components, level and type, as described below. If none are requested, as indicated by a 0 value, or if no diagnostic information was encountered in processing of the request, then diagnostics information is not returned.
Type:
|
||||||||||||||||||||||||||||||||||||
|
auditEntryId |
String |
An identifier that identifies the Client’s security audit log entry associated with this request. An empty string value means that this parameter is not used. The auditEntryId typically contains who initiated the action and from where it was initiated. The auditEntryId is included in the AuditEvent to allow human readers to correlate an Event with the initiating action. More details of the Audit mechanisms are defined in 6.5 and in OPC 10000-3. |
||||||||||||||||||||||||||||||||||||
|
timeoutHint |
UInt32 |
This timeout in milliseconds is used in the Client side Communication Stack to set the timeout on a per-call base. For a Server this timeout is only a hint and can be used to cancel long running operations to free resources. If the Server detects a timeout, he can cancel the operation by sending the Service result Bad_Timeout. The Server should wait at minimum the timeout after he received the request before cancelling the operation. The Server shall check the timeoutHint parameter of a Publish request before processing a Publish response. If the request timed out, a Bad_Timeout Service result is sent and another Publish request is used. The value of 0 indicates no timeout. |
||||||||||||||||||||||||||||||||||||
|
additionalHeader |
Extensible Parameter AdditionalHeader |
If additional header parameters are needed, they shall be passed using the AdditionalParametersType defined in 7.1. Applications that do not understand the header should ignore it. |
The components of this parameter are defined in Table 176.
|
Name |
Type |
Description |
|
ResponseHeader |
structure |
Common parameters for all responses. |
|
timestamp |
UtcTime |
The time the Server sent the response. |
|
requestHandle |
IntegerId |
The requestHandle given by the Client to the request. |
|
serviceResult |
StatusCode |
OPC UA-defined result of the Service invocation. The StatusCode type is defined in 7.39. |
|
serviceDiagnostics |
DiagnosticInfo |
Diagnostic information for the Service invocation. This parameter is empty if diagnostics information was not requested in the request header. The DiagnosticInfo type is defined in 7.12. |
|
stringTable [] |
String |
There is one string in this list for each unique namespace, symbolic identifier, and localized text string contained in all of the diagnostics information parameters contained in the response (see 7.12). Each is identified within this table by its zero-based index. |
|
additionalHeader |
Extensible Parameter AdditionalHeader |
If additional header parameters are needed, they shall be passed using the AdditionalParametersType defined in 7.1. Applications that do not understand the header should ignore it. |
The components of this parameter are defined in Table 177.
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.
The exact use of this parameter depends on the mappings defined in OPC 10000-6.
|
Name |
Type |
Description |
|
ServiceFault |
structure |
An error response sent when a service level error occurs. |
|
responseHeader |
ResponseHeader |
Common response parameters (see 7.34 for ResponseHeader definition). |
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.
Figure 37 – Logical layers of a Server
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.
Figure 38 – Obtaining a SessionAuthenticationToken
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.
The components of this parameter are defined in Table 178.
|
Name |
Type |
Description |
|
SignatureData |
structure |
Contains a digital signature created with a Certificate. |
|
algorithm |
String |
A string containing the URI of the algorithm. The URI string values are defined as part of the security profiles specified in OPC 10000-7. |
|
signature |
ByteString |
This is a signature generated with the private key associated with a Certificate. |
NoteDetails on SoftwareCertificates will be defined in a future version of this document.
Table 179 specifies SignedSoftwareCertificate Structure.
Table 179 – SignedSoftwareCertificate
|
Name |
Type |
Description |
|
SignedSoftwareCertificate |
structure |
|
|
certificateData |
ByteString |
The certificate data serialized as a ByteString. |
|
signature |
ByteString |
The signature for the certificateData. |
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 180.
Table 180 – StatusCode bit assignments
|
Field |
Bit Range |
Description |
||||||||||||
|
Severity |
30:31 |
Indicates whether the StatusCode represents a good, bad or uncertain condition. These bits have the following meanings:
|
||||||||||||
|
Reserved |
29:29 |
Reserved for use in OPC UA application specific APIs. This bit shall always be zero on the wire but may be used by OPC UA application specific APIs for API specific status codes. |
||||||||||||
|
Reserved |
28:28 |
Reserved for future use. Shall always be zero. |
||||||||||||
|
SubCode |
16:27 |
The code is a numeric value assigned to represent different conditions. Each code has a symbolic name and a numeric value. All descriptions in the OPC UA specification refer to the symbolic name. OPC 10000-6 maps the symbolic names onto a numeric value. |
||||||||||||
|
StructureChanged |
15:15 |
Indicates that the structure of the associated data value has changed since the last Notification. Clients should not process the data value unless they re-read the metadata. Servers shall set this bit if the DataTypeDefinition of the DataType used for a Variable changes. This bit is provided to warn Clients that parse complex data values that their parsing routines could fail because the serialized form of the data value has changed. This bit has meaning only for StatusCodes returned as part of a data change Notification or the HistoryRead. StatusCodes used in other contexts shall always set this bit to zero. The bit is set on one data change Notification per MonitoredItem that samples values at the time the structure change happened. If the data change notification with the bit set is deleted because of a queue overflow, the bit shall be set on the next data change notification in the queue. |
||||||||||||
|
SemanticsChanged |
14:14 |
Indicates that the semantics of the associated data value have changed. Clients should not process the data value until they re-read the metadata associated with the Variable. Servers should set this bit if the metadata has changed in way that could cause application errors if the Client does not re-read the metadata. For example, a change to the engineering units could create problems if the Client uses the value to perform calculations. OPC 10000-8 defines the conditions where a Server shall set this bit for a DA Variable. Other specifications may define additional conditions. A Server may define other conditions that cause this bit to be set. This bit has meaning only for StatusCodes returned as part of a data change Notification or the HistoryRead. StatusCodes used in other contexts shall always set this bit to zero. The bit is set on one data change Notification per MonitoredItem that samples values at the time the semantic change happened. If the data change notification with the bit set is deleted because of a queue overflow, the bit shall be set on the next data change notification in the queue. |
||||||||||||
|
Reserved |
12:13 |
Reserved for future use. Shall always be zero. |
||||||||||||
|
InfoType |
10:11 |
The type of information contained in the info bits. These bits have the following meanings:
|
||||||||||||
|
InfoBits |
0:9 |
Additional information bits that qualify the StatusCode. The structure of these bits depends on the Info Type field. |
Table 181 describes the structure of the InfoBits when the Info Type is set to DataValue (01).
Table 181 – DataValue InfoBits
|
Info Type |
Bit Range |
Description |
|||||||||||||||||||||
|
LimitBits |
8:9 |
The limit bits associated with the data value. The limits bits have the following meanings:
|
|||||||||||||||||||||
|
Overflow |
7 |
This bit shall only be set if the MonitoredItem queue size is greater than 1. If this bit is set, not every detected change has been returned since the Server’s queue buffer for the MonitoredItem reached its limit and had to purge out data. |
|||||||||||||||||||||
|
Reserved |
5:6 |
Reserved for future use. Shall always be zero. |
|||||||||||||||||||||
|
HistorianBits |
0:4 |
These bits are set only when reading historical data. They indicate where the data value came from and provide information that affects how the Client uses the data value. The historian bits have the following meaning:
OPC 10000-11 describes how these bits are used in more detail. |
Table 182 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 182 – Common Service Result Codes
|
Symbolic Id |
Description |
|
Good |
The operation was successful. |
|
Good_CompletesAsynchronously |
The processing will complete asynchronously. |
|
Good_SubscriptionTransferred |
The Subscription was transferred to another session. |
|
|
|
|
Bad_CertificateHostNameInvalid
|
The HostName used to connect to a Server does not match a HostName in the Certificate. |
|
Bad_CertificateChainIncomplete |
The Certificate chain is incomplete. |
|
Bad_CertificateIssuerRevocationUnknown |
It was not possible to determine if the Issuer Certificate has been revoked. |
|
Bad_CertificateIssuerUseNotAllowed |
The Issuer Certificate may not be used for the requested operation. |
|
Bad_CertificateIssuerTimeInvalid |
An Issuer Certificate has expired or is not yet valid. |
|
Bad_CertificateIssuerRevoked |
The Issuer Certificate has been revoked. |
|
Bad_CertificateInvalid |
The Certificate provided as a parameter is not valid. |
|
Bad_CertificateRevocationUnknown |
It was not possible to determine if the Certificate has been revoked. |
|
Bad_CertificateRevoked |
The Certificate has been revoked. |
|
Bad_CertificateTimeInvalid |
The Certificate has expired or is not yet valid. |
|
Bad_CertificateUriInvalid |
The URI specified in the ApplicationDescription does not match the URI in the Certificate. |
|
Bad_CertificateUntrusted |
The Certificate is not trusted. |
|
Bad_CertificateUseNotAllowed |
The Certificate may not be used for the requested operation. |
|
Bad_CommunicationError |
A low level communication error occurred. |
|
Bad_DataTypeIdUnknown |
The ExtensionObject cannot be (de)serialized because the data type id is not recognized. |
|
Bad_DecodingError |
Decoding halted because of invalid data in the stream. |
|
Bad_EncodingError |
Encoding halted because of invalid data in the objects being serialized. |
|
Bad_EncodingLimitsExceeded |
The message encoding/decoding limits imposed by the Communication Stack have been exceeded. |
|
Bad_IdentityTokenInvalid |
The user identity token is not valid. |
|
Bad_IdentityTokenRejected |
The user identity token is valid but the Server has rejected it. |
|
Bad_InternalError |
An internal error occurred as a result of a programming or configuration error. |
|
Bad_InvalidArgument |
One or more arguments are invalid. Each service defines parameter-specific StatusCodes and these StatusCodes shall be used instead of this general error code. This error code shall be used only by the Communication Stack and in services where it is defined in the list of valid StatusCodes for the service. |
|
Bad_InvalidState |
The operation cannot be completed because the object is closed, uninitialized or in some other invalid state. |
|
Bad_InvalidTimestamp |
The timestamp is outside the range allowed by the Server. |
|
Bad_LicenseExpired |
The UA Server requires a license to operate in general or to perform a service or operation, but existing license is expired |
|
Bad_LicenseLimitsExceeded |
The UA Server has limits on number of allowed operations / objects, based on installed licenses, and these limits where exceeded. |
|
Bad_LicenseNotAvailable |
The UA Server does not have a license which is required to operate in general or to perform a service or operation. |
|
Bad_NonceInvalid |
The nonce does appear to be not a random value or it is not the correct length. |
|
Bad_NothingToDo |
No processing could be done because there was nothing to do. For Service level results the code is used if the Client passed a list of operations with no elements. |
|
Bad_OutOfMemory |
Not enough memory to complete the operation. |
|
Bad_RequestCancelledByClient |
The request was cancelled by the Client. |
|
Bad_RequestTooLarge |
The request message size exceeds limits set by the Server. |
|
Bad_ResponseTooLarge |
The response message size exceeds limits set by the Client or Server. |
|
Bad_RequestHeaderInvalid |
The header for the request is missing or invalid. |
|
Bad_ResourceUnavailable |
An operating system resource is not available. |
|
Bad_SecureChannelIdInvalid |
The specified secure channel is no longer valid. |
|
Bad_SecurityChecksFailed |
An error occurred while verifying security. |
|
Bad_SecurityPolicyRejected |
The security policy does not meet the requirements set by the Server. |
|
Bad_ServerHalted |
The Server has stopped and cannot process any requests. |
|
Bad_ServerNotConnected |
The operation could not complete because the Client is not connected to the Server. |
|
Bad_ServerTooBusy |
The Server does not have the resources to process the request at this time. This can be caused by a general overload of the Server or an overload by the Client that receives the result code. |
|
Bad_ServerUriInvalid |
The Server URI is not valid. |
|
Bad_ServiceUnsupported |
The Server does not support the requested service. |
|
Bad_SessionIdInvalid |
The Session id is not valid. |
|
Bad_SessionClosed |
|
|
Bad_SessionNotActivated |
The Session cannot be used because ActivateSession has not been called. |
|
Bad_Shutdown |
The operation was cancelled because the application is shutting down. |
|
Bad_SubscriptionIdInvalid |
The Subscription id is not valid. The Subscription id is not known or is not valid in the context of the Session used to call the Subscription related Service. |
|
Bad_Timeout |
The operation timed out. |
|
Bad_TimestampsToReturnInvalid |
The timestamps to return parameter is invalid. |
|
Bad_TooManyOperations |
The request could not be processed because it specified too many operations. |
|
Bad_UnexpectedError |
An unexpected error occurred. |
|
Bad_UnknownResponse |
An unrecognized response was received from the Server. |
|
Bad_UserAccessDenied |
User does not have permission to perform the requested operation. |
|
Bad_ViewIdUnknown |
The view id does not refer to a valid view Node. |
|
Bad_ViewTimestampInvalid |
The view timestamp is not available or not supported. |
|
Bad_ViewParameterMismatchInvalid |
The view parameters are not consistent with each other. |
|
Bad_ViewVersionInvalid |
The view version is not available or not supported. |
Table 183 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.
Table 183 – Common Operation Level Result Codes
|
Symbolic Id |
Description |
|
Good_Clamped |
The value written was accepted but was clamped. |
|
Good_Overload |
Sampling has slowed down due to resource limitations. |
|
|
|
|
Uncertain |
The value is uncertain but no specific reason is known. |
|
|
|
|
Bad |
The value is bad but no specific reason is known. |
|
Bad_AttributeIdInvalid |
The attribute is not supported for the specified node. |
|
Bad_BrowseDirectionInvalid |
The browse direction is not valid. |
|
Bad_BrowseNameInvalid |
The browse name is invalid. |
|
Bad_ContentFilterInvalid |
The content filter is not valid. |
|
Bad_ContinuationPointInvalid |
The continuation point provided is no longer valid. This status is returned if the continuation point was deleted or the address space was changed between the browse calls. |
|
Bad_DataEncodingInvalid |
The data encoding is invalid. This result is used if no dataEncoding can be applied because an Attribute other than Value was requested or the DataType of the Value Attribute is not a subtype of the Structure DataType. |
|
Bad_DataEncodingUnsupported |
The Server does not support the requested data encoding for the node. This result is used if a dataEncoding can be applied but the passed data encoding is not known to the Server. |
|
Bad_EventFilterInvalid |
The event filter is not valid. |
|
Bad_FilterNotAllowed |
A monitoring filter cannot be used in combination with the attribute specified. |
|
Bad_FilterOperandInvalid |
The operand used in a content filter is not valid. |
|
Bad_HistoryOperationInvalid |
The history details parameter is not valid. |
|
Bad_HistoryOperationUnsupported |
The Server does not support the requested operation. |
|
Bad_IndexRangeInvalid |
The syntax of the index range parameter is invalid. |
|
Bad_IndexRangeNoData |
No data exists within the range of indexes specified. |
|
Bad_MonitoredItemFilterInvalid |
The monitored item filter parameter is not valid. |
|
Bad_MonitoredItemFilterUnsupported |
The Server does not support the requested monitored item filter. |
|
Bad_MonitoredItemIdInvalid |
The monitoring item id does not refer to a valid monitored item. |
|
Bad_MonitoringModeInvalid |
The monitoring mode is invalid. |
|
Bad_NoCommunication |
Communication with the data source is defined, but not established, and there is no last known value available. This status/sub-status is used for cached values before the first value is received or for Write and Call if the communication is not established. |
|
Bad_NoContinuationPoints |
The operation could not be processed because all continuation points have been allocated. |
|
Bad_NodeClassInvalid |
The node class is not valid. |
|
Bad_NodeIdInvalid |
The syntax of the node id is not valid or refers to a node that is not valid for the operation. |
|
Bad_NodeIdUnknown |
The node id refers to a node that does not exist in the Server address space. |
|
Bad_NoDeleteRights |
The Server will not allow the node to be deleted. |
|
Bad_NodeNotInView |
The nodesToBrowse is not part of the view. |
|
Bad_NotFound |
A requested item was not found or a search operation ended without success. |
|
Bad_NotImplemented |
Requested operation is not implemented. |
|
Bad_NoValue |
There is no value available. The status is used if a Variable is created and no default value or no initial value is available. |
|
Bad_NotReadable |
The access level does not allow reading or subscribing to the Node. |
|
Bad_NotSupported |
The requested operation is not supported. |
|
Bad_NotWritable |
The access level does not allow writing to the Node. |
|
Bad_ObjectDeleted |
The Object cannot be used because it has been deleted. |
|
Bad_OutOfRange |
The value was out of range. |
|
Bad_ReferenceTypeIdInvalid |
The reference type id does not refer to a valid reference type node. |
|
Bad_SecurityModeInsufficient |
The SecurityPolicy and/or MessageSecurityMode do not match the Server requirements to complete the operation. For example, a user may have the right to receive the data but the data can only be transferred through an encrypted channel with an appropriate SecurityPolicy. |
|
Bad_SourceNodeIdInvalid |
The source node id does not refer to a valid node. |
|
Bad_StructureMissing |
A mandatory structured parameter was missing or null. |
|
Bad_TargetNodeIdInvalid |
The target node id does not refer to a valid node. |
|
Bad_TypeDefinitionInvalid |
The type definition node id does not reference an appropriate type node. |
|
Bad_TypeMismatch |
The value supplied for the attribute is not of the same type as the attribute's value. |
|
Bad_WaitingForInitialData |
Waiting for the Server to obtain values from the underlying data source. After creating a MonitoredItem or after setting the MonitoringMode from DISABLED to REPORTING or SAMPLING, it may take some time for the Server to actually obtain values for these items. In such cases the Server can send a Notification with this status prior to the Notification with the first value or status from the data source. |
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 184.
Table 184 – TimestampsToReturn values
|
Name |
Value |
Description |
|
SOURCE |
0 |
Return the source timestamp. |
|
SERVER |
1 |
Return the Server timestamp. |
|
BOTH |
2 |
Return both the source and Server timestamps. |
|
NEITHER |
3 |
Return neither timestamp. This is the default value for MonitoredItems if a Variable value is not being accessed. For HistoryRead this is not a valid setting. |
|
INVALID |
4 |
No value specified. |
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 185 defines the current set of user identity tokens. The ExtensibleParameter type is defined in 7.17.
Table 185 – UserIdentityToken parameterTypeIds
|
Symbolic Id |
Description |
|
AnonymousIdentityToken |
No user information is available. |
|
UserNameIdentityToken |
A user identified by user name and password. |
|
X509IdentityToken |
A user identified by an X.509 v3 Certificate. |
|
IssuedIdentityToken |
A user identified by a token issued by an external Authorization Service. |
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. Clients shall validate the Server Certificate and ensure it is trusted before sending a UserIdentityToken encrypted with the Certificate.
The legacy token secret format defined in 7.41.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.41.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.42.
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.
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 186 describes how to serialize UserIdentityTokens before applying encryption.
Table 186 – Legacy UserIdentityToken Encrypted Token Secret Format
|
Name |
Type |
Description |
|
Length |
Byte [4] |
The length of the data to be encrypted including the ServerNonce but excluding the length field. This field is a 4-byte unsigned integer encoded with the least significant bytes appearing first. |
|
tokenData |
Byte [*] |
The token data. |
|
serverNonce |
Byte [*] |
The last ServerNonce returned by the Server in the CreateSession or ActivateSession response. |
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.
Figure 39 – EncryptedSecret layout
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 187. 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 187. The first three fields TypeId, EncodingMask and Length belong to the ExtensionObject encoding defined in OPC 10000-6.
Table 187 – EncryptedSecret layout
|
Name |
Type |
Description |
|
TypeId |
NodeId |
|
|
EncodingMask |
Byte |
This value is always 1. |
|
Length |
Int32 |
The length of the data that follows including the Signature. |
|
SecurityPolicyUri |
String |
The URI for the SecurityPolicy used to apply security. |
|
Certificate |
ByteString |
The signing and/or encrypting Certificate. |
|
SigningTime |
DateTime |
When the Signature was created. |
|
KeyDataLength |
UInt16 |
The length, in bytes, of the KeyData that follows If the KeyData is encrypted this is the length of the encrypted data; Otherwise, it is the length of the unencrypted data. |
|
KeyData |
Byte [*] |
The key data used to create the keys needed for decrypting and verifying the payload using the SymmetricEncryptionAlgorithm specified by the SecurityPolicyUri. Each EncryptedSecret DataType describes how the key data is structured for different SecurityPolicies. |
|
Nonce |
ByteString |
This is the last serverNonce returned in the CreateSession or ActivateSession Response when a UserIdentityToken is passed with the ActivateSession Request. If used outside of an ActivateSession call, the Nonce is created by the sender and its length shall be between 32 and 128 bytes inclusive. |
|
Secret |
ByteString |
The secret to protect. The password when used with UserNameIdentityTokens. The tokenData when used with IssuedIdentityTokens. |
|
PayloadPadding |
Byte[*] |
Additional padding added to ensure the size of the encrypted payload is an integer multiple of the InitializationVectorLength specified by the SecurityPolicyUri. If the InitializationVectorLength is less than 16 bytes then 16 bytes are used instead. The value of each byte is the least significant byte of the PayloadPaddingSize. |
|
PayloadPaddingSize |
UInt16 |
The size of the padding added to the payload. |
|
Signature |
Byte[*] |
The Signature calculated after all encryption is applied. Each EncryptedSecret DataType describes how the Signature is calculated for different SecurityPolicies. |
The PayloadPaddingSize adjusted with the following formula:
If (Secret.Length + PayloadPaddingSize < InitializationVectorLength) Then
PayloadPaddingSize = PayloadPaddingSize + InitializationVectorLength
Where the InitializationVectorLength is specified by the SymmetricEncryptionAlgorithm.
The currently available EncryptedSecret DataTypes are defined in Table 188.
Table 188 – EncryptedSecret DataTypes
|
Type Name |
When to Use |
|
RsaEncryptedSecret |
Used when the SecurityPolicy requires the use of RSA cryptography. It is described in 7.41.2.4. |
|
EccEncryptedSecret |
Used when the SecurityPolicy requires the use of ECC cryptography.It is described in 7.41.2.5. |
The RsaEncryptedSecret uses RSA based Asymmetric Cryptography.
Additional semantics for the fields in the EncryptedSecret layout for the RsaEncryptedSecret Structure are described in Table 189.
Table 189 – RsaEncryptedSecret structure
|
Name |
Type |
Description |
|
TypeId |
NodeId |
The NodeId of the RsaEncryptedSecret DataType Node. |
|
EncodingMask |
Byte |
See Table 187. |
|
Length |
UInt32 |
See Table 187. |
|
SecurityPolicyUri |
String |
See Table 187. |
|
Certificate |
ByteString |
The SHA1 hash of the DER form of the Certificate used to encrypt the KeyData. |
|
SigningTime |
DateTime |
See Table 187. |
|
KeyDataLength |
UInt16 |
The length, in bytes, of the encrypted KeyData. |
|
KeyData |
|
The KeyData is encrypted with the PublicKey associated with the receiver of the EncryptedSecret. The creator of the EncryptedSecret generates the SigningKey, EncryptingKey and InitializationVector using a cryptographic random number generator with the lengths required by the SecurityPolicy. |
|
SigningKey |
ByteString |
The key used to compute the Signature. |
|
EncryptingKey |
ByteString |
The key used to encrypt payload. |
|
InitializationVector |
ByteString |
The initialization vector used with the EncryptingKey. |
|
Nonce |
ByteString |
A Nonce. This is the last ServerNonce returned in the CreateSession or ActivateSession Response when proving a UserIdentityToken passed in the ActivateSession Request. In other contexts, this is a Nonce created by the sender with a length between 32 and 128 bytes inclusive. |
|
Secret |
ByteString |
See Table 187. |
|
PayloadPadding |
Byte[*] |
See Table 187. |
|
PayloadPaddingSize |
UInt16 |
See Table 187. |
|
Signature |
Byte[*] |
The Signature calculated with the SigningKey using the SymmetricEncryptionAlgorithm from the SecurityPolicy. The Signature is calculated after encrypting the KeyData and the payload. The Signature can only be checked after the KeyData is decrypted. It allows the receiver to verify that the message has not beem tampered with. It does not provide any information about who created the EncryptedSecret. |
The EccEncryptedSecret uses ECC based Asymmetric Cryptography.
Additional semantics for the fields in the EncryptedSecret layout for the EccEncryptedSecret Structure are described in Table 190.
The EccEncryptedSecret uses ECC 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.
Table 190 – EccEncryptedSecret Layout
|
Name |
Type |
Description |
|
TypeId |
NodeId |
The NodeId of the EccEncryptedSecret DataType Node. |
|
EncodingMask |
Byte |
See Table 187 |
|
Length |
UInt32 |
See Table 187 |
|
SecurityPolicyUri |
String |
See Table 187 |
|
Certificate |
ByteString |
The signing Certificate encoded in DER form. The value shall include the entire chain. This value may be null or empty if the SigningCertificate is known to the receiver. This is true if the structure is used to provide a UserIdentityToken to a Server over a SecureChannel and the SigningCertificate is the Client ApplicationInstance Certificate. |
|
SigningTime |
DateTime |
See Table 187 |
|
KeyDataLength |
UInt16 |
The length of the KeyData without encryption. |
|
KeyData |
|
The KeyData is not encrypted. |
|
SenderPublicKey |
ByteString |
The Public Key for the EphemeralKey created by the sender. |
|
ReceiverPublicKey |
ByteString |
The Public Key for the EphemeralKey created by the receiver. |
|
Nonce |
ByteString |
A Nonce. This is the last ServerNonce returned in the CreateSession or ActivateSession Response when proving a UserIdentityToken passed in the ActivateSession Request. In other contexts, this is a Nonce created by the sender with a length between 32 and 128 bytes inclusive. |
|
Secret |
ByteString |
See Table 187 |
|
PayloadPadding |
Byte [*] |
See Table 187 |
|
PayloadPaddingSize |
UInt16 |
See Table 187 |
|
Signature |
Byte [*] |
When using AuthenticatedEncryption the Signature has two parts: the Signature produced when the secret is encrypted using the SymmetricEncryptionAlgorithm and the Signature calculated using the Certificate and the AsymmetricSignatureAlgorithm. Both Signatures are calculated from the start of the packet. The AsymmetricSignatureAlgorithm Signature includes the SymmetricEncryptionAlgorithm Signature. When using UnauthenticatedEncryption the Signature is only calculated using the Certificate and the AsymmetricSignatureAlgorithm. |
The AnonymousIdentityToken is used to indicate that the Client has no user credentials.
Table 191 defines the AnonymousIdentityToken parameter.
Table 191 – AnonymousIdentityToken
|
Name |
Type |
Description |
|
AnonymousIdentityToken |
Structure |
An anonymous user identity. |
|
policyId |
String |
An identifier for the UserTokenPolicy that the token conforms to. The UserTokenPolicy structure is defined in 7.42. Servers that provide a null or empty PolicyId shall accept null or empty and treat them as equal. |
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 UserTokenPolic y. 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 193 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.41.2.4. For passwords that do not exceed 64 bytes, it is encrypted and serialized as described in 7.41.2.2. When using the ECC based SecurityPolicies the password is encrypted and serialized as described in 7.41.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 192 defines the UserNameIdentityToken parameter.
Table 192 – UserNameIdentityToken
|
Name |
Type |
Description |
|
UserNameIdentityToken |
Structure |
UserName value. |
|
policyId |
String |
An identifier for the UserTokenPolicy that the token conforms to. The UserTokenPolicy structure is defined in 7.42. Servers that provide a null or empty PolicyId shall accept null or empty and treat them as equal. |
|
userName |
String |
A string that identifies the user. |
|
password |
ByteString |
The password for the user. The password can be an empty string. The format used for the encrypted data is described in 7.41.2.2. |
|
encryptionAlgorithm |
String |
A string containing the URI of the AsymmetricEncryptionAlgorithm. The URI string values are defined names that may be used as part of the security profiles specified in OPC 10000-7. This parameter is null or empty if the password is not encrypted. |
Table 193 describes the dependencies for selecting the AsymmetricEncryptionAlgorithm for the UserNameIdentityToken. 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.
Table 193 – EncryptionAlgorithm selection
|
SecureChannel SecurityPolicy |
SecureChannel SecurityMode |
UserTokenPolicy SecurityPolicy |
UserIdentityToken EncryptionAlgorithm |
|
Security Policy - None |
NONE |
Null or empty |
No encryption (a) |
|
Security Policy - None |
NONE |
Security Policy - None |
No encryption (a) |
|
Security Policy - None |
NONE |
Security Policy - Other |
Asymmetric algorithm for "Other" |
|
Security Policy - Other |
Other than NONE |
Null or empty |
Asymmetric algorithm for "Other" |
|
Security Policy - Other |
Other than NONE |
Security Policy - Yet another |
Asymmetric algorithm for "Yet another" |
|
Security Policy - Other |
Other than NONE |
Security Policy - Other |
Asymmetric algorithm for "Other" |
|
Security Policy - Other |
SIGNANDENCRYPT |
Security Policy - None |
No encryption but encrypted SecureChannel |
|
Security Policy - Other |
SIGN |
Security Policy - None |
Invalid configuration shall be rejected. |
|
(a)The use of this configuration without network encryption would result in a serious security fault. |
|||
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.
Table 194 defines the X509IdentityToken parameter.
Table 194 – X.509 v3 Identity Token
|
Name |
Type |
Description |
|
X509IdentityToken |
structure |
X.509 v3 value. |
|
policyId |
String |
An identifier for the UserTokenPolicy that the token conforms to. The UserTokenPolicy structure is defined in 7.42. Servers that provide a null or empty PolicyId shall accept null or empty and treat them as equal. |
|
certificateData |
ByteString |
The X.509 v3 Certificate in DER format. |
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.41.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 UserTokenPolic y.
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.42).
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. Clients should renew the token with ActivateSession before the expiration time to avoid communication interruption.
Table 195 defines the IssuedIdentityToken parameter.
Table 195 – IssuedIdentityToken
|
Name |
Type |
Description |
|
IssuedIdentityToken |
structure |
The token provided by an Authorization Service. |
|
policyId |
String |
An identifier for the UserTokenPolicy that the token conforms to. The UserTokenPolicy structure is defined in 7.42. Servers that provide a null or empty PolicyId shall accept null or empty and treat them as equal. |
|
tokenData |
ByteString |
The text or binary representation of the token. The format of the data depends on the associated UserTokenPolicy. |
|
encryptionAlgorithm |
String |
The URI of the AsymmetricEncryptionAlgorithm. The list of OPC UA-defined names that may be used is specified in OPC 10000-7. See Table 193 for details on picking the correct URI. This parameter is null or empty if the tokenData is not encrypted or if the EncryptedSecret format is used. |
The components of this parameter are defined in Table 196.
|
Name |
Type |
Description |
|
UserTokenPolicy |
structure |
Specifies a UserIdentityToken that a Server will accept. |
|
policyId |
String |
An identifier for the UserTokenPolicy assigned by the Server. The identifier may be null or empty. Null or empty are equal. The identifier shall be unique across the UserTokenPolicies assigned by the Server. The Client specifies this value when it constructs a UserIdentityToken that conforms to the policy. This value is only unique within the context of a single Server. |
|
tokenType |
Enum User TokenType |
The type of user identity token required. The UserTokenType is defined in 7.43 A tokenType of ANONYMOUS indicates that the Server does not require any user identification. In this case, the Client Application Instance Certificate is used as the user identification. |
|
issuedTokenType |
String |
A URI for the type of token. OPC 10000-6 defines URIs for common issued token types. Vendors may specify their own token types. This field may only be specified if TokenType is ISSUEDTOKEN. |
|
issuerEndpointUrl |
String |
An optional string which depends on the Authorization Service. The meaning of this value depends on the issuedTokenType. Further details for the different token types are defined in OPC 10000-6. For JWTs this is a JSON object with fields defined in OPC 10000-6. |
|
securityPolicyUri |
String |
The security policy to use when encrypting or signing the UserIdentityToken when it is passed to the Server in the ActivateSession request. Clause 7.41 describes how this parameter is used. The security policy for the SecureChannel is used if this value is null or empty. |
The UserTokenType is an enumeration that specifies the user identity token type. The possible values are described in Table 197.
Table 197 – UserTokenType values
|
Name |
Value |
Description |
|
ANONYMOUS |
0 |
No token is required. |
|
USERNAME |
1 |
A username/password token. |
|
CERTIFICATE |
2 |
An X.509 v3 Certificate token. |
|
ISSUEDTOKEN |
3 |
Any token issued by an Authorization Service. |
This primitive data type is a UInt32 that represents the time in seconds since the year 2000. The epoch date is midnight UTC (00:00) on January 1, 2000.
It is used as version number based on the last change time. If the version is updated, the new value shall be greater than the previous value.
If a Variable is initialized with a VersionTime value, the value shall be either loaded from persisted configuration or time synchronization shall be available to ensure a unique version is applied.
The value 0 is used to indicate that no version information is available.
The components of this parameter are defined in Table 198.
|
Name |
Type |
Description |
|
ViewDescription |
structure |
Specifies a View. |
|
viewId |
NodeId |
NodeId of the View to Query. A null value indicates the entire AddressSpace. |
|
timestamp
|
UtcTime |
The time date desired. The corresponding version is the one with the closest previous creation timestamp. Either the Timestamp or the viewVersion parameter may be set by a Client, but not both. If ViewVersion is set this parameter shall be null. |
|
viewVersion |
UInt32 |
The version number for the View desired. When Nodes are added to or removed from a View, the value of a View’s ViewVersion Property is updated. Either the Timestamp or the viewVersion parameter may be set by a Client, but not both. The ViewVersion Property is defined in OPC 10000-3. If timestamp is set this parameter shall be 0. The current view is used if timestamp is null and viewVersion is 0. |