View source for A primer on OPC UA certificate stores

[[Category:Application note]] [[Category:OPC UA]] This page is a snapshot of the current state of several new articles from the QuickOPC 2018.3 documentation.

<h1>Certificate Stores</h1>

<h2>Certificate Store Types</h2>

<p>QuickOPC can work with certificates located in&nbsp;<em>certificate stores</em>. Certificate stores are of different types; they are either:</p>

<ul>
    <li>Windows certificate store, or</li>

    <li>directory in a file system.</li>
</ul>

<p>For more details on each of these types, see&nbsp;Windows Certificate
Stores&nbsp;and&nbsp;Directory Certificate Stores.</p>

<h2>Certificate Store Path</h2>

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

<ul>
    <li>If the string starts with <strong>"LocalMachine\"</strong> (case insensitive), it denotes a Windows certificate store for the local computer. The store
    name follows this prefix.</li>

    <li>If the string starts with <strong>"CurrentUser\"</strong> (case insensitive), it denotes a Windows certificate store for the current user. The store
    name follows this prefix.</li>

    <li>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 <em>tokens</em> that refer to specific locations. For details, see&nbsp;Directory Certificate Stores.</li>
</ul>

<h2>Certificate Store Locations</h2>

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

<ul>
    <li><strong>Application certificate store</strong>. 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&nbsp;Providing Client Instance Certificate.
    <span class="Highlight">The application instance certificates in this store include the private keys.</span></li>

    <li><strong>Rejected certificate store</strong>. Server certificates that fail validation are placed into this store.</li>

    <li><strong>Trusted issuers certificate store</strong>. Contains certificates of Certification Authorities to be trusted.</li>

    <li><strong>Trusted peers certificate store</strong>. Contains specific OPC UA application instance certificates to be trusted.</li>
</ul>

<p>For details on rejected certificate store, trusted issuers certificate store and trusted peers certificate store, see&nbsp;Trusting Server Instance Certificate&nbsp;and&nbsp;Trusting Server HTTPS Certificate.</p>

<p>&nbsp;</p>

<p>When targeting .NET framework, by default, all certificates&nbsp;that QuickOPC works with are located in some directory-based certificate store. Specifically:</p>

<ul>
    <li>Default application certificate store is <strong>"%</strong><strong>CommonApplicationData%</strong><strong>\OPC
    Foundation\CertificateStores\MachineDefault"</strong>.</li>

    <li>Default rejected certificate store is <strong>"%</strong><strong>CommonApplicationData%</strong><strong>\OPC
    Foundation\CertificateStores\RejectedCertificates"</strong>.</li>

    <li>Default trusted issuers certificate store is <strong>"%</strong><strong>CommonApplicationData%</strong><strong>\OPC Foundation\CertificateStores\UA
    Certificate Authorities"</strong>.</li>

    <li>Default trusted peers certificate store is <strong>"%</strong><strong>CommonApplicationData%</strong><strong>\OPC Foundation\CertificateStores\UA
    Applications"</strong>.</li>
</ul>

<p>On Windows, the <strong>%</strong><strong>CommonApplicationData%</strong>&nbsp;token typically resolves to something like <strong>"C:\ProgramData"</strong>.
See&nbsp;Directory Certificate Stores&nbsp;for more details.</p>

<p>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:</p>

<ul>
    <li>Default application certificate store is <strong>"%</strong><strong>LocalFolder%/</strong><strong>OPC
    Foundation/CertificateStores/MachineDefault"</strong>.</li>

    <li>Default rejected certificate store is <strong>"%</strong><strong>LocalFolder</strong><strong>%/OPC
    Foundation/CertificateStores/RejectedCertificates"</strong>.</li>

    <li>Default trusted issuers certificate store is <strong>"%</strong><strong>LocalFolder</strong><strong>%/OPC Foundation/CertificateStores/UA Certificate
    Authorities"</strong>.</li>

    <li>Default trusted peers certificate store is <strong>"%</strong><strong>LocalFolder</strong><strong>%/OPC Foundation/CertificateStores/UA
    Applications"</strong>.</li>
