... | ... | @@ -3,115 +3,117 @@ |
|
|
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.
|
|
|
## PKI provider principles
|
|
|
|
|
|
## Default PKI provider principles
|
|
|
|
|
|
The PKI verifies a certificate in the safest manner (whole certificate chain, with date validation, mandatory certificate revocation lists).
|
|
|
The PKI verifies a certificate in the safest manner (whole certificate chain, with date validation, key usages, 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.
|
|
|
There are 4 lists of certificates to provide to the PKI:
|
|
|
* The **"trusted certificates"** are the certificates and Certificate Authorities (CAs) which are trusted.
|
|
|
* The **"trusted crls"** are the Certificate Revocation Lists (CRLs) for the Certificate Authorities (CAs) in the "trusted certificates" list.
|
|
|
* The **"issuer certificates"** are the Certificate Authorities (CAs) which are used to verify the signing chain but certificates in this list are considered untrusted.
|
|
|
* The **"issuer crls"** are the Certificate Revocation Lists (CRLs) for the certificates in the "issuer certificates" list.
|
|
|
In OPC UA, these 4 lists are known as the the "trustList".
|
|
|
|
|
|
*Note 1: a certificate chain is an ordered-list of certificate from the end-entity to a root Certificate Authorities (self-signed CA). The order is made up by signatures (trace back to the root CA).*
|
|
|
|
|
|
*Note 2: an end-entity certificate is considered valid by the PKI, if the whole certificate chain is valid (signature + OPC UA security policy properties) and if at least one certificate in the chain is include in the "trusted certificates" list.*
|
|
|
|
|
|
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 3: each CA shall be provided with an associated Certificate Revocation List (CRL). An end-entity certificate will not be considered valid by the PKI, if an issuer in the signature chain does not have at least one associated CRL.*
|
|
|
|
|
|
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 4: an end-entity certificate don't need to be provided to the "trusted certificates" if the PKI includes the certificates which are necessary to validate the end-entity (at least one trusted, see details at Note 2 above).*
|
|
|
|
|
|
Note 3: certificates issued by trusted CA don't need to be provided to the PKI.
|
|
|
*Note 5: self-signed end-entity certificates which are not include in the "trusted certificates" are not considered valid by the PKI.*
|
|
|
|
|
|
Note 4: unknown self-signed certificates are not trustworthy.
|
|
|
*Note 7: an end-entity certificate could be a root CA for backward interoperability but it shall be include in the "trusted certificates" list (Note 5)*
|
|
|
|
|
|
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.
|
|
|
*Note 6: if an end-entity 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/revoked.*
|
|
|
|
|
|
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.
|
|
|
**Warning:** The creation of the PKI at the server startup works on the assumption that the user has correctly configured the four lists presented above. For instance if a CA is supplied without a CRL, validation will fail for certificates issued by this CA, as the chain does not complied with the OPC UA CRL requirement.
|
|
|
|
|
|
## Use server XML configuration to configure the PKI
|
|
|
## Use client/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](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.
|
|
|
In order to configure the certificates provided to the PKI it is possible to use the S2OPC client/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](https://gitlab.com/systerel/S2OPC/-/wikis/demo#start-opc-ua-demo-server)) or to generate a fulfilled `SOPC_Client_Config` or `SOPC_Server_Config` structures to configure your own application 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:
|
|
|
The XML configuration simply requires the directory store path of the PKI, example for server:
|
|
|
```xml
|
|
|
<ApplicationCertificates>
|
|
|
<ServerCertificate path="/certs/server/my_server_cert.der"/>
|
|
|
<ServerKey path="/cert/server/my_server_key/my_server_key.pem" encrypted=true/>
|
|
|
<TrustedIssuers>
|
|
|
<TrustedIssuer root="true" cert_path="/certs/PKI/trusted/myCompanyCA.der"
|
|
|
revocation_list_path="/certs/PKI/revoked/myCompanyCRL.der"/>
|
|
|
</TrustedIssuers>
|
|
|
<ServerKey path="/cert/server/my_server_key/my_encrypted_server_key.pem" encrypted="true"/>
|
|
|
<ServerPublicKeyInfrastructure path="./my_server_pki_store"/>
|
|
|
</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):
|
|
|
or for client:
|
|
|
```xml
|
|
|
<ApplicationCertificates>
|
|
|
<ServerCertificate path="/certs/server/my_server_cert.der"/>
|
|
|
<ServerKey path="/cert/server/my_server_key/my_server_key.pem" encrypted=true/>
|
|
|
<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>
|
|
|
<ApplicationCertificates>
|
|
|
<ClientCertificate path="/certs/client/my_client_cert.der"/>
|
|
|
<ClientKey path="/cert/client/my_client_key/my_encrypted_client_key.pem" encrypted="true"/>
|
|
|
<ClientPublicKeyInfrastructure path="./my_client_pki_store"/>
|
|
|
</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:
|
|
|
The directory store shall be organized as follows:
|
|
|
```xml
|
|
|
<ApplicationCertificates>
|
|
|
<ServerCertificate path="/certs/server/my_server_cert.der"/>
|
|
|
<ServerKey path="/cert/server/my_server_key/my_server_key.pem" encrypted=true/>
|
|
|
<IssuedCertificates>
|
|
|
<IssuedCertificate path="/certs/issued/myClient1CA.der"/>
|
|
|
<IssuedCertificate path="/certs/issued/myClient2CA.der"/>
|
|
|
</IssuedCertificates>
|
|
|
</ApplicationCertificates>
|
|
|
.
|
|
|
|
|
|
|
---- <Directory_store_name>
|
|
|
|
|
|
|
|---- trusted
|
|
|
| |
|
|
|
| ---- certs
|
|
|
| ---- crl
|
|
|
|---- issuers
|
|
|
| |
|
|
|
| ---- certs
|
|
|
| ---- crl
|
|
|
|---- (rejected) [created during runtime if requested]
|
|
|
|
|
|
|
---- (updatedTrustList) [automatically created for runtime update persistence]
|
|
|
| |
|
|
|
| ---- trusted
|
|
|
| | |
|
|
|
| | ---- certs
|
|
|
| | ---- crl
|
|
|
| ---- issuers
|
|
|
| |
|
|
|
| ---- certs
|
|
|
| ---- crl
|
|
|
```
|
|
|
|
|
|
* 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:
|
|
|
When first commissioning the device, the administrator shall configure the **trusted** and **issuers** folder beforehand as follows:
|
|
|
* **trusted/certs:** with the "trusted certificates"
|
|
|
* **trusted/crl:** with the CRLs for the CA of the "trusted certificates"
|
|
|
* **issuers/certs:** with the "issuer certificates" (shall be filled with CAs only)
|
|
|
* **issuers/crl:** with the CRLs for the "issuer certificates"
|
|
|
|
|
|
When first commissioning the device, the **updatedTrustList** and **rejected** folders shall not exist.
|
|
|
|
|
|
At startup, the PKI always tries to build from the **updatedTrustList** folder, which is missing if no update was performed during the last server run.
|
|
|
When **updatedTrustList** is missing or when an unexpected error has occurred then the PKI switches to the default **trusted** and **issuers** folders configured by the administrator beforehand.
|
|
|
The **rejected** folder contains certificates which have failed to connect, and is created or refreshed when requested by the application.
|
|
|
|
|
|
## Use users XML configuration to configure the PKI for x509IdentityToken
|
|
|
|
|
|
The x509 certificates can be used as user credentials for sessions (authentication and authorization). To configure the associated PKI, it is possible to use the S2OPC users XML configuration format (`schemas/s2opc_clientserver_users_config.xsd`).
|
|
|
XML configuration requires the directory store path of the PKI plus the user rights for valid certificates, example:
|
|
|
|
|
|
```xml
|
|
|
<ApplicationCertificates>
|
|
|
<ServerCertificate path="/certs/server/my_server_cert.der"/>
|
|
|
<ServerKey path="/cert/server/my_server_key/my_server_key.pem" encrypted=true/>
|
|
|
<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>
|
|
|
<UserCertificates>
|
|
|
<PublicKeyInfrastructure path="./my_user_pki" write="false" read="true" execute="false" addnode="false"/> <!-- default right for all valid certificates -->
|
|
|
<UserCertificateRights path="user/my_specific_user.der" write="true" read="true" execute="true" addnode="true"/> <!-- overwrite the default right for a specific certificate -->
|
|
|
</UserCertificates>
|
|
|
```
|
|
|
|
|
|
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.
|
|
|
If you implement your own server, client or UserManager based on S2OPC toolkit you will need to instantiate PKI using the function `SOPC_PKIProvider_CreateFromStore`. The parameters content is the same as described for XML above and those can be instantiated from the XML itself on client/server and for user credentials.
|
|
|
|
|
|
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).
|
|
|
It is also possible to use function `SOPC_PKIProvider_CreateFromList` to create the PKI from already parsed certificates.
|
|
|
PKI certificates can be dynamically and persistently updated in memory by using `SOPC_PKIProvider_UpdateFromList` and `SOPC_PKIProvider_WriteToStore`.
|
|
|
|
|
|
## Certificates and keys generation
|
|
|
|
... | ... | @@ -128,5 +130,7 @@ The script `generate_certs.sh` can be used to generate new keys and can be modif |
|
|
- AES-192-CBC
|
|
|
- AES-256-CBC
|
|
|
|
|
|
Same process for user certificates (files: `generate_user_certs.sh` and `usr_req.cnf`) and for certificates signed by an an intermediate CA (files: `./intermediate/generate_int_certs.sh`, `./intermediate/srv_req.cnf` and `./intermediate/cli_req.cnf`).
|
|
|
|
|
|
![Analytics](https://systerel-ga-beacon.appspot.com/UA-1802741-3/wiki/home?pixel&useReferer)
|
|
|
![Matomo](https://analytics.systerel.fr/matomo.php?idsite=5&rec=1&action_name=wiki/certificates+configuration) |
|
|
\ No newline at end of file |