|
|
# Configure the certificate validation in your OPC UA server / client
|
|
|
|
|
|
In order to activate OPC UA secure communication (integrity and confidentiality) it is necessay to define in which cases a certificate will be valid for you application. A common way to achieve this goal is to define one or several Certificate Authorities (CAs) your application trusts, then all certificates signed by those CAs will be considered valid if security checks pass.
|
|
|
|
|
|
## Reminder on the certificates constraints for OPC UA
|
|
|
|
|
|
### Generate correct certificates for OPC UA usage
|
|
|
|
|
|
TODO: remind key usages / basic constraints to generate valid certificates for OPC UA usage
|
|
|
|
|
|
### Basic examples of valid organization for you certificates
|
|
|
|
|
|
TODO: graphical presentation of self-signed certificate, trusted CA-signed certificate, untrusted CA-signed certificate (trusted), + same with intermediate CA ?
|
|
|
|
|
|
## Configure the certificate validation management in S2OPC
|
|
|
|
|
|
In order to activate secure communication 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 `csrc/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 4 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. These certificates are considered themselves trustworthy (if the certificate properties and its signature are both valid).
|
|
|
* The "untrusted issuers" are CAs that 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.
|
|
|
|
|
|
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 the order child to parent).
|
|
|
* 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, it's 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_config.xsd`).
|
|
|
The XML configuration can be used to automatically configure the S2OPC demo server (see [Start S2OPC demo server wiki](https://gitlab.com/systerel/S2OPC/-/wikis/demo#start-opc-ua-demo-server))
|
|
|
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:
|
|
|
```xml
|
|
|
<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):
|
|
|
```xml
|
|
|
<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/myCompanyCA.der"
|
|
|
revocation_list_path="/certs/PKI/revoked/myCompanyCRL.der"/>
|
|
|
</TrustedIssuers>
|
|
|
</ApplicationCertificates>
|
|
|
```
|
|
|
Note 1: Intermediate CAs (non root CA) shall be provided in the order child to parent, 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:
|
|
|
```xml
|
|
|
<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:
|
|
|
```xml
|
|
|
<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>
|
|
|
<UntrustedIssuers>
|
|
|
<!-- Intermediate CAs shall be provided in the order child to parent -->
|
|
|
<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"/>
|
|
|
</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](/GettingStarted).
|
|
|
|
|
|
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). |
|
|
\ No newline at end of file |