</ul>

<p>The <strong>%LocalFolder%</strong> token resolves to the current working directory of the application.</p>

<h2>Certificate Store Security</h2>

<p>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&nbsp;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.</p>

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

<p>&nbsp;</p>

<h1>Directory Certificate Stores</h1>
<h2>Structure of the Directory Certificate Store</h2>

<p>As described in&nbsp;Certificate Stores, <em>directory certificate stores</em> 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.</p>

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

<ul>
    <li>The <strong>"certs"</strong> subdirectory. Contains the certificates without private keys, in .DER format.</li>

    <li>The <strong>"private"</strong> 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).</li>
</ul>

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

<p>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. <strong>"My Application [71511464F08D30AF9F9B2BC21CDB78D49BE568B8]"</strong>. Special characters (like <strong>&lt; &gt; : " / \ | ? *</strong>)&nbsp;that cannot appear in file names are stripped off from the common name.</p>

<h2>Syntax of Directory Certificate Store Path</h2>

<p>In its simplest form, the directory certificate store path is an absolute path to the directory that holds the store, e.g. <strong>"C:\ProgramData\OPC
Foundation\CertificateStores\MachineDefault"</strong>. 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 <em>tokens</em> in the directory certificate store path. A token is
enclosed in percentage sign characters, e.g. <strong>%</strong><strong>CommonApplicationData%</strong>. 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.</p>

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

<ul>
    <li><strong>Special folders</strong>. Any enumerated constant name from the .NET <span class="Identifier">Environment</span>.<span class=
    "Identifier">SpecialFolder</span> enumeration (https://docs.microsoft.com/en-us/dotnet/api/system.environment.specialfolder&nbsp;)
    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: <span class="Identifier">CommonApplicationData</span>, <span class=
    "Identifier">CommonProgramFiles</span>, <span class="Identifier">ProgramFiles</span>, etc.</li>

    <li><strong>Environment variables</strong>. 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.</li>

    <li>On .NET 6+ development platform only: "<strong>%LocalFolder%</strong>" (case sensitive). The current working directory of the application replaces the token. The string does not end with a backslash (\) or a slash (/).</li>
</ul>

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

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

<p>Example: The default application certificate store path is specified as&nbsp;<strong>"%</strong><strong>CommonApplicationData%</strong><strong>\OPC
Foundation\CertificateStores\MachineDefault"</strong>, and it may resolve to <strong>"C:\ProgramData\OPC
Foundation\CertificateStores\MachineDefault"</strong>.</p>

<p>&nbsp;</p>
<h1>Windows Certificate Stores</h1>
<p>The Windows Certificate Stores are implemented and maintained by the Windows operating system. As explained in&nbsp;Certificate Stores, you specify the Windows certificate store by starting the certificate store path by either
<strong>"LocalMachine\"</strong> or <strong>"CurrentUser\"</strong>.</p>

<ul>
    <li>If the string starts with <strong>"LocalMachine\"</strong> (case insensitive), it denotes a Windows certificate store for the local computer. Commonly
    used examples are: <strong>"LocalMachine\My"</strong>, <strong>"LocalMachine\UA Applications"</strong> or "<strong>LocalMachine\UA Certificate
    Authorities"</strong>.</li>

    <li>If the string starts with <strong>"CurrentUser\"</strong> (case insensitive), it denotes a Windows certificate store for the current user. Commonly
    used examples are: <strong>"CurrentUser\My"</strong> or <strong>"CurrentUser\Root"</strong>.</li>
</ul>

<p>The store name follows the prefix.</p>

{{Note|
To manage the local computer certificates, type {{Style=keyboard|certlm.msc}} into the Windows search box, and press Enter. You will need administrative privileges to manage the local computer certificates.<br/>
To manage the certificates for the current user, type {{Style=keyboard|certmgr.msc}} into the Windows search box, and press Enter.<br/>
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.
}}

<p>&nbsp;</p>

<syntaxhighlight lang="C#">
// 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.");
        }
    }
}
</syntaxhighlight>

<p>&nbsp;</p>