Configure the certificate validation management in S2OPC server / client

In order to activate secure communication (integrity and confidentiality) in your S2OPC server or client you will need to configure a Public Key Infrastructure (PKI) provider to manage the peer certificate validation.

A default implementation of PKI provider is provided with S2OPC toolkit (see src/Common/crypto/sopc_pki_stack.h), all you need is configure it for your needs.

Default PKI provider principles

The PKI verifies a certificate in the safest manner (whole certificate chain, with date validation, mandatory certificate revocation lists). Certificate Authority (CA) requirements (such as the hash algorithm used for the signature) depend on the chosen OPC UA security policy.

There are 3 types of certificates to provide to the PKI:

• The "trusted issuers" are Certificate Authorities (CAs) from which issued certificates are also trusted. All the certificates of the signing chain including the root CA must be provided.
• The "issued certificates" are certificates issued by untrusted CA or self-issued. These certificates are considered themselves trustworthy (if the certificate properties and its signature are both valid).
• The "untrusted issuers" are CAs which are used to verify the signing chain of the "issued certificates". Each issued certificate must have its whole signing CA chain in the untrusted issuers or the trusted issuers up to the root CA.

Note: the difference between trusted issuers and trusted issued certificates is that issued certificates are trusted on a one by one basis, whereas the trusted issuer may emit a large number of trusted certificates.

Note 2: each CA shall be provided with an associated Certificate Revocation List (CRL) to be considered valid by the PKI. See details on CRL list below.

Note 3: certificates issued by trusted CA don't need to be provided to the PKI.

Note 4: unknown self-signed certificates are not trustworthy.

In addition, there are two more concepts:

• A link (or intermediate) CA is part of the certificate validation chain. All links between a certificate and a root certificate must be provided (and sorted in child to parent order).
• A root CA is always trusted, even if there are other root CAs that signed it. Hence the parent of root CAs will never be checked, and the validation stops on root CAs.

Finally the list of Certificate Revocation List (CRL) shall contain exactly one list for each CA of the provided CAs, either link or root, trusted or untrusted. Issued certificates should not have CRLs, as they cannot be used to trust any other certificate. When an issued certificate is used to protect a Secure Channel, its signing chain will be verified. For instance, if the certificate is not self signed and appears on the CRL of its signing CA, the connection will fail as the certificate is in fact invalid.

Use server XML configuration to configure the PKI

In order to configure the certificates provided to the PKI it is possible to use the S2OPC server XML configuration format (schemas/s2opc_clientserver_config.xsd). The XML configuration can be used to automatically configure the S2OPC demo server (see Start S2OPC demo server wiki) or to generate a fulfilled SOPC_Server_Config structure to configure your own server implementation.

Examples of configuration extract for certificate validation:

• Certificate validation based on a single root CA: all certificates directly signed by myCompanyCA.der are accepted:

    <ApplicationCertificates>
      <ServerCertificate path="/certs/server/my_server_cert.der"/>
      <ServerKey path="/cert/server/my_server_key/my_server_key.pem"/>
      <TrustedIssuers>
        <TrustedIssuer root="true" cert_path="/certs/PKI/trusted/myCompanyCA.der"
                       revocation_list_path="/certs/PKI/revoked/myCompanyCRL.der"/>
      </TrustedIssuers>
    </ApplicationCertificates>

• Certificate validation based on a root CA rootCA.der and intermediate CAs child1CA.der (signed by root) and child2CA.der signed by first child CA: all certificates signed by any of the CA are accepted and trust chain is verified (certificate and intermediate CAs signatures until root CA):

    <ApplicationCertificates>
      <ServerCertificate path="/certs/server/my_server_cert.der"/>
      <ServerKey path="/cert/server/my_server_key/my_server_key.pem"/>
      <TrustedIssuers>
        <!-- Intermediate CAs shall be provided in the order child to parent to be verified by default PKI -->
        <TrustedIssuer root="false" cert_path="/certs/PKI/trusted/child2CA.der"
                       revocation_list_path="/certs/PKI/revoked/child2CRL.der"/>
        <TrustedIssuer root="false" cert_path="/certs/PKI/trusted/child1CA.der"
                       revocation_list_path="/certs/PKI/revoked/child1CRL.der"/>
        <TrustedIssuer root="true" cert_path="/certs/PKI/trusted/rootCA.der"
                       revocation_list_path="/certs/PKI/revoked/rootCRL.der"/>
      </TrustedIssuers>
    </ApplicationCertificates>

