It also contain an identif ier whic in icates what data it contain an how it is en oded.. If a given f ield is also a stru ture then the values of its field are writen seq ential y b for
Terms and definitions 1 1
For the purposes of this document the terms and definitions given in IEC TR 62541 -1 , IEC TR 62541 -2 and IEC 62541 -3 as well as the following apply
DataEncoding a way to serialize OPC UA Messages and data structures
Mapping specifies how to implement an OPC UA feature with a specific technology
Note 1 to entry: For example, the OPC UA Binary Encoding is a Mapping that specifies how to serialize OPC UA data structures as sequences of bytes
Security Protocol ensures the integrity and privacy of UA Messages that are exchanged between OPC UA applications
Stack Profile a combination of DataEncodings, SecurityProtocol and TransportProtocol Mappings
Note 1 to entry: OPC UA applications implement one or more StackProfiles and can only communicate with OPC
UA applications that support a StackProfile that they support
Transport Protocol a way to exchange serialized OPC UA Messages between OPC UA applications
Abbreviations and symbols 1 1
ASN.1 Abstract Syntax Notation #1 (used in X690)
BP WS-I Basic Profile Version
BSP WS-I Basic Security Profile
CSV Comma Separated Value (File Format)
HTTPS Secure Hypertext Transfer Protocol
OID Object Identifier (used with ASN.1 )
RSTR Request Security Token Response
SOAP Simple Object Access Protocol
SSL Secure Sockets Layer (Defined in SSL/TLS)
TLS Transport Layer Security (Defined in SSL/TLS)
UTF8 Unicode Transformation Format (8-bit) (Defined in UTF8)
UASC OPC UA Secure Conversation
WS-* XML Web Services Specifications
WS-SC WS Secure Conversation
The OPC UA standards are designed to be technology-agnostic, ensuring their relevance as technology advances However, this independence also means that the information provided in IEC TR 62541-1 to IEC 62541-5 is insufficient for constructing a complete OPC UA application, as it omits crucial implementation details.
This standard outlines the Mappings between abstract specifications and the technologies for their implementation, categorized into three groups: Data Encodings, Security Protocols, and Transport Protocols These Mappings are combined to form Stack Profiles, which all OPC UA Applications must implement Communication is only possible between OPC UA Applications that utilize the same Stack Profile.
This standard defines the DataEncodings in Clause 5, the SecurityProtocols in Clause 6 and the TransportProtocols in 6.7.6 The StackProfiles are defined in IEC 62541 -7
All communication between OPC UA applications relies on message exchange, with parameters defined in IEC 62541-4 The format of these messages is determined by DataEncoding and TransportProtocol Consequently, each message outlined in IEC 62541-4 must have a normative description detailing the exact content for transmission These normative descriptions are provided in the appendices.
A Stack consists of software libraries that implement various StackProfiles, with a non-normative API serving as the interface between an OPC UA Application and the Stack, concealing implementation details The API is tailored to a specific DevelopmentPlatform, and it's important to note that the data types available in the API may differ from those defined by the specification due to DevelopmentPlatform limitations For instance, since Java does not support unsigned integers, any Java API must convert unsigned integers to a signed integer type.
Figure 1 illustrates the relationships between the different concepts defined in this standard
Figure 1 – The OPC UA Stack Overview
The layers outlined in this specification do not align with the OSI 7 layer model Each OPC UA StackProfile functions as a standalone Layer 7 (Application) protocol, relying on existing Layer 5, 6, or 7 protocols like TCP/IP, TLS, or HTTP The SecureChannel layer is always present, even when the SecurityMode is set to None, indicating that no security is applied; however, the SecurityProtocol implementation must maintain a logical channel with a unique identifier It is crucial for users and administrators to recognize that a SecureChannel with SecurityMode set to None is not trustworthy unless the Application operates on a physically secure network or utilizes a low-level protocol such as IPSec.
General 1 3
This standard defines two data encodings: OPC UA Binary and OPC UA XML It describes how to construct Messages using each of these encodings
All OPC UA DataEncodings rely on established rules for a standard set of built-in types, which serve as the foundation for creating structures, arrays, and messages These built-in types are detailed in Table 1.
Table 1 – Built-in Data Types
1 Boolean A two-state logical value (true or false)
2 SByte An integer value between − 1 28 and 1 27
3 Byte An integer value between 0 and 256
4 Int1 6 An integer value between − 32 768 and 32 767
5 UInt1 6 An integer value between 0 and 65 535
6 Int32 An integer value between − 2 1 47 483 648 and 2 1 47 483 647
7 UInt32 An integer value between 0 and 429 4967 295
8 Int64 An integer value between − 9 223 372 036 854 775 808 and 9 223 372 036 854 775 807
9 UInt64 An integer value between 0 and 1 8 446 744 073 709 551 61 5
1 0 Float An IEEE single precision (32 bit) floating point value
1 1 Double An IEEE double precision (64 bit) floating point value
1 2 String A sequence of Unicode characters
1 3 DateTime An instance in time
1 4 Guid A 1 6 byte value that can be used as a globally unique identifier
1 7 NodeId An identifier for a node in the address space of an OPC UA Server
1 8 ExpandedNodeId A NodeId that allows the namespace URI to be specified instead of an index
1 9 StatusCode A numeric identifier for a error or condition that is associated with a value or an operation
20 QualifiedName A name qualified by a namespace
21 LocalizedText Human readable text with an optional locale identifier
22 ExtensionObject A structure that contains an application specific data type that may not be recognized by the receiver
23 DataValue A data value with an associated status code and timestamps
24 Variant A union of all of the types specified above
25 DiagnosticInfo A structure that contains detailed error and diagnostic information associated with a StatusCode
The data types outlined in this standard closely align with the abstract types specified in IEC 62541-3 and IEC 62541-4 Notably, it introduces the ExtensionObject and Variant types, along with a representation for the Guid type as defined in IEC 62541-3.
A Guid is a 1 6-byte globally unique identifier with the layout shown in Table 2
Guid values may be represented as a string in this form:
----
Where Data1 is 8 characters wide, Data2 and Data3 are 4 characters wide and each Byte in Data4 is 2 characters wide Each value is formatted as a hexadecimal number padded zeros
A typical Guid value would look like this when formatted as a string:
A ByteString is essentially a one-dimensional array of bytes, but it is recognized as a unique built-in data type This distinction enables encoders to enhance the efficiency of value transmission However, certain development platforms may not maintain the difference between a ByteString and a standard one-dimensional byte array.
If a decoder for DevelopmentPlatform cannot preserve the distinction it shall convert all one dimensional arrays of Byte to ByteStrings
In a one-dimensional array of ByteString, each element can vary in length, making it structurally distinct from a two-dimensional array of Byte, where each dimension maintains a consistent length Consequently, decoders must ensure that they differentiate between multi-dimensional arrays of Byte and one-dimensional or multi-dimensional arrays of ByteString.
If a Development Platform lacks support for unsigned integers, it must represent ByteStrings as arrays of SByte, thereby applying the requirements for Byte to SByte.
An ExtensionObject serves as a versatile container for complex data types that cannot be represented by standard built-in data types It encapsulates a complex value, which is serialized either as a sequence of bytes or as an XML element Additionally, the ExtensionObject includes an identifier that specifies the type of data it holds and the method of its encoding.
Complex Data types in a Server address space are sub-types of the Structure DataType, with their DataEncodings represented as DataTypeEncoding Objects The NodeId for these DataTypeEncoding Objects is stored in the ExtensionObject According to IEC 62541-3, the relationship between DataTypeEncoding Nodes and other Nodes in the AddressSpace is defined.
Server implementers should use namespace qualified numeric NodeIds for any DataTypeEncoding Objects they define This will minimize the overhead introduced by packing Complex Data values into ExtensionObjects
A Variant is a comprehensive union of all built-in data types, including ExtensionObjects, and can also hold arrays of these types They are utilized to store any value or parameter that has a data type of BaseDataType or its subtypes.
Variants can be empty, represented by a null value, similar to a null column in a SQL database It's important to note that a null value in a Variant may differ from a null value in data types that support nulls, like Strings Additionally, some Development Platforms might not maintain the distinction between a null for a DataType and a null for a Variant, so applications should not depend on this distinction.
Variants can contain arrays of Variants but they cannot directly contain another Variant
DataValue and DiagnosticInfo types only have meaning when returned in a response message with an associated StatusCode As a result, Variants cannot contain instances of DataValue or DiagnosticInfo.
Variables of BaseDataType are associated with a Variant, but the ValueRank and ArrayDimensions Attributes impose limitations on the contents of the Variant For instance, if the ValueRank is set to Scalar, the Variant is restricted to holding only scalar values.
OPC UA Binary 1 6
General 1 6
The OPC UA BinaryDataEncoding is a specialized data format created to enhance the performance of OPC UA applications It focuses on rapid encoding and decoding while also considering the size of the encoded data transmitted over the network.
The OPC UA Binary DataEncoding utilizes various primitive data types with specific encoding rules for sequential reading and writing to a binary stream Structures are encoded by writing the encoded form of each field in order, and if a field is a structure itself, its fields are written sequentially before proceeding to the next field in the parent structure Importantly, all fields must be written to the stream, including those with null values, as the encodings for each primitive type define how to represent both null and default values.
The OPC UA Binary DataEncoding omits type and field name information, as all OPC UA applications are designed to have prior knowledge of the supported services and structures However, an exception exists for the ExtensionObject, which includes an identifier and size for the Complex Data structure it represents, enabling decoders to bypass unrecognized types.
Built-in Types 1 6
A Boolean value shall be encoded as a single byte where a value of 0 (zero) is false and any non-zero value is true
Encoders shall use the value of 1 to indicate a true value; however, decoders shall treat any non-zero value as true
All integer types shall be encoded as little endian values where the least significant byte appears first in the stream
Figure 2 illustrates how value 1 000 000 000 (Hex: 3B9ACA00) should be encoded as a 32 bit integer in the stream
Figure 2 – Encoding Integers in a binary stream
All floating point values must be encoded using the IEEE-754 binary representation, which consists of three key components: the sign, the exponent, and the fraction The bit allocation for each component varies based on the type's width, as detailed in Table 3, which outlines the bit ranges for the supported floating point types.
Table 3 – Supported Floating Point Types
Name Width (bits) Fraction Exponent Sign
In addition, the order of bytes in the stream is significant All floating point values shall be encoded with the least significant byte appearing first (i.e little endian)
Figure 3 illustrates how the value −6,5 (Hex: C0D00000) should be encoded as a Float
The floating point type accommodates both positive and negative infinity, as well as not-a-number (NaN) values While the IEEE specification recognizes various NaN variants, encoders and decoders may not maintain this distinction Consequently, encoders are required to represent a NaN value as an IEEE quiet-NAN (000000000000F8FF) or (0000C0FF) Additionally, unsupported types, including denormalized numbers, must also be encoded as an IEEE quiet-NAN.
Figure 3 – Encoding Floating Points in a binary stream
All String values are encoded as a sequence of UTF8 characters without a null terminator and preceded by the length in bytes
The length in bytes is encoded as Int32 A value of −1 is used to indicate a ‘null’ string
Figure 4 illustrates how the multilingual string “水Boy” should be encoded in a byte stream
Figure 4 – Encoding Strings in a binary stream
A DateTime value shall be encoded as a 64-bit signed integer (see Clause 5.2.2.2) which represents the number of 1 00 nanosecond intervals since January 1 , 1 601 (UTC)
Not all Development Platforms can fully represent the range of dates and times allowed by this Data Encoding For instance, the UNIX time_t structure has a resolution of only 1 second and cannot represent dates before 1970 Therefore, specific rules must be followed when handling date/time values that exceed a Development Platform's dynamic range One such rule states that a date/time value is encoded as 0 if certain conditions are met.
1 ) The value is equal to or earlier than 1 601 -01 -01 1 2:00AM
2) The value is the earliest date that can be represented with the DevelopmentPlatform’s encoding
0 1 2 3 4 b) A date/time is encoded as the maximum value for an Int64 if either
1 ) The value is equal to or greater than 9999-01 -01 1 1 :59:59PM,
2) The value is the latest date that can be represented with the DevelopmentPlatform’s encoding c) A date/time is decoded as the earliest time that can be represented on the platform if either
2) The encoded value represents a time earlier than the earliest time that can be represented with the DevelopmentPlatform’s encoding d) A date/time is decoded as the latest time that can be represented on the platform if either
1 ) The encoded value is the maximum value for an Int64,
2) The encoded value represents a time later than the latest time that can be represented with the DevelopmentPlatform’s encoding
These rules imply that the earliest and latest times that can be represented on a given platform are invalid date/time values and should be treated that way by Applications
A decoder shall truncate the value if a decoder encounters a DateTime value with a resolution that is greater than the resolution supported on the DevelopmentPlatform
A Guid is encoded in a structure as shown in Table 2 Fields are encoded sequentially according to the data type for field
Figure 5 illustrates how the Guid “72962B91 -FA75-4ae6-8D28-B404DC7DAF63” should be encoded in a byte stream
Figure 5 – Encoding Guids in a binary stream
A ByteString is encoded as sequence of bytes preceded by its length in bytes The length is encoded as a 32-bit signed integer as described above
If the length of the byte string is −1 then the byte string is ‘null’
An XmlElement is an XML fragment serialized as UTF8 string and then encoded as ByteString
Figure 6 illustrates how the XmlElement “Hot 水 ” should be encoded in a byte stream
Figure 6 – Encoding XmlElements in a binary stream
The components of a NodeId are described the Table 4
Namespace UInt1 6 The index for a namespace URI
An index of 0 is used for OPC UA defined NodeIds
IdentifierType Enum The format and data type of the identifier
The value may be one of the following:
NUMERIC - the value is an UInteger;
STRING - the value is String;
GUID - the value is a Guid;
OPAQUE - the value is a ByteString;
Value * The identifier for a node in the address space of an OPC UA Server
The DataEncoding of a NodeId is determined by the instance's contents, with the first byte of the encoded form indicating the format of the remaining data Table 5 outlines the various DataEncoding formats, while subsequent tables detail the structure of each format, excluding the format-indicating byte.
Two Byte 0x00 A numeric value that fits into the two byte representation
Four Byte 0x01 A numeric value that fits into the four byte representation
Numeric 0x02 A numeric value that does not fit into the two or four byte representations
ByteString 0x05 An opaque (ByteString) value
NamespaceUri Flag 0x80 See discussion of ExpandedNodeId in 5.2.2.1 0
ServerIndex Flag 0x40 See discussion of ExpandedNodeId in 5.2.2.1 0
The standard NodeId DataEncoding has the structure shown in Table 6 The standard DataEncoding is used for all formats that do not have an explicit format defined
Table 6 – Standard NodeId Binary DataEncoding
Identifier * The identifier which is encoded according to the following rules:
An example of a String NodeId with Namespace = 1 and Identifier = “Hot水” is shown in Figure 7
Figure 7 – A String NodeId The Two Byte NodeIdDataEncoding has the structure shown in Table 7
Table 7 – Two Byte NodeId Binary DataEncoding
Identifier Byte The Namespace is the default OPC UA namespace (i.e 0)
The Identifier Type is ‘Numeric’
The Identifier shall be in the range 0 to 255
An example of a Two Byte NodeId with Identifier = 72 is shown in Figure 8
Figure 8 – A Two Byte NodeId The Four Byte NodeIdDataEncoding has the structure shown in Table 8
Table 8 – Four Byte NodeId Binary DataEncoding
Namespace Byte The Namespace shall be in the range 0 to 255
Identifier UInt1 6 The Identifier Type is ‘Numeric’
The Identifier shall be an integer in the range 0 to 65 535
An example of a Four Byte NodeId with Namespace = 5 and Identifier = 1 025 is shown in Figure 9
An ExpandedNodeId enhances the NodeId structure by enabling the explicit specification of the NamespaceUri, rather than relying on the NamespaceIndex The NamespaceUri is optional; when provided, the NamespaceIndex within the NodeId is disregarded.
The ExpandedNodeId is encoded by first encoding a NodeId as described in 5.2.2.9 and then encoding NamespaceUri as a String
An ExpandedNodeId can utilize the NamespaceIndex without including the NamespaceUri in the stream When the NamespaceUri is absent, its presence is signaled by activating the NamespaceUri flag in the encoding format byte for the NodeId.
When the NamespaceUri is available, the encoder must set the NamespaceIndex to 0 during the encoding of the NodeId The inclusion of the unused NamespaceIndex in the stream ensures consistency.
An ExpandedNodeId can include a ServerIndex, represented as a UInt32 following the NamespaceUri The presence of the ServerIndex in the NodeId encoding is indicated by a specific flag, and it is excluded from the stream if its value is zero.
The ExpandedNodeId encoding has the structure shown in Table 9
NodeId NodeId The NamespaceUri and ServerIndex flags in the NodeId encoding indicate whether those fields are present in the stream
NamespaceUri String Not present if null or Empty
ServerIndex UInt32 Not present if 0
A StatusCode is encoded as a UInt32
The DiagnosticInfo structure, as outlined in IEC 62541 -4, includes several fields that may be absent To address this, the encoding employs a bit mask to signify which fields are included in the encoded representation.
According to IEC 62541-4, the fields SymbolicId, NamespaceUri, LocalizedText, and Locale serve as indexes in a string table included in the response header, with only the index of the corresponding string being encoded An index of -1 signifies the absence of a value for the string.
Encoding Mask Byte A bit mask that indicates which fields are present in the stream
The mask has the following bits:
0x04 LocalizedText 0x08 Locale 0x1 0 Additional Info 0x20 InnerStatusCode 0x40 InnerDiagnosticInfo SymbolicId Int32 A symbolic name for the status code
NamespaceUri Int32 A namespace that qualifies the symbolic id
LocalizedText Int32 A human readable summary of the status code
Locale Int32 The locale used for the localized text
Additional Info String Detailed application specific diagnostic information
Inner StatusCode StatusCode A status code provided by an underlying system
Inner DiagnosticInfo DiagnosticInfo Diagnostic info associated with the inner status code
A QualifiedName structure is encoded as shown in Table 1 1
The abstract QualifiedName structure is defined in IEC 62541 -3
NamespaceIndex UInt1 6 The namespace index
The LocalizedText structure, as defined in IEC 62541 -3, includes two fields that may be absent To address this, a bit mask is utilized in the encoding process to signify which fields are present in the encoded format.
EncodingMask Byte A bit mask that indicates which fields are present in the stream
The mask has the following bits:
Omitted is null or empty
Text String The text in the specified locale
Omitted is null or empty
An ExtensionObject is encoded as sequence of bytes prefixed by the NodeId of its DataTypeEncoding and the number of bytes encoded
An ExtensionObject can be encoded by the Application as either a ByteString or an XmlElement, allowing the encoder to determine the byte count before encoding Alternatively, if the ExtensionObject is capable of self-encoding, the encoder must either calculate the byte count beforehand or seek backwards in the stream to update the length after encoding the body.
When a decoder encounters an ExtensionObject, it checks for a recognized DataTypeEncoding identifier to decode the object body If the type is unrecognized, the decoder uses the EncodingMask to identify whether the body is a ByteString or an XmlElement, allowing it to decode the object body or treat it as opaque data and skip it.
The serialized form of an ExtensionObject is shown in Table 1 3
Table 1 3 – Extension Object Binary DataEncoding
TypeId NodeId The identifier for the DataTypeEncoding node in the Server's AddressSpace
ExtensionObjects defined by the OPC UA specification have a numeric node identifier assigned to them with a NamespaceIndex of 0 The numeric identifiers are defined in A.1
Encoding Byte An enumeration that indicates how the body is encoded
The parameter may have the following values:
0x01 The body is encoded as a ByteString
0x02 The body is encoded as a XmlElement
Length Int32 The length of the object body
The length shall be specified if the body is encoded
Body Byte[*] The object body
This field contains the raw bytes for ByteString bodies
For XmlElement bodies this field contains the XML encoded as a UTF-8 string without any null terminator
ExtensionObjects are used in two contexts: as values contained in Variant structures or as parameters in OPC UA Messages
A Variant is a union of the built-in types
The structure of a Variant is shown in Table 1 4
EncodingMask Byte The type of data encoded in the stream
The mask has the following bits assigned:
0:5 Built-in Type Id (see Table 1 )
6 True if the Array Dimensions field is encoded
7 True if an array of values is encoded
ArrayLength Int32 The number of elements in the array
This field is only present if the array bit is set in the encoding mask
Enumerations
Enumerations are encoded as Int32 values.
Arrays
Arrays outside of a Variant are represented as a sequence of elements, starting with an Int32 value indicating the number of elements A null Array is encoded with a length of -1, while an Array with zero length is distinct from a null Array, requiring encoders and decoders to maintain this difference.
Multi-dimensional arrays can only be encoded within a Variant.
Structures
Structures are represented as a sequence of fields in the order of their definition, with the encoding of each field dictated by its built-in type.
All fields specified in the complex type shall be encoded
Structures cannot have a null value If a programming language permits structures to be null, the encoder must create a new instance with default values for all fields and serialize it accordingly In such cases, encoders should avoid generating encoding errors.
The following is an example of a structure using C++ syntax: class Type2
The Y field is a pointer to an array with a length stored in NoOfY
An instance of Type1 which contains an array of two Type2 instances would be encoded as
The 37-byte sequence represents an instance of Type1 encoded in an ExtensionObject, as detailed in Table 1 The fields defined by the ExtensionObject include the TypeId, Encoding, and length Notably, Type2 instances do not require a type identifier, as it is explicitly defined within Type1.
Table 1 6 – Sample OPC UA Binary Encoded structure
Type Id 4 The identifier for Type1 Encoding 1 0x1 for ByteString
Messages
Messages are represented as ExtensionObjects, with parameters serialized similarly to Structure fields Each Message includes a TypeId field that identifies its DataTypeEncoding, while the Length field is excluded, as Messages adhere to the OPC UA standards.
Each OPC UA Service described in IEC 62541 -4 has a request and response Message The DataTypeEncoding IDs assigned to each Service are given in A.3.
XML
Built-in Types
Most built-in types are represented in XML according to the formats specified in XML Schema Part 2 Any specific restrictions or applications are detailed below, while some built-in types also have an XML Schema defined using the syntax outlined in XML Schema Part 1.
The prefix xs: is used to denote a symbol defined by the XML Schema specification
A Boolean value is encoded as an xs:boolean value
Integer values are represented using a subtype of the xs:decimal type, with the relationships between OPC UA integer types and XML schema data types detailed in Table 1.
Table 1 7 – XML Data Type Mappings for Integers
Floating point values are represented using specific XML floating point types, with the relationships between OPC UA floating point types and XML schema data types detailed in Table 1.
Table 1 8 – XML Data Type Mappings for Floating Points
The XML floating point type supports positive infinity (INF), negative infinity (-INF) and not-a- number (NaN)
A String value is encoded as an xs:string value
A DateTime value is encoded as an xs:dateTime value
All DateTime values shall be encoded as UTC times or with the time zone explicitly specified Correct:
It is recommended that all xs:dateTime values be represented in UTC format
The earliest and latest date/time values that can be represented on a DevelopmentPlatform have special meaning and shall not be literally encoded in XML
The earliest date/time value on a DevelopmentPlatform shall be encoded in XML as '0001 -01 -
The latest date/time value on a DevelopmentPlatform shall be encoded in XML as '9999-1 2-
When a decoder processes an xs:dateTime value that is incompatible with the DevelopmentPlatform, it should adjust the value to the nearest representable date/time, either the earliest or latest available Importantly, the XML decoder must not produce an error for out-of-range date values.
The earliest date/time value on a DevelopmentPlatform is equivalent to a null date/time value
A Guid is encoded using the string representation defined in 5.1 3
The XML schema for a Guid is:
A ByteString value is encoded as an xs:base64Binary value (see Base64)
The XML schema for a ByteString is:
An XmlElement value is encoded as an xs:complexType with the following XML schema:
XmlElements may only be used inside Variant or ExtensionObject values
A NodeId value is encoded as an xs:string with the syntax: ns=; =
The elements of the syntax are described in Table 1 9
UInt1 6 The NamespaceIndex formatted as a base 1 0 number
If the index is 0 then the entire 'ns=0;' clause shall be omitted
Enum A flag that specifies the IdentifierType
The flag has the following values: i NUMERIC (UInteger) s STRING (String) g GUID (Guid) b OPAQUE (ByteString)
* The Identifier encoded as string
The Identifier is formatted using the XML data type mapping for the IdentifierType Note that the Identifier may contain any non-null UTF8 character including whitespace
Examples of NodeIds: i =1 3 ns =1 0 ; i =- 1 ns =1 0 ; s =He l l o: Worl d g=0 9 0 8 7 e7 5 - 8 e 5 e - 4 9 9 b- 9 5 4 f- f2 a9 6 0 3 db2 8 a ns =1 ; b=M/ RbKBs RVke PCePcx2 4 oRA==
The XML schema for a NodeId is:
An ExpandedNodeId value is encoded as an xs:string with the syntax: svr=; ns=; = or svr=; nsu=; =
The possible fields are shown in Table 20
UInt32 The ServerIndex formatted as a base 1 0 number
If the ServerIndex is 0 then the entire 'svr=0;' clause shall be omitted
UInt1 6 The NamespaceIndex formatted as a base 1 0 number
If the NamespaceIndex is 0 then the entire 'ns=0;' clause shall be omitted
The NamespaceIndex shall not be present if the URI is present
String The NamespaceUri formatted as a string
Reserved characters in a URI must be encoded by replacing them with a '%' followed by their 8-bit ANSI value represented as two hexadecimal digits For instance, the character ';' is encoded as '%3B'.
The reserved characters are ‘;’ and ‘%’
If the NamespaceUri is null or empty then 'nsu=;' clause shall be omitted
Enum A flag that specifies the IdentifierType
This field is described in Table 1 9
* The Identifier encoded as string
This field is described in Table 1 9
The XML schema for an ExpandedNodeId is:
A StatusCode is encoded as an xs:unsignedInt with the following XML schema:
An DiagnosticInfo value is encoded as an xs:complexType with the following XML schema:
The XML schema defines an optional element named "Additional Info" of type string, which may occur zero or more times Additionally, it includes an optional element called "InnerStatusCode" of type StatusCode, also allowing for zero occurrences.
A QualifiedName value is encoded as an xs:complexType with the following XML schema:
A LocalizedText value is encoded as an xs:complexType with the following XML schema:
An ExtensionObject value is encoded as an xs:complexType with the following XML schema:
The ExtensionObject body consists of a single element, which can be either a ByteString or an XML encoded Structure A decoder can identify the type by examining the top-level element; if it is named tns:ByteString, it indicates an OPC UA Binary encoded body, while any other name signifies an OPC UA XML encoded body.
The TypeId is the NodeId for the DataTypeEncoding Object
A Variant value is encoded as an xs:complexType with the following XML schema:
If the Variant is a scalar value, it must include one child element named after the built-in type For instance, the single precision floating point value 3.1415 would be encoded as:
If the Variant is a one-dimensional array, it must include a single child element prefixed with 'ListOf' and named after the built-in type For instance, an array of strings would be encoded accordingly.
Hel l o
Worl d
If the Variant represents a multidimensional Array then it shall contain a child element with the name ‘Matrix’ with the two sub-elements shown in this example:
A
B
C
D
In this example, the array has the following elements:
A multi-dimensional array's elements are flattened into a single-dimensional array, with higher rank dimensions serialized first This single-dimensional array is encoded as a child of the 'Elements' element The 'Dimensions' element contains an array of Int32 values that define the array's dimensions, beginning with the lowest rank dimension The original multi-dimensional array can be reconstructed using the encoded dimensions.
The complete set of built-in type names is found in Table 1
A DataValue value is encoded as a xs:complexType with the following XML schema:
Enumerations
Enumerations that are used as parameters in the Messages defined in IEC 62541 -4 are encoded as xs:string with the following syntax:
The elements of the syntax are described in Table 21
String The symbolic name for the enumerated value
UInt32 The numeric value associated with enumerated value
For example, the XML schema for the NodeClass enumeration is:
Enumerations that are stored in a Variant are encoded as an Int32 value
For example, any Variable could have a value with a DataType of NodeClass In this case the corresponding numeric value is placed in the Variant (e.g NodeClass::Object would be stored as a 1 ).
Arrays
Array parameters are encoded by enclosing their elements within a container element, which is then integrated into the structure The container element's name corresponds to the parameter name, while the names of the elements within the array reflect the type name.
For example, the Read service takes an array of ReadValueIds The XML schema would look like:
The nillable attribute shall be specified because XML encoders will drop elements in arrays if those elements are empty.
Structures
Structures are encoded as a xs:complexType with all of the fields appearing in a sequence All fields are encoded as an xs:element and have xs:maxOccurs set to 1
For example, the Read service has a ReadValueId structure in the request The XML schema would look like:
Messages
Messages are encoded as an xs:complexType The parameters in each Message are serialized in the same way the fields of a Structure are serialized
Security handshake
All Security Protocols must incorporate the OpenSecureChannel and CloseSecureChannel services as outlined in IEC 62541-4 These services detail the procedures for establishing a SecureChannel and applying security measures to the messages transmitted through it The exchanged messages and the corresponding security algorithms are illustrated in Figure 1.
SecurityProtocols offer three modes: None, Sign, and SignAndEncrypt When the SecurityMode is set to None, security measures are not applied, and the security handshake depicted in Figure 1 0 is unnecessary Nevertheless, the implementation of SecurityProtocol must still establish a logical channel and assign a unique identifier for the SecureChannel.
Signed with Client Private Key Encrypted with Server Public Key
Signed with Server Private Key Encrypted with Client Public Key
CreateSession Request Signed with Client Signing Key Encrypted with Server Encryption Key
CreateSession Response Signed with Server Signing Key Encrypted with Client Encryption Key
Each SecurityProtocol mapping outlines the application of security algorithms to messages A collection of these algorithms used in a security handshake is referred to as a SecurityPolicy According to IEC 62541-7, standard SecurityPolicies are integral to the standard Profiles that OPC UA applications should support, and it also specifies a URI for each standard SecurityPolicy.
A Stack is expected to have built in knowledge of the SecurityPolicies that it supports Applications specify the SecurityPolicy they wish to use by passing the URI to the Stack
Table 22 outlines the components of a SecurityPolicy, detailing how each parameter is utilized through specific SecurityProtocol mappings It is important to note that not all parameters are necessarily employed in every SecurityProtocol mapping.
PolicyUri The URI assigned to the SecurityPolicy
SymmetricSignatureAlgorithm The URI of the symmetric signature algorithm to use
SymmetricEncryptionAlgorithm The URI of the symmetric key encryption algorithm to use
AsymmetricSignatureAlgorithm The URI of the asymmetric signature algorithm to use
AsymmetricKeyWrapAlgorithm The URI of the asymmetric key wrap algorithm to use
AsymmetricEncryptionAlgorithm The URI of the asymmetric key encryption algorithm to use
MinAsymmetricKeyLength The minimum length for an asymmetric key
MaxAsymmetricKeyLength The maximum length for an asymmetric key
KeyDerivationAlgorithm The key derivation algorithm to use
DerivedSignatureKeyLength The length in bits of the derived key used for Message authentication
The Asymmetric Encryption Algorithm is utilized for encrypting entire messages with an asymmetric key However, certain security protocols opt not to encrypt the full message using this method Instead, they employ the Asymmetric Key Wrap Algorithm to secure a symmetric key, which is then used in conjunction with the Symmetric Encryption Algorithm to encrypt the message.
The AsymmetricSignatureAlgorithm is used to sign a Message with an asymmetric key
The Key Derivation Algorithm generates keys for securing messages transmitted via the Secure Channel The encryption key length is determined by the Symmetric Encryption Algorithm, while the key length for Symmetric Signatures varies based on the Symmetric Signature Algorithm and may differ from the encryption key length.
Certificates
General
OPC UA Applications utilize Certificates to securely store Public Keys essential for Asymmetric Cryptography operations These applications employ X509 Version 3 Certificates, encoded in DER format, as specified in X690 Additionally, the Certificates must adhere to RFC 3280, which outlines the profile for X509 Certificates in the context of Internet-based Applications.
The ServerCertificate and ClientCertificate parameters in the OpenSecureChannel service are examples of the ApplicationInstance Certificate Data Type For guidance on creating an X509 Certificate suitable for use as an ApplicationInstance Certificate, refer to Subclause 6.2.2.
The ServerSoftwareCertificates and ClientSoftwareCertificates parameters in the CreateSession and ActivateSession Services are examples of the SignedSoftwareCertificate Data Type For details on creating an X509 Certificate suitable for use as a SignedSoftwareCertificate, refer to Subclause 6.2.3.
Application Instance Certificate
An ApplicationInstanceCertificate is a ByteString that holds the DER encoded version of an X509v3 Certificate, as specified in X690 This certificate, issued by a certifying authority, uniquely identifies an instance of an application operating on a specific host The X509v3 fields included in the ApplicationInstanceCertificate are detailed in Table 23 and are fully defined in RFC 3280.
Table 23 also provides a mapping from the RFC 3280 terms to the terms used in the abstract definition of an ApplicationInstanceCertificate defined in IEC 62541 -4
The ApplicationInstanceCertificate is an X509v3 Certificate characterized by its version, which is set to "V3." It includes a serial number assigned by the issuer, the signature algorithm utilized for signing the certificate, and the signature itself created by the issuer Additionally, the issuer's distinguished name is included, which is essential for validating the signature.
The issuer field is completely described in RFC 3280 validity validTo, validFrom When the Certificate becomes valid and when it expires subject subject The distinguished name of the Application Instance
The Common Name attribute must be defined as the productName or an appropriate equivalent, while the Organization Name attribute should reflect the name of the organization operating the application instance, which is typically not the application's vendor Additional attributes may also be included.
The subject field is completely described in RFC 3280 subjectAltName applicationUri, hostnames The alternate names for the Application Instance
Shall include a uniformResourceIdentifier which is equal to the applicationUri
Servers must define a dNSName or IPAddress to identify the machine hosting the Application Instance If the machine has multiple names, additional dNSNames can be included However, the IPAddress should not be provided if a dNSName is specified.
The subjectAltName field is completely described in RFC 3280 publicKey publicKey The public key associated with the Certificate keyUsage keyUsage Specifies how the Certificate key may be used
Shall include digitalSignature, nonRepudiation, keyEncipherment and dataEncipherment
Other key uses are allowed extendedKeyUsage keyUsage Specifies additional key uses for the Certificate
Shall specify 'serverAuth and/or clientAuth
The authorityKeyIdentifier offers additional details regarding the key utilized to sign the Certificate It is mandatory for Certificates signed by a Certificate Authority (CA) and is recommended for self-signed Certificates.
Signed Software Certificate
A SignedSoftwareCertificate is a ByteString that holds the DER encoded version of an X509v3 Certificate, issued by a certifying authority This certificate includes an X509v3 extension known as SoftwareCertificate, which outlines the claims verified by the certifying authority The specific fields within a SignedSoftwareCertificate are detailed in Table 24 and are fully defined in RFC 3280.
A Signed Software Certificate is an X509v3 Certificate that includes several key components: the version, which must be "V3"; the serial number assigned by the issuer; the signature algorithm used for signing the certificate; the signature itself created by the issuer; and the issuer's distinguished name, which is essential for validating the signature.
The issuer field is completely described in RFC 3280 validity validTo, validFrom When the Certificate becomes valid and when it expires subject subject The distinguished name of the product
The Common Name attribute shall be the same as the productName in the SoftwareCertificate and the Organization Name attribute shall be the vendorName in the SoftwareCertificate
Other attributes may be specified
The subject field is completely described in RFC 3280 subjectAltName productUri The alternate names for the product
It shall include a ‘uniformResourceIdentifier’ which is equal to the productUri specified in the SoftwareCertificate
The subjectAltName field is detailed in RFC 3280, while the publicKey refers to the key linked to the Certificate Additionally, the keyUsage indicates the permissible uses of the Certificate key, which must include 'digitalSignature' and 'nonRepudiation'.
Other key uses are not allowed extendedKeyUsage keyUsage Specifies additional key uses for the Certificate
Other key usages are not allowed softwareCertificate softwareCertificate The XML encoded form of the SoftwareCertificate stored as UTF8 text
Subclause 5.3.4 describes how to encode a SoftwareCertificate in XML The ASN.1 Object Identifier (OID) for this extension is:
Time synchronization
For effective security protocols, it is essential that the system clocks of communicating machines are synchronized to accurately verify the expiry times of Certificates or Messages The permissible clock skew varies based on the security requirements of the system, and applications should enable administrators to set the acceptable clock skew during time verification A recommended default value for this clock skew is 5 minutes.
The Network Time Protocol (NTP) is essential for synchronizing machine clocks with network time servers Most systems operating on full-featured operating systems, such as Windows and Linux, inherently support NTP or similar protocols Additionally, devices utilizing embedded operating systems are expected to have NTP support as well.
If a device's operating system cannot support NTP, an OPC UA Application can synchronize its clock using the Timestamps in the ResponseHeader as outlined in IEC 62541 -4 To do this, the application must know the URL of a Discovery Server on a machine with the correct time The application or a separate utility will invoke the FindServers Service and adjust its clock according to the time provided in the ResponseHeader This synchronization process should be repeated periodically to account for clock drift over time.
UTC and International Atomic Time (TAI)
All times in OPC UA are expressed in UTC, which may experience discontinuities from leap seconds or repeating seconds to accommodate variations in the Earth's orbit and rotation Servers with access to International Atomic Time (TAI) may opt to use it instead of UTC Nevertheless, clients must always be ready to handle potential discontinuities caused by UTC adjustments or changes to the server's system clock.
Issued User Identity Tokens – Kerberos
Kerberos UserIdentityTokens are transmitted to the Server through the IssuedIdentityToken, which includes an XML element containing the WS-Security token as outlined in the Kerberos Token Profile specification.
Servers utilizing Kerberos authentication must implement a UserTokenPolicy that defines the version of the Kerberos Token Profile in use, along with the Kerberos Realm and the Server's Kerberos Principal Name The Realm and Principal Name are formatted together using a straightforward syntax and included in the issuerEndpointUri, as illustrated in Table 25.
Name Decription tokenType ISSUEDTOKEN_3 issuedTypeType http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1 1 issuerEndpointUri A string with the form \\\ where
is the Kerberos realm name (e.g Windows Domain);
is the Kerberos principal name for the OPC UA Server
The interaction between Client and Server applications with the Kerberos Authentication Service is tailored to specific applications In this context, the realm corresponds to the DomainName when utilizing a Windows Domain controller as the Kerberos provider.
WS Secure Conversation
Overview
Messages transmitted through SOAP can be secured using the WS Secure Conversation protocol, which outlines a method for negotiating shared secrets via WS Trust These shared secrets are then utilized to secure messages exchanged through the mechanisms established in WS Security.
The mechanisms for actually signing XML elements are described in the XML Signature specification The mechanisms for encrypting XML elements are described in the XML Encryption specification
The WS Security Policy outlines standard algorithm suites for securing SOAP messages, directly aligning with the Security Policies specified in IEC 62541-7 Additionally, the WS-I Basic Security Profile 1.1 provides best practices for implementing WS-Security, promoting interoperability among systems Compliance with this specification is mandatory for all OPC UA implementations.
The Timestamp header defined by WS Security is used to prevent replay attacks and shall be present and signed in all Messages exchanged
Figure 1 illustrates the connections among various WS-* specifications utilized in this mapping, highlighting the most current versions available at the time of publication Additionally, IEC 62541-7 may outline Profiles that necessitate support for future iterations of these specifications.
Figure 1 1 – Relevant XML Web Services specifications Figure 1 2 illustrates how these WS-* specifications are used in the security handshake
Figure 1 2 – The WS Secure Conversation handshake
The WS Trust specification defines the RST (Request Security Token) and RSTR (Request Security Token Response) Messages, while WS Secure Conversation introduces actions for these messages to indicate the Client's intent to create a SCT (Security Context Token) The SCT is essential as it contains the shared keys used by Applications to secure Messages transmitted over the SecureChannel.
Individual Messages are encrypted using keys generated from the Security Context Token (SCT) as outlined in the WS Secure Conversation protocol The following subclauses detail the structure of these Messages and highlight the necessary features from the WS-* specifications to effectively execute the OPC UA security handshake.
BinarySecurityToken (contains Client Public Key) SecurityToken (encrypted with Server Private Key) DerivedKeyToken (signing)
Each DerivedKeyToken contains a Nonce that is used to derived the key from the shared secret
SecurityContextToken (identifier only) DerivedKeyToken (signing) DerivedKeyToken (encrypting)
SecurityContextToken (identifier only) DerivedKeyToken (signing) DerivedKeyToken (encrypting)
Contains a secret that is used to create the derived keys.
The SecurityContextToken contains a secret created from the entropy provided in the RST and RSTR.
SOAP 1 2 HTTP or HTTPS (SSL/TLS)
Notation
SOAP Messages use XML elements defined in a number of different specifications This document uses the prefixes in Table 26 to identify the specification that defines an XML element
Prefix Specification wsu WS-Security Utilities wsse WS-Security Extensions wst WS-Trust wsc WS-Secure Conversation wsa WS-Addressing xenc XML Encryption
Request Security Token (RST/SCT)
The Request Security Token Messages adhere to the abstract OpenSecureChannel request Message outlined in IEC 62541-4 Its syntax is governed by WS Trust, while the Message structure is thoroughly detailed in WS Secure Conversation.
The Message will include several key components: a wsse:BinarySecurityToken that contains the Client’s Public Key, which is provided in a DER encoded X509v3 Certificate; an encrypted wsse:SecurityToken that holds the ClientNonce for key derivation, encrypted with the AsymmetricKeyWrapAlgorithm using the Server’s Application Instance Certificate Public Key; a wsc:DerivedKeyToken for signing the message body, WS Addressing headers, and wsu:Timestamp header with the SymmetricSignatureAlgorithm, which is then signed with the Client’s Private Key using the AsymmetricSignatureAlgorithm and includes a Nonce; and another wsc:DerivedKeyToken for encrypting the Message body with the SymmetricEncryptionAlgorithm.
This Message shall have the wsa:Action, wsa:MessageId, wsa:ReplyTo and wsa:To headers defined by WS Addressing The Message shall also have a wsu:Timestamp header defined by
WS Security These headers shall also be signed with the derived key used to sign the Message body
The signature shall be calculated before applying encryption and the signature shall be encrypted
The mapping between the OpenSecureChannel request parameters and the elements of the RST/SCT Message are shown in Table 27
Table 27 – RST/SCT Mapping to an OpenSecureChannel Request
RST/SCT Element Description clientCertificate wsse:BinarySecurityToken Passed in the SOAP header requestType wst:RequestType Shall be “http://schemas.xmlsoap.org/ws/2005/02/trust/Issue” when creating a new SCT
The renewal of a Security Context Token (SCT) requires the use of the endpoint “http://schemas.xmlsoap.org/ws/2005/02/trust/Renew” The secureChannelId and wsse:SecurityTokenReference must be included in the SOAP header during this process Additionally, it is essential to specify the securityMode, securityPolicyUri, wst:SignatureAlgorithm, wst:EncryptionAlgorithm, and wst:KeySize to ensure compliance with security standards.
These elements describe the SecurityPolicy requested by the Client
These elements shall match the SecurityPolicy used by the Endpoint that the Client wishes to connect to
These elements are optional clientNonce wst:Entropy This contains the Nonce specified by the Client
The Nonce is specified with the wst:BinarySecret element requestedLifetime wst:Lifetime The requested lifetime for the SCT
Request Security Token Response (RSTR/SCT)
The Request Security Token Response Message adheres to the abstract OpenSecureChannel response Message as outlined in IEC 62541-4, with its syntax governed by WS Trust Detailed descriptions of the Message's usage are provided in the relevant documentation.
WS Secure Conversation indicates that the message is neither signed nor encrypted using the asymmetric algorithms outlined in IEC 62541-4 Instead, it utilizes symmetric algorithms along with a key provided in the request message for security.
The Message will include two wsc:DerivedKeyTokens: the first is utilized to sign the body, WS Addressing headers, and the wsu:Timestamp header with the SymmetricSignatureAlgorithm, derived from the encrypted SecurityToken in the RST/SCT Message, and includes a Nonce The second wsc:DerivedKeyToken is employed to encrypt the Message body using the SymmetricEncryptionAlgorithm, also derived from the encrypted SecurityToken in the RST/SCT Message, and specifies a Nonce as well.
This Message shall have the wsa:Action and wsa:RelatesTo headers defined by
WS Addressing The Message shall also have a wsu:Timestamp header defined by
WS Security These headers shall also be signed with the derived key used to sign the Message body
The signature shall be calculated before applying encryption and the signature shall be encrypted
The mapping between the OpenSecureChannel response parameters and the elements of the RSTR/SCT Message are shown Table 28
Table 28 – RSTR/SCT Mapping to an OpenSecureChannel Response
- wst:RequestedProofToken This contains a wst:ComputedKey element which specifies the algorithm used to compute the shared secret key from the Nonces provided by the Client and the Server
The wst:TokenType defines the type of SecurityToken that is issued, while the wst:RequestedSecurityToken indicates the new or renewed Security Context Token (SCT) Additionally, the channelId wsc:Identifier serves as an absolute URI that uniquely identifies the SCT, and the tokenId wsc:Instance acts as an identifier for a specific set of keys issued for a given context.
The article discusses key elements of the wsc:SecurityContextToken, highlighting that the createdAt timestamp is optional It also mentions the revisedLifetime for the SCT and the serverNonce, which contains the Nonce specified by the server.
The Nonce is specified with the wst:BinarySecret element
The xenc:EncryptedData element is not used in OPC UA because the Message body shall be encrypted
The lifetime indicates the UTC expiration time for the security context token (SCT) The client must renew the SCT before this expiration by resending the RST/SCT message Detailed behavior is outlined in IEC 62541-4.
Using the SCT
Once the Client receives the RSTR/SCT Message it can use the SCT to secure all other Messages
An identifier for the SCT used shall be passed as an wsc:SecurityContextToken in each request Message The response Message shall reference the SecurityContextToken used in the request
If encryption is used it shall be applied before the signature is calculated
Messages secured with the SecurityContextToken must include additional tokens: a wsc:DerivedKeyToken for signing the message body, WS Addressing headers, and the wsu:Timestamp header using the SymmetricSignatureAlgorithm, with the key derived from the SecurityContextToken and accompanied by a Nonce Additionally, another wsc:DerivedKeyToken is required to encrypt the message body using the SymmetricEncryptionAlgorithm, also derived from the SecurityContextToken and specifying a Nonce.
This Message shall have the wsa:Action and wsa:RelatesTo headers defined by
WS Addressing The Message shall also have a wsu:Timestamp header defined by
Cancelling Security contexts
The Cancel Message defined by WS Trust implements the abstract CloseSecureChannel request Message defined in IEC 62541 -4
This Message shall be secured with the SCT.