Using OpcCmd Utility to work with OPC UA Security Key Service (SKS)

From OPC Labs Knowledge Base

For general information about the OpcCmd tool, see Category:OpcCmd Utility.

Tutorial

If you execute the commands listed in the tutorial below, you will get an overview of basic operations that can be made with an OPC UA Server that provides OPC UA Security Key Service (SKS).

This tutorial works with Unified Automation C++ SDK Demo Server. You should be able to use the principles explained in this tutorial with other OPC UA servers that provide the Security Key Service, by modifying the relevant parameters used in the commands.


  1. Start the Unified Automation C++ SDK Demo Server. In Windows, type start uaservercpp.exe at the operating system command prompt.
    Uaservercpp.png

  2. Start the OpcCmd utility in interactive mode. The interactive mode is always in effect e.g. when you use ClickOnce, or when running the utility from QuickOPC Launcher/Start menu. In other cases, you need to use the -i (or --interactive) option on the command line.

  3. Using an external tool, configure a security group inside the Security Key Service (SKS) of the server. For the remainder of this tutorial, we will assume that the security group has been given an Id "TestGroup". You will need to change the commands accordingly if the security group Id is different.
    How the security group is created is outside of the scope of this article. You can e.g.
    • use a generic OPC UA client and call the AddSecurityGroup method on the Objects/Server/PublishSubscribe/SecurityGroups object, or
    • use a dedicated OPC UA PubSub configuration tool, or
    • copy a ready-made "pubsubconfig.uabinary" file to the server's instalation folder (Media:Pubsubconfig-testgroup.zip).

  4. At the OpcCmd> prompt, enter uaPublishSubscribeClient accessSecurityKeyService opc.tcp://localhost:48010 --EndpointAllowedMessagedSecurity SecuritySignAndEncrypt --EndpointUser root:secret, or shortened: uapsc asks opc.tcp://localhost:48010 -eams SecuritySignAndEncrypt -eu root:secret. This command tells the utility that from now on, we will be accessing the Security Key Service in the specified OPC UA server, using a secured connection and authenticating as the specified user (these are common security requirements as the SKS itself is a security sensitive component). The programs responds with a confirmation of the command.

    All following commands are entered at the uaPubSubSecurityKeyService> prompt. You can enter -?, -h or --help (possibly preceded by the command name) at any time to obtain help for this prompt (or its commands).

  5. In order to obtain information security groups configured in the SKS, enter browseSecurityGroups (browseSecurityGroups can be shortened to bsg).
    If this is the first operation made from this client on the server, you will most likely receive an error, caused by the fact that the server does not trust the client. In order to establish the trust:
    1. The Unified Automation C++ SDK Demo Server will have a copy of the rejected client certificate in its "rejected certificates" folder. Under the installation folder of the server, copy the rejected client certificate from pkiserver/rejected folder to pkiserver/trusted/certs folder.
    2. Enter the browseSecurityGroups command again.

  6. The OpcCmd Utility will now ask you whether you want the client to trust the server certificate (this is the inverse to the trust established above). Verify that that you have been presented with the right server server certificate, and if so, accept the certificate by pressing Y for "Yes".
    After the certificate is accepted, the browseSecurityGroups proceeds.
    Opccmd-uapubsubsecuritykeyservice-browsesecuritygroups.png
    As you can see, the command outputs a table with information available about each security group configured in the SKS (more precisely, in the security groups root folder).

  7. If there are multiple security groups in the SKS< you might be interested in getting information about a specific security group only. For example, to get information about the "TestGroup" security group, enter getSecurityGroupElement TestGroup (getSecurityGroupElement can be shortened to gsge). The command will output configuration information for the specified security group.

  8. In more complicated servers, the security groups are organized into security group folders, which form a tree structure (a hierarchy). To view the tree of all available security group folders, and the security groups in them, enter browseTree (browseTree can be shortened to bt).
    Opccmd-uapubsubsecuritykeyservice-browsetree.png

  9. You can ask the server to provide you with the security keys for communication. As opposed to the configuration tasks that we have done earlier, this is a runtime operation that is normally performed by publishers and subscribers during the SKS operation, invisibly to the normal user. It might be useful, however, to do this manually, in order to verify the SKS operation. The security keys are identified by an integer token Id which keeps incrementing (a circular counter). You need to specify the first token Id and the number of keys you are requesting. The first token Id can be zero (for current token), or a specific number, allowing you to start with a past or future key. For example, to obtain 10 keys starting from the current one, enter getSecurityKeys TestGroup 0 10 (getSecurityKeys can be shortened to gsk).
    Opccmd-uapubsubsecuritykeyservice-getsecuritykeys.png
    The command outputs the information about the security keys provided (such as the actual first token Id provided, security policy URI that needs to be used to interpret the keys, key lifetime, and more), and the actual security keys.

  10. Enter getSecurityKeys TestGroup 3 5 to obtain 5 security keys starting at security token Id 3.

  11. If you want to monitor the security keys provided by the SKS over a period of time, you can instruct the OpcCmd tool to repeat the getSecurityKeys command. In order to repeatedly obtain the security keys from the SKS and display them, enter getSecurityKeys TestGroup 0 10 !repeat Infinite 0:0:15 !wait Infinite. The command waits 15 seconds between the invocations, and repeats until you stop it by pressing X on the keyboard. In a way, what this command does is similar to what a publisher would do in order to stay up-to-date with the security keys from the SKS.

Other Commands

Other commands at the uaPubSubSecurityKeyService> prompt, not used in this tutorial, include:

  • listSecurityGroupFolderNames
  • listSecurityGroupIds

Related Reading

Retrieved from "https://kb.opclabs.com/index.php?title=Using_OpcCmd_Utility_to_work_with_OPC_UA_Security_Key_Service_(SKS)&oldid=3740"