Note 1: Intermediate CAs (non root CA) shall be provided in child to parent order, several chains can be provided as long as it complies with the child to parent order in each chain.

Note 2: Trusted intermediate CAs may also be defined as root CA in this configuration, in this case the chain will not be verified by PKI since any certificate signed by one of the CA defined as root will be accepted without checking signature of the root certificate.

• Certificate validation based on self-signed certificates myClient1.der and myClient2.der: only the self-issued certificates will be considered as valid by the PKI:

    <ApplicationCertificates>
      <ServerCertificate path="/certs/server/my_server_cert.der"/>
      <ServerKey path="/cert/server/my_server_key/my_server_key.pem"/>
      <IssuedCertificates>
        <IssuedCertificate path="/certs/issued/myClient1CA.der"/>
        <IssuedCertificate path="/certs/issued/myClient2CA.der"/>
      </IssuedCertificates>
    </ApplicationCertificates>

• Certificate validation based on a issued certificate myClient.der signed by untrusted intermediate CA child2CA.der (signature chain: child2CA <- child1CA <- rootCA) : all certificates signed by the root CA are accepted and the issued certificate is only accepted if its trust chain is valid whereas we do not trust the intermediate CAs:

    <ApplicationCertificates>
      <ServerCertificate path="/certs/server/my_server_cert.der"/>
      <ServerKey path="/cert/server/my_server_key/my_server_key.pem"/>
      <TrustedIssuers>
       <TrustedIssuer root="true" cert_path="/certs/PKI/trusted/rootCA.der" 
                      revocation_list_path="/certs/PKI/revoked/rootCRL.der"/>
      </TrustedIssuers>
      <UntrustedIssuers>
        <!-- Intermediate CAs shall be provided in the order child to parent -->
        <UntrustedIssuer root="false" cert_path="/certs/PKI/trusted/child2CA.der" 
                       revocation_list_path="/certs/PKI/revoked/child2CRL.der"/>
        <UntrustedIssuer root="false" cert_path="/certs/PKI/trusted/child1CA.der" 
                       revocation_list_path="/certs/PKI/revoked/child1CRL.der"/>
      </UntrustedIssuers>
      <IssuedCertificates>
        <IssuedCertificate path="/certs/issued/myClient.der"/>
      </IssuedCertificates>
    </ApplicationCertificates>

Note: any other certificate than myClient.der signed by untrusted intermediate CAs will be refused since we only trust known issued certificates. The root CA certificate might also be untrusted, in this case all certificates directly signed by the root CA will be also refused.

Configure a PKI manually

If you implement your own server or client based on S2OPC toolkit you will need to instantiate the PKI using the function SOPC_PKIProviderStack_CreateFromPaths. The parameters content is the same as described for XML above and those can be instantiated from the XML itself on server side using SOPC_Server_Config structure content.

Examples of instantiation are provided in the server / client examples, see Build your own server or client.

It is also possible to use function SOPC_PKIProviderStack_Create to create the PKI from already parsed certificates (limited to root CA / self-signed certificates for now).

Certificates and keys generation

The certificates and keys shall be generated for the server and client applications with configuration adapted to the deployment platform. The certificate generation script and configuration files provided by S2OPC product should be used: https://gitlab.com/systerel/S2OPC/-/blob/master/samples/ClientServer/data/cert/ The following files shall be adapted:

• generate_certs.sh: the “-days” configuration shall be set to a value less than or equal to 1 or 2 years.
• cli_req.cnf: the “alternate_names” “URI” and “DNS.1” sections shall be changed using the hostname of the machine that will run the client applications instead of “localhost”.
• srv_req.cnf: the “alternate_names” “URI” and “DNS.1” sections shall be changed using the hostname of the machine that will run the server application instead of “localhost”.

Once modification done, the script “generate_certs.sh” should be called and the new certificate and keys are generated.