How to publish or subscribe to secure OPC UA PubSub messages
Publish secure messages in UADemoPublisher
Enter the following command at the UADemoPublisher> prompt:
publish --EnabledConnection DynamicLayoutConnection --EnabledDataSetWriter SimpleWriter --SecurityMode SignAndEncrypt --SecurityKeyServiceUri opc.tcp://localhost:48010 --SecurityKeyServiceMessageSecurity SignAndEncrypt --SecurityKeyServiceUserInfo root:secret --SecurityGroupId TestGroup --SaveConfiguration
Explanation of the command line arguments and options used:
- --EnabledConnection DynamicLayoutConnection
- Normally, messages are published on multiple connections. For easier troubleshooting, this option selects just one of them.
- --EnabledDataSetWriter SimpleWriter
- Normally, multiple dataset writers contribute to a network message. For easier troubleshooting, this option selects just one of them.
- --SecurityMode SignAndEncrypt
- Specifies the security mode for the PubSub network messages produced.
- --SecurityKeyServiceUri opc.tcp://localhost:48010
- Specifies the URL of the SKS (Security Key Service) endpoint.
- --SecurityKeyServiceMessageSecurity SignAndEncrypt
- Specifies the security mode that will be used to connect to the SKS.
- --SecurityKeyServiceUserInfo root:secret
- Specifies the user name and password used for "logging in" to the SKS.
- --SecurityGroupId TestGroup
- Specifies the Id of the security group in the SKS that will be used (the security group in the SKS is configured to use certain security policy, and has other parameters detailing how the security keys are generated).
- --SaveConfiguration
- Tells the application to create a file named UADemoPublisher.uabinary with the configuration the publisher is using (influenced by all the other options provided). The configuration file also contains metadata for the published datasets, and might be used by subscribers in consuming the published messages.
This command publishes message with dynamic layout that are (to certain extent) self-describing, and data can be extracted from them by subscribers without the necessity to have the associated metadata available too.
Publish (secure) messages with fixed layout
In order to publish (secure) messages with fixed layout, replace --EnabledConnection DynamicLayoutConnection in the above command by --EnabledConnection FixedLayoutConnection. In this case, subscribers will need the associated metadata in order to fully parse the published messages. The metadata is contained in the UADemoPublisher.uabinary file generated by the command.
Subscribe to secure messages in OpcCmd utility
Enter the following command at the OpcCmd> prompt:
uaSubscriber subscribeDataSet opc.udp://239.0.0.1:4840 --SecurityKeyServiceUri opc.tcp://localhost:48010 --SksTemplateMessageSecurity SecuritySignAndEncrypt --SksTemplateUser root:secret --SecurityGroupId TestGroup --SecurityMode SecuritySignAndEncrypt
Explanation of the command line arguments and options used:
- opc.udp://239.0.0.1:4840
- The URL of the UDP multicast group on which the subscriber will be listening for PubSub network messages.
- --SecurityMode SecuritySignAndEncrypt
- Specifies the security mode for the PubSub network messages received. This is a minimum security mode that you want to accept.
- --SecurityKeyServiceUri opc.tcp://localhost:48010
- Specifies the URL of the SKS (Security Key Service) endpoint.
- --SksTemplateMessageSecurity SecuritySignAndEncrypt
- Specifies the security mode that will be used to connect to the SKS.
- --SksTemplateUser root:secret
- Specifies the user name and password used for "logging in" to the SKS.
- --SecurityGroupId TestGroup
- Specifies the Id of the security group in the SKS that will be used (the security group in the SKS is configured to use certain security policy, and has other parameters detailing how the security keys are generated).
Use publisher configuration and/or subscribe to fixed layout messages
In order to subscribe to fixed layout messages, the subscriber needs to have the metadata about the published dataset. If the publisher is the UADemoPublisher (see above), it gives you a PubSub configuration file that contains (among other information) the metadata needed.
Make sure the UADemoPublisher.uabinary file is available to the OpcCmd utility (e.g. by copying it to the same directory, or specifying full path to it in the command below), and enter the following command at the OpcCmd> prompt:
uaSubscriber subscribeDataSet --ResolverPublisherFileResourceUri UADemoPublisher.uabinary --PublishedDataSetName Simple
Compared to the previous command, not only does this command get the metadata from the configuration file, but it also uses the configuration file to determine all other parameters necessary for communication with the SKS, and interpreting the PubSub network messages. All that was really needed was to specify the name of the published dataset you want to subscribe to, using the --PublishedDataSetName command option. Note that this only works if the publisher configuration has only one (currently enabled) way of publishing the dataset with the specified name. Otherwise, you will need to narrow down the search by specifying e.g. the connection name, or writer group name, using more command options of the subscribeDataSet command.
Publishers other than the UADemoPublisher can also be OPC UA servers, and provide the PubSub configuration (and metadata) online, as part of their information model. In such case, use the --ResolverPublisherEndpointUri command option instead of --ResolverPublisherFileResourceUri to specify where to look for the configuration. The command to subscribe to the specified published dataste may then look like this:
uaSubscriber subscribeDataSet --ResolverPublisherEndpointUri opc.tcp://localhost:48010 --PublishedDataSetName PubDS_1 --SksTemplateUser root:secret
Enable security event tracing in command-line tools
Use the following commands in the OpcCmd utility or in UADemoPublisher (at the beginning of the program session) to enable tracing of security-related events:
!diagnostics switches setValue 1 --multiple --contains Security --typeName BooleanSwitch !diagnostics sources setSwitchValue Verbose --multiple --contains Security
Use the following command to show the trace entries after a command has been run:
traceEntries?
Using static security key
In order to bypass the SKS and always us the same security key (for troubleshooting purposes), you can use the "static:" scheme in the --SecurityKeyServiceUri command option, and specify the security key as a string of hexadecimal digits in the "key" parameter in the URI query part, e.g.:
--SecurityKeyServiceUri static:?key=0101010101020202020203030303030404040404050505050506060606060707070707080808080809090909090A0A0A0A0A0B0B
The full command to publish with a static security key at the UADemoPublisher> prompt is then:
publish --EnabledConnection DynamicLayoutConnection --EnabledDataSetWriter SimpleWriter --SecurityMode SignAndEncrypt --SecurityKeyServiceUri static:?key=0101010101020202020203030303030404040404050505050506060606060707070707080808080809090909090A0A0A0A0A0B0B --SecurityGroupId TestGroup
The full command to subscribe with a static security key at the OpcCmd> prompt is then:
uaSubscriber subscribeDataSet opc.udp://239.0.0.1:4840 --SecurityKeyServiceUri static:?key=0101010101020202020203030303030404040404050505050506060606060707070707080808080809090909090A0A0A0A0A0B0B --SecurityGroupId TestGroup --SecurityMode SecuritySignAndEncrypt
The security policy is determined from the available policies and the size of the provided key (for example, PubSub-Aes128-CTR is chosen when the key has 52 bytes, and PubSub-Aes256-CTR is chosen when the key has 68 bytes). When the security policy cannot be determined in this way, or you want to override the default, use the "securityPolicyUri" parameter in the URI query part to specify the security policy URI.
Security key in file system
QuickOPC supports static security key that is specified by a set of files residing in a file system directory. This key storage format is used by Systerel S2OPC (https://gitlab.com/systerel/S2OPC ). You specify the directory by using the "keyPartsDirectory" parameter in the URI query part, instead of the "key" parameter as discussed above. The URI may then be e.g. static:?keyPartsDirectory=C:\MyDirectory. The specified directory must contain binary key files named signingKey.key, encryptKey.key and keyNonce.key, from which QuickOPC will assemble the key data for UADP message security.
