The UADP NetworkMessage header and other parts of the NetworkMessage are shown in Figure 29.
When using security, the payload and the Padding field are encrypted and after that, the whole NetworkMessage is signed if signing and encryption is active. The NetworkMessage shall be signed without being encrypted if only the signing is active.
The UADP NetworkMessage does not provide the total message size. It is expected that the message size is known from the transport protocol mapping. If the transport protocol mapping does not provide the size of the payload, an additional size information must be added in front of the UADP NetworkMessage for that transport protocol.
Figure 29 – UADP NetworkMessage
The encoding of the UADP NetworkMessage is specified in Table 137.
The NetworkMessageContentMask setting of the Publisher controls the flags in the fields UADPFlags and ExtendedFlags1. The SecurityMode setting of the Publisher controls the security enabled flag of the ExtendedFlags1. The setting of the flags shall not change until the configuration of the Publisher is changed.
Table 137 – UADP NetworkMessage
|
Name |
Type |
Description |
|
UADPVersion |
Bit[0-3] |
Bit range 0-3: Version of the UADP NetworkMessage. The UADPVersion for this specification version is 1. |
|
UADPFlags |
Bit[4-7] |
Bit 4: PublisherId enabled If the PublisherId is enabled, the type of PublisherId is indicated in the ExtendedFlags1 field.If the PublisherId is enabled is false, the ExtendedFlags1 PublisherId Type flags shall be false. Bit 5: GroupHeader enabled Bit 6: PayloadHeader enabled Bit 7: ExtendedFlags1 enabledThe bit shall be false, if ExtendedFlags1 is 0. |
|
ExtendedFlags1 |
Byte |
The ExtendedFlags1 shall be omitted if bit 7 of the UADPFlags is false. If the field is omitted, the Subscriber shall handle the related bits as false. Bit range 0-2: PublisherId Type 000 The PublisherId is of DataType Byte This is the default value if ExtendedFlags1 is omitted 001 The PublisherId is of DataType UInt16 010 The PublisherId is of DataType UInt32 011 The PublisherId is of DataType UInt64 100 The PublisherId is of DataType String 101 Reserved 11x ReservedReserved values shall not be used by the sender and the receiver shall skip messages when reserved values are received. The PublisherId Type shall be ignored if bit 4 of the UADPFlags is false. Bit 3: DataSetClassId enabled Bit 4: SecurityHeader enabled If this flag is enabled, the NetworkMessage header includes the SecurityHeader, otherwise the SecurityHeader is omitted. If the SecurityMode in the configuration is SIGN or SIGNANDENCRYPT, this flag shall be set. Bit 5: Timestamp enabled Bit 6: PicoSeconds enabled This bit shall be false if the Timestamp bit is false. Bit 7: ExtendedFlags2 enabled The bit shall be false, if ExtendedFlags2 is 0. |
|
ExtendedFlags2 |
Byte |
The ExtendedFlags2 shall be omitted if bit 7 of the ExtendedFlags1 is false. If the field is omitted, the Subscriber shall handle the related bits as false. Bit 0: Chunk message defined in in 7.2.4.4.4. Bit 1: PromotedFields enabled If Promoted fields are enabled, the number of DataSetMessages in the Network Message shall be one. Bit range 2-4: UADP NetworkMessage type 000 NetworkMessage with DataSetMessage payload defined in 7.2.4.4.4. If the ExtendedFlags2 field is not provided, this is the default NetworkMessage type. 001 NetworkMessage with discovery probe defined in 7.2.4.5.4. 010 NetworkMessage with discovery announcement payload defined in 7.2.4.6.. 011 Reserved 1xxReserved Reserved values shall not be used by the sender and the receiver shall skip messages when reserved values are received. Bit 5: Reserved Bit 6: Reserved Bit 7: Reserved for further extended flag fields Reserved bits shall be set to false by the sender and the receiver shall skip messages where the reserved bits are not false. |
|
PublisherId |
Byte[*] |
The PublisherId shall be omitted if bit 4 of the UADPFlags is false. The Id of the Publisher that sent the data. Valid DataTypes are UInteger and String. The DataType is indicated by bits 0-2 of the ExtendedFlags1. A Subscriber can skip NetworkMessages from Publishers it does not expect NetworkMessages from. PublisherIds are only equal if they have the same DataTypes and equal values. |
|
DataSetClassId |
Guid |
The DataSetClassId associated with the DataSets in the NetworkMessage. All DataSetMessages in the NetworkMessage shall have the same DataSetClassId. The DataSetClassId shall be omitted if bit 3 of the ExtendedFlags1 is false. |
|
GroupHeader |
|
The group header shall be omitted if bit 5 of the UADPFlags is false. |
|
GroupFlags |
Byte |
Bit 0: WriterGroupId enabled Bit 1: GroupVersion enabled Bit 2: NetworkMessageNumber enabled Bit 3: SequenceNumber enabled Bits 4-6: Reserved Bit 7: Reserved for further extended flag fields Reserved bits shall be set to false by the sender and the receiver shall skip messages where the reserved bits are not false. |
|
WriterGroupId |
UInt16 |
Unique id for the WriterGroup in the Publisher. A Subscriber can skip NetworkMessages from WriterGroups it does not expect NetworkMessages from. This field shall be omitted if bit 0 of the GroupFlags is false. |
|
GroupVersion |
VersionTime |
Version of the header and payload layout configuration of the NetworkMessages sent for the group. This field shall be omitted if bit 1 of the GroupFlags is false. |
|
NetworkMessage Number |
UInt16 |
Unique number of a NetworkMessage across the combination of PublisherId and WriterGroupId within one PublishingInterval. The number is needed if the DataSetMessages for one group are split into more than one NetworkMessage in a PublishingInterval. The value 0 is invalid. This field shall be omitted if bit 2 of the GroupFlags is false. |
|
SequenceNumber |
UInt16 |
Sequence number for each new NetworkMessage as defined in 7.2.3. This field shall be omitted if bit 3 of the GroupFlags is false. |
|
PayloadHeader |
Byte [*] |
The payload header depends on the UADP NetworkMessage type flags defined in the ExtendedFlags2 bit range 2-4. The default is DataSetMessage if the ExtendedFlags2 field is not enabled. The PayloadHeader shall be omitted if bit 6 of the UADPFlags is false. The PayloadHeader is not contained in the payload but it is contained in the unencrypted NetworkMessage header since it contains information necessary to filter DataSetMessages on the Subscriber side. If the payload header is not present for DataSetMessages, the Subscriber must know the number and size of DataSetMessages from the DataSetReader configuration. The group header is the default option to provide a reference to this information in the NetworkMessage. In this case the number and size of the DataSetMessages is known from the DataSetReader configuration for the combination of WriterGroupId and NetworkMessageNumber. |
|
Timestamp |
DateTime |
The time the NetworkMessage was created. The Timestamp shall be omitted if bit 5 of ExtendedFlags1 is false. The PublishingInterval, the SamplingOffset the PublishingOffset and the Timestamp and PicoSeconds in the NetworkMessage header shall use the same time base. |
|
PicoSeconds |
UInt16 |
Specifies the number of 10 picosecond (1,0 e-11 seconds) intervals which shall be added to the Timestamp. The PicoSeconds field stores the difference between a high-resolution timestamp with a resolution of 10 picoseconds and the Timestamp field value which only has a 100 ns resolution. The PicoSeconds field shall contain values less than 10 000. The decoder shall treat values greater than or equal to 10 000 as the value ‘9999’. The PicoSeconds shall be omitted if bit 6 of ExtendedFlags1 is false. |
|
PromotedFields |
|
The PromotedFields shall be omitted if bit 1 of the ExtendedFlags2 is false. If the PromotedFields are provided, the number of DataSetMessages in the Network Message shall be one. |
|
Size |
UInt16 |
Total size in Bytes of the Fields contained in the PromotedFields. |
|
Fields |
BaseDataType[ ] |
Array of promoted fields. The size, order and DataTypes of the fields depend on the settings in the FieldMetaData of the DataSetMetaData associated with the DataSetMessage contained in the NetworkMessage. |
|
SecurityHeader |
|
The security header shall be omitted if bit 4 of the ExtendedFlags1 is false. |
|
SecurityFlags |
Byte |
Bit 0: NetworkMessage Signed Bit 1: NetworkMessage EncryptedThe configuration options for MessageSecurityMode are NONE, SIGN and SIGNANDENCRYPT. Therefore bit 0 shall be true if bit 1 is true. Bit 2: SecurityFooter enabled Bit 3: Force key reset This bit is set if all keys will be made invalid. It is set until the new key is used. The Publisher needs to give Subscribers a reasonable time to request new keys. The minimum time is five times the KeepAliveTime configured for the corresponding PubSub group. This flag is typically set if all keys are invalidated to exclude Subscribers, who no longer have access to the keys. Bit range 4-7: Reserved Reserved bits shall be set to false by the the sender and the receiver shall skip messages where the reserved bits are not false. |
|
SecurityTokenId |
IntegerId |
The ID of the security token that identifies the security key in a SecurityGroup. The relation to the SecurityGroup is done through DataSetWriterIds contained in the NetworkMessage. If bit 1 and 2 of the SecurityFlags are 0, the SecurityTokenId shall be 0. |
|
NonceLength |
Byte |
The length of the Nonce used to initialize the encryption algorithm. If bit 1 and 2 of the SecurityFlags are 0, the NonceLength shall be 0. |
|
MessageNonce |
Byte [NonceLength] |
A number used exactly once for a given security key. For a given security key a unique nonce shall be generated for every NetworkMessage. The rules for constructing the MessageNonce are defined for the UADP Message Security in 7.2.4.4.3. |
|
SecurityFooterSize |
UInt16 |
The size of the SecurityFooter. The security footer size shall be omitted if bit 2 of the SecurityFlags is false. |
|
Payload |
Byte [*] |
The payload depends on the UADP NetworkMessage Type flags defined in the ExtendedFlags2 bit range 2-4 and on the Chunk flag defined in the. ExtendedFlags2 bit 0. |
|
SecurityFooter |
Byte [*] |
Optional security footer shall be omitted if bit 2 of the SecurityFlags is false. The content of the security footer is defined by the SecurityPolicy. |
|
Signature |
Byte [*] |
The signature of the NetworkMessage. |
The security algorithms used and the length of the KeyNonce for the UADP NetworkMessage depend on the selected SecurityPolicy. The algorithms are defined by SymmetricEncryptionAlgorithm and SymmetricSignatureAlgorithm in OPC 10000-7. The nonce length is part of the SymmetricEncryptionAlgorithm.
The keys used to encrypt and sign messages are extracted from the key data returned from the GetSecurityKeys method (see 8.3.2). This Method returns a sequence of key data with a length that depends on the SecurityPolicyUri, which is also returned by the Method. The layout of the key data is defined in Table 138.
Table 138 – Layout of the key data for UADP message security
|
Name |
Type |
Description |
|
SigningKey |
Byte [SymmetricSignatureAlgorithm Key Length] |
Signing key part of the key data returned from GetSecurityKeys. The SymmetricSignatureAlgorithm is defined in the SecurityPolicy. |
|
EncryptingKey |
Byte [SymmetricEncryptionAlgorithm Key Length] |
Encryption key part of the key data returned from GetSecurityKeys. The SymmetricEncryptionAlgorithm is defined in the SecurityPolicy. |
|
KeyNonce |
Byte [SymmetricEncryption Nonce Length] |
Nonce part of the key data returned from GetSecurityKeys. |
The layout of the MessageNonce for AES-CTR mode is defined in Table 139.
Table 139 – Layout of the MessageNonce for AES-CTR
|
Name |
Type |
Description |
|
Random |
Byte [4] |
The random part of the MessageNonce. This number does not need to be a cryptographically random number, it can be pseudo-random. |
|
SequenceNumber |
UInt32 |
Sequence number for the MessageNonce as defined in 7.2.3. The sequence number is reset to 1 after the key and SecurityTokenId are updated in the Publisher. |
The message encryption and decryption with AES-CTR mode uses a secret and a counter block. The secret is the EncryptingKey from the key data defined in Table 138. The layout and content of the counter block is defined in Table 140.
Table 140 – Layout of the counter block for UADP message security for AES-CTR
|
Name |
Type |
Description |
|
KeyNonce |
Byte [4] |
The KeyNonce portion of the key data returned from GetSecurityKeys. |
|
MessageNonce |
Byte [8] |
The first 8 bytes of the Nonce in the SecurityHeader of the NetworkMessage. For AES-CTR mode the length of the SecurityHeader Nonce shall be 8 Bytes. |
|
BlockCounter |
Byte [4] |
The counter for each encrypted block of the NetworkMessage. The counter is a 32-bit big endian integer (the opposite of the normal encoding for UInt32 values in OPC UA. This convention comes from the AES-CTR RFC). The counter starts with 1 at the first block. The counter is incremented by 1 for each block. |
AES-CTR mode takes the counter block and encrypts it using the encrypting key. The encrypted key stream is then logically XORed with the data to encrypt or decrypt. The process is repeated for each block in plain text. No padding is added to the end of the plain text. AES-CTR does not change the size of the plain text data and can be applied directly to a memory buffer containing the message.
The signature is calculated on the entire NetworkMessage including any encrypted data. The signature algorithm is specified by the SecurityPolicyUri in OPC 10000-7.
When a Subscriber or a Publisher receives a NetworkMessage, it shall verify the signature before processing the payload. If verification fails, it drops the NetworkMessage.
Other SecurityPolicy may specify different key lengths or cryptography algorithms.
If a NetworkMessage payload with a DataSetMessage need to be split across multiple NetworkMessages, the chunks are sent in multiple NetworkMessages. The PayloadHeader of each NetworkMessage contains the payload header defined in Table 141. The Payload of each NetworkMessage contains the payload defined in Table 142. A chunk NetworkMessage can only contain chunked payload of one DataSetMessage.
If a NetworkMessage payload with a discovery announcement message has to be split across multiple NetworkMessages the chunks are sent with the payload defined in Table 142. The payload header is disabled for discovery probe and discovery announcement NetworkMessages.
Table 141 – Chunked NetworkMessage payload header
|
Name |
Type |
Description |
|
DataSetWriterId |
UInt16 |
DataSetWriterId contained in the NetworkMessage. The DataSetWriterId identifies the PublishedDataSet and the DataSetWriter responsible for sending Messages for the DataSet. A Subscriber can skip DataSetMessages from DataSetWriters it does not expect DataSetMessages from. |
Table 142 – Chunked NetworkMessage payload fields
|
Name |
Type |
Description |
|
MessageSequenceNumber |
UInt16 |
Sequence number of the payload as defined for the NetworkMessage type like DataSetMessageSequenceNumber in a DataSetMessage. NetworkMessages may be received out of order. In this case, a chunk for the next payload can be received before the last chunk of the previous payload was received. If the next sequence number is received by a Subscriber that can handle only one payload, the chunks of the previous payload are skipped if they are not completely received yet. |
|
ChunkOffset |
UInt32 |
The byte offset position of the chunk in the complete NetworkMessage payload. The last chunk is detected if ChunkOffset plus the size of the current chunk equals TotalSize. All chunks, except for the last one shall have the same size. The size of all chunks other than the last one can be used to calculate the number of expected chunks. The reassembled NetworkMessage payload can be processed after all chunks are received. Depending on the transport protocol mapping, the chunks may be received out of order and the last chunk may be received before all other chunks are received. |
|
TotalSize |
UInt32 |
Total size of the NetworkMessage payload in bytes. |
|
ChunkData |
ByteString |
The pieces of the original DataSetMessage or the discovery announcement message are copied into the chunk until the maximum size allowed for a single NetworkMessage is reached minus space for the signature. The data copied into next chunk starts with the byte after the last byte copied into current chunk. A DataSetMessage or discovery announcement message is completely received when all chunks are received and the message can be processed completely. |