 |
High Performance OPC UA Server SDK
1.7.1.383
|
|
High Performance OPC UA Server SDK
1.7.1.383
|
The tool uacertmgr is a command line program which can be used to manage PKI stores. The source code serves also as an example on how to use the PKI store API and can be found in src/tools/uacertmgr.
Important: You should not modify the PKI folders manually unless you know exactly what you are doing. It is recommended to always use the uacertmgr tool to edit PKI stores, or to use a GDS server to remotely manage the UA server.
Like all good command line tools it has a built-in help which can be used to find out about the available options.
The UA SDK uses DER encoded certificates and CRLs as required by the OPC UA protocol. Only the private keys are stored as PEM encoded RSA private keys. Private keys are never sent over the network, so the actual encoding is only relevant for the application itself. Using OpenSSL those keys are typically stored in PKCS5 format.
Certificates and CRLs can be converted to DER format using the OpenSSL commandline tool.
Examples:
# convert certificate from PEM to DER openssl x509 -in rootCA.pem -outform der -out rootCA.der # convert CRL from PEM to DER openssl crl -in rootCA.crl.pem -outform der -out rootCA.crl
Since V1.6.0 uacertmgr can also import PEM encoded certificates. The tool automatically converts PEM encoded certificates to DER when importing them. This works for the commands import, import-own and import-tree.
When started the first time and the PKI store does not exist it will create it in the same way as the demo servers do. Therefor it loads the same settings.conf file by default. If you want to use a different configuration file you can do so using the option -c.
One of the first things you normally want to do is importing the own server certificate (if not using the self-signed test certificates) and importing one ore more CA certificates into the trust list. You may specify the name of the certificate and key with the '-n' option. The name is used in the "certificates" section in the settings file (e.g. "certificates/0/certificate = store://server4k").
You can find out the certificate id by invoking the list command.
To print the certificate details use the show command.
Now to import a CA certificate into the trust list use the import command again, but this time with 'trusted' as the location. You can also omit the location, because the default value is 'trusted'.
Normally you should also get a CRL with the CA certificate that needs to be imported too.
Alternatively, you can also perform both steps at once using the import command.
To remove trusted certificates you can use the delete command. You first need to find out the certificates SHA1 id using the list command. Then you can delete the certificate and the according CRL using the delete command.
The process of revoking a certificate can actually only be done by the CA which is issued the certificate. But you need to update the CRL in the PKI store to make this change effective. How you get this update CRL is another story. OPC UA GDS is one good option for this.
Assuming you have already imported the CRL as shown above you can update the CRL with newer versions this way.
Note that this will only work if the CRL already exists and the new CRL is newer than the existing one. CRLs are cryptographically signed by the CA, so that they are tamper proof. Also, installing older versions of a CRL is not allowed, because this could activate a revoked certificate again.
One feature of OPC UA is that rejected certificates are stored in the rejected folder inside the PKI store. This way self-signed certificates of clients can be easily trusted without the need of copying them manually to the server. The trust command can be used for this. But before you trust a certificate SHOULD inspect the certificate details and compare the certificate thumbprint.
Comparing the certificate thumbprint. The client that wants to connect must tell you the certificate thumbprint, which is the same as the SHA1 id used by uacertmgr. On Windows you can find out this thumbprint by opening the certificate by double clicking, selecting the 'Details' tab and scroll down until you find the 'thumbprint' field. On Linux you can simply call sha1sum <file> to calculate this thumbprint.
There might be situations where you want to import complete PKI hierarchies into the server. One example for this is using the UA Compliance Test Tool. This tool requires a certain PKI setup to be able to perform the tests. To simplify the configuration the latest version of the UA CTT can generate a complete PKI folder hierarchy, but the files are not name as expected by the UA High Performance SDK, which expected SHA1 ids as filenames. Using the uacertmgr you can import such hierarchies in one command.
User certificates are store in a separate PKI store. By default this is the second store. So when importing a self-signed user certificate or a CA certificate for user authentication, then you need to select the correct PKI store, because the default is store index 0, which is the store for application instance certificates.
Example: Importing the self-signed user certificate for Joe.
Example: Importing a CA certificate and the according CRL for user authentication.
By resetting a PKI store all contained data (certificates, CRLs, private keys) will be deleted and the PKI store folders will be recreated.
Because this is a dangerous operation, that should not be triggered accidentally you must confirm the operation by typing "YES" in capital letters. You can avoid this prompt by using the option -f to force deletion.