A primer on OPC UA certificate stores

This page is a snapshot of the current state of several new articles from the QuickOPC 2018.3 documentation.

Certificate Stores

Certificate Store Types

QuickOPC can work with certificates located in certificate stores. Certificate stores are of different types; they are either:

• Windows certificate store, or
• directory in a file system.

For more details on each of these types, see Windows Certificate Stores and Directory Certificate Stores.

Certificate Store Path

The certificate store is identified by a string, called certificate store path. The syntax and semantics of this string is as follows:

• If the string starts with "LocalMachine\" (case insensitive), it denotes a Windows certificate store for the local computer. The store name follows this prefix.
• If the string starts with "CurrentUser\" (case insensitive), it denotes a Windows certificate store for the current user. The store name follows this prefix.
• Otherwise, the string denotes a certificate store located in a file system directory, and the value is equal to the directory path. The string can contain replaceable tokens that refer to specific locations. For details, see Directory Certificate Stores.

Certificate Store Locations

QuickOPC uses several certificate stores for its operations. The location of the stores is given by various parameters. The stores are:

• Application certificate store. A client application created with QuickOPC looks for or creates its own instance certificate here. The location of the store is controlled by EasyUAClient.SharedParameters.EngineParameters.ApplicationParameters.ApplicationCertificateStore property. For more details, see Providing Client Instance Certificate. The application instance certificates in this store include the private keys.
• Rejected certificate store. Server certificates that fail validation are placed into this store.
• Trusted issuers certificate store. Contains certificates of Certification Authorities to be trusted.
• Trusted peers certificate store. Contains specific OPC UA application instance certificates to be trusted.

For details on rejected certificate store, trusted issuers certificate store and trusted peers certificate store, see Trusting Server Instance Certificate and Trusting Server HTTPS Certificate.

 

When targeting .NET framework, by default, all certificates that QuickOPC works with are located in some directory-based certificate store. Specifically:

• Default application certificate store is "%CommonApplicationData%\OPC Foundation\CertificateStores\MachineDefault".
• Default rejected certificate store is "%CommonApplicationData%\OPC Foundation\CertificateStores\RejectedCertificates".
• Default trusted issuers certificate store is "%CommonApplicationData%\OPC Foundation\CertificateStores\UA Certificate Authorities".
• Default trusted peers certificate store is "%CommonApplicationData%\OPC Foundation\CertificateStores\UA Applications".

On Windows, the %CommonApplicationData% token typically resolves to something like "C:\ProgramData". See Directory Certificate Stores for more details.

When targeting .NET 6+, all certificates that QuickOPC works with are located in a directory-based certificate store under the current working directory by default. Specifically:

• Default application certificate store is "%LocalFolder%/OPC Foundation/CertificateStores/MachineDefault".
• Default rejected certificate store is "%LocalFolder%/OPC Foundation/CertificateStores/RejectedCertificates".
• Default trusted issuers certificate store is "%LocalFolder%/OPC Foundation/CertificateStores/UA Certificate Authorities".
• Default trusted peers certificate store is "%LocalFolder%/OPC Foundation/CertificateStores/UA Applications".

The %LocalFolder% token resolves to the current working directory of the application.

Certificate Store Security

In a secure deployment, the certificate store itself (that is, read and write access to the certificates it contains) must be secured. QuickOPC needs appropriate permissions to read from (and sometimes write to) the certificate stores. At the same time, access should be denied to unauthorized actors. This is most critical for the write access to the stores (and for read access to the private key parts). Securing the certificate stores is outside of QuickOPC scope.

Warning: By default, the private keys in OPC UA certificate stores are not protected by passwords.

 

Directory Certificate Stores

Structure of the Directory Certificate Store

As described in Certificate Stores, directory certificate stores reside in a file system. In many cases, their structure can remain an opaque implementation detail to you. Knowing the structure comes handy if you need to deal with them externally or manually.

There are no files at the "root" of the directory certificate, only sub-directories, and they are:

• The "certs" subdirectory. Contains the certificates without private keys, in .DER format.
• The "private" subdirectory (only in certificate stores which need it). Contains the certificate *with* private keys, in .PFX format. Instead of .PFX, it can also contain just the private key, in .PEM format (QuickOPC recognizes this but does not itself create files in directory certificate stores in this way).

If the certificate store contains a certificate with a private key, it will therefore be present in both "certs" and "private" subdirectories, each time in a different format.

