Using OpcCmd Utility for OPC UA Administration

Under construction: Parts are missing.

How to: Make a rejected certificate trusted

If you do not set up the trust between the OPC UA applications (client and server) upfront, you often end up with other party's application certificate being rejected (for example, the OPC UA client will reject the OPC UA server's certificate when you try to connect securely to a new server). As a convenience, the actual certificate provided by the other party at that point is stored into the so-called Rejected certificate store. If you know that this certificate, in fact, should be trusted, you can move it to the Trusted peers certificate store. Next time, it will not be rejected.

There are multiple ways to move the certificate, and the procedures differ depending on the placement of certificate store involved (platform-specific, or a directory). The steps described below work with the default configuration of OPC UA applications that target .NET Framework (or COM applications). Such applications share a common group of certificate stores, located in a dedicated directory in the file system. Any file manipulation tool can be used for move and copy operations with the certificates, but it might be somewhat difficult to find the right directory and navigate between the sub-directories of the directory certificate stores. With the OpcCmd Utility, you can make the rejected certificate trusted in just a few steps. Note that applications that target .NET Core or .NET 5+ have a different default location of the certificate stores, and therefore this procedure cannot be directly used.

1. At the OpcCmd> prompt, enter uaAdministration pki applicationStoreGroup --placement LegacyDirectoryCommon, or shortened: uaa pki asg -p LegacyDirectoryCommon. This command tells the utility that from now on, we will be accessing the common group of PKI stores for the OPC UA applications written for .NET Framework with the use of OPC Foundation's UA stack and SDK. The program responds with a confirmation of the command.
   
   All following commands are entered at the pkiApplicationStoreGroup> 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).
   
   
2. Enter store Instance.Rejected certificates?, or shortened: s Instance.Rejected c?. This command will show a table that contains information about all rejected certificates. The output may look similar to this:

Result (sequence):
╒══╤══════════════╤════════════════════════════════════════════════╤════════════════════════╤══════════╤══════════╤════════════════════╤═══════╕
│[]│Signature     │Subject Simple Name                             │Issuer Simple Name      │Not Before│Not After │Thumbprint          │Has    │
│  │Algorithm Name│                                                │                        │          │          │                    │Private│
│  ├──────────────┼────────────────────────────────────────────────┼────────────────────────┤          │          │                    │Key    │
│  │Public Key    │Subject DNS Name                                │Serial Number           │          │          │                    │       │
│  │Size          │                                                │                        │          │          │                    │       │
│  ├──────────────┼────────────────────────────────────────────────┤                        │          │          │                    │       │
│  │CA            │Subject URL Name                                │                        │          │          │                    │       │
╞══╪══════════════╪════════════════════════════════════════════════╪════════════════════════╪══════════╪══════════╪════════════════════╪═══════╡
│ 0│sha256RSA     │Global Discovery Server                         │Global Discovery Server │9/12/2020 │9/12/2021 │86A2C4D0A9FD07D1A85F│False  │
│  │          2048│demo-5                                          │1EBFEB858386FC19        │1:21:52 PM│1:21:52 PM│84090A88A5B3CA4F1DA5│       │
│  │False         │urn:demo-5:somecompany.com:GlobalDiscoveryServer│                        │          │          │                    │       │
├──┼──────────────┼────────────────────────────────────────────────┼────────────────────────┼──────────┼──────────┼────────────────────┼───────┤
│ 1│sha256RSA     │UaServerCpp@PC-ZBYNEKZ-4                        │UaServerCpp@PC-ZBYNEKZ-4│3/16/2021 │3/15/2026 │CA0C65DB312C5458D21A│False  │
│  │          2048│PC-ZBYNEKZ-4                                    │6050A511                │1:31:13 PM│1:31:13 PM│54D6AB02C5497DBCEC33│       │
│  │True          │urn:PC-ZBYNEKZ-4:UnifiedAutomation:UaServerCpp  │                        │          │          │                    │       │
╘══╧══════════════╧════════════════════════════════════════════════╧════════════════════════╧══════════╧══════════╧════════════════════╧═══════╛
Command finished (0.2 seconds).

3. The table displayed by the previous command should contain the certificate that has previously been rejected and that you want to make trusted. Locate the corresponding row in the table. For security reasons, you should compare the thumbprint listed in the table with the known thumbprint of the certificate you want to trust (this is often neglected, but it shouldn't). For example, if a server's certificate has been rejected on the client side, the server usually has a way to display its application certificate and its thumbprint, and you should compare it with the one in the table.


4. Enter moveCertificates Instance.Rejected Instance.Trusted xxxx*, or shortened: mc Instance.Rejected Instance.Trusted xxxx*, replacing xxxx with several leading characters of the thumbprint (notice also the asterisk that follows them, at the end of the command!). You should use enough characters to uniquely distinguish the desired certificate from any other certificates in the store. For example, if you wanted to move the certificate of the "Global Discovery Server" as listed in the example output above, you could use the command moveCertificates Instance.Rejected Instance.Trusted 86A2*, but moveCertificates Instance.Rejected Instance.Trusted 8* would also have the same effect. Alternatively, you can use the full thumbprint, without the asterisk at the end. The command will move the certificate(s) that matches the given thumbprint pattern from the Rejected certificate store to the Trusted peers certificate store. The command output may look similar to this:

Moving PKI certificates...
Number of certificates moved: 1
Command finished (3.9 seconds).

5. Verify that in the output of the command above, the "Number of certificates moved" value is equal to 1. If the certificate was not found (e.g. you made a mistake when specifying the thumbprint pattern), the value would be 0. If more certificates were moved, the number would be greater than 1.


6. If you like, you can additionally verify the presence of the certificate in the Trusted peers certificate store. To do so, enter store Instance.Trusted certificates?, or shortened: s Instance.Trusted c?