The file name of each certificate comprises of the certificate common name (from its subject), followed by a space, and the certificate thumbprint in square brackets, e.g. "My Application [71511464F08D30AF9F9B2BC21CDB78D49BE568B8]". Special characters (like < > : " / \ | ? *) that cannot appear in file names are stripped off from the common name.

Syntax of Directory Certificate Store Path

In its simplest form, the directory certificate store path is an absolute path to the directory that holds the store, e.g. "C:\ProgramData\OPC Foundation\CertificateStores\MachineDefault". Since absolute paths are not flexible enough and may fail to work when the application is transferred to a computer with different configuration, QuickOPC allows you to include replaceable tokens in the directory certificate store path. A token is enclosed in percentage sign characters, e.g. %CommonApplicationData%. For the token to be recognized, the directory certificate store path must begin directly with the token (the percent sign). Tokens are not recognized further down in the string.

The following three types of tokens can be used. QuickOPC searches for them from top to bottom.

• Special folders. Any enumerated constant name from the .NET Environment.SpecialFolder enumeration (https://docs.microsoft.com/en-us/dotnet/api/system.environment.specialfolder ) can be used as a token. The token is replaced by the absolute path of the corresponding special folder. Not all available special folders make sense with OPC UA, but the following ones are good candidates: CommonApplicationData, CommonProgramFiles, ProgramFiles, etc.
• Environment variables. These are the operating system environment variable names, as available to the current process. The value of the environment variable is retrieved, and replaces the token.
• On .NET 6+ development platform only: "%LocalFolder%" (case sensitive). The current working directory of the application replaces the token. The string does not end with a backslash (\) or a slash (/).

If the token name is not recognized, the token is replaced by an empty string (i.e. the token is removed).

When targeting .NET Framework (as opposed to .NET 6+), the default directory certificate store paths all start with the %CommonApplicationData% token, which typically resolves to something like "C:\ProgramData".

Example: The default application certificate store path is specified as "%CommonApplicationData%\OPC Foundation\CertificateStores\MachineDefault", and it may resolve to "C:\ProgramData\OPC Foundation\CertificateStores\MachineDefault".

 

Windows Certificate Stores

The Windows Certificate Stores are implemented and maintained by the Windows operating system. As explained in Certificate Stores, you specify the Windows certificate store by starting the certificate store path by either "LocalMachine\" or "CurrentUser\".

• If the string starts with "LocalMachine\" (case insensitive), it denotes a Windows certificate store for the local computer. Commonly used examples are: "LocalMachine\My", "LocalMachine\UA Applications" or "LocalMachine\UA Certificate Authorities".
• If the string starts with "CurrentUser\" (case insensitive), it denotes a Windows certificate store for the current user. Commonly used examples are: "CurrentUser\My" or "CurrentUser\Root".

The store name follows the prefix.

Note: To manage the local computer certificates, type certlm.msc into the Windows search box, and press Enter. You will need administrative privileges to manage the local computer certificates.
To manage the certificates for the current user, type certmgr.msc into the Windows search box, and press Enter.
Note, however, that the logical store names displayed by the management console are not the same as the physical certificate store names, and that some stores may not be displayed at all.

 

// This example demonstrates how to place the client certificate in the Windows certificate store.

using System;
using OpcLabs.EasyOpc.UA;

namespace UADocExamples._UAApplicationParameters
{
    class ApplicationCertificateStore
    {
        public static void Windows()
        {
            UAEndpointDescriptor endpointDescriptor =
                "opc.tcp://opcua.demo-this.com:51210/UA/SampleServer";
            // or "http://opcua.demo-this.com:51211/UA/SampleServer" (not in .NET Standard)
            // or "https://opcua.demo-this.com:51212/UA/SampleServer/"

            // Set the application certificate store path, which determines the location of the client certificate.
            // Note that this only works once in each host process.
            EasyUAClient.SharedParameters.EngineParameters.ApplicationParameters.ApplicationCertificateStore = "CurrentUser\\My";

            // Do something - invoke an OPC read, to trigger creation of the certificate.
            var client = new EasyUAClient();
            client.ReadValue(endpointDescriptor, "nsu=http://test.org/UA/Data/;i=10853");

            // The certificate will be located or created in the specified Windows certificate store.
            // When viewed by the certmgr.msc tool, it will be under
            // Certificates - Current User -> Personal -> Certificates.

            Console.WriteLine("Done.");
        }
    }
}