High Performance OPC UA Server SDK
UA Certificate Manager

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.

Command Line Options

Like all good command line tools it has a built-in help which can be used to find out about the available options.

Usage: ./uacertmgr [ options ] command [ command args ]
-c: config file to load (default='settings.conf')
-s: store index as defined in settings.conf (default=0)
-n: optional name for import-own
-h: print this help and exit
-V: print version information
list [ location ] List certificates.
show [ location ] <sha1> Show certificate details.
dump <cert> Dump DER certificate file content (like show, but with file
as input data).
import [ location ] <cert> [ <crl> ] Import certificate (*.der/pem) and optionally a CRL (*.crl)
import-own <cert> <key> Import own certificate (*.der/pem) and private key (*.pem).
import-tree <dir> Import a complete PKI tree.
import-crl [ location ] <crl> Import a CRL (Certificate Revocation List). The according
certificate must be already in the store. Use 'auto' as
location to find out the certificate location automatically.
update-crl [ location ] <crl> Update a CRL. The CRL must exist already.
delete [ location ] <sha1> Delete a certificate and its CRL (if it exists).
delete-crl [ location ] <sha1> Delete a CRL. Use 'auto' as location to find out the
certificate location automatically.
trust <sha1> | <index> Trust a rejected certificate. You can identify the
certificate either by its SHA1 or by the list index shown in
`uacertmgr list rejected`.
reset [-f] Recreates the complete PKI store. All settings will be lost!
Location: 'trusted', 'issuers', 'rejected', or 'own' (default=trusted)

Note on File Formats

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.


# 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.

Getting Started

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").

$> ./uacertmgr -n server4k import-own server.der server.pem

You can find out the certificate id by invoking the list command.

$> ./uacertmgr list own

To print the certificate details use the show command.

$> ./uacertmgr show own 1234

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'.

$> ./uacertmgr import trusted rootCA.der

Normally you should also get a CRL with the CA certificate that needs to be imported too.

$> ./uacertmgr import-crl trusted rootCA.crl

Alternatively, you can also perform both steps at once using the import command.

$> ./uacertmgr import trusted rootCA.der rootCA.crl

Deleting Certificates

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.

$> ./uacertmgr delete trusted 12345

Revoking Certificates

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.

$> ./uacertmgr update-crl trusted rootCA.crl

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.

Trusting Rejected Certificates

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.

$> ./uacertmgr list rejected
List all certificates:
Idx SHA1 Certificate Id Common Name Application URI Key Type Key Size
[0] C4D35C1536E208F1463BF84EC2977C65866F3ACC UaExpert@ws-demo urn:ws-demo:UnifiedAutomation:UaExpert RSA Public Key 2048
$> ./uacertmgr show C4D35C1536E208F1463BF84EC2977C65866F3ACC
Certificate details of C4D35C1536E208F1463BF84EC2977C65866F3ACC:
Application URI: urn:ws-demo:UnifiedAutomation:UaExpert
IP Address:
DNS: ws-demo
Valid From: 2017-11-07T17:39:23
Valid Till: 2022-11-06T17:39:23
Serial: 5A01EFCB
Key Usage: 0x0
Common Name: UaExpert@ws-demo
Organization: a
Organization Unit: a
Locality: a
State: a
Country: DE
Common Name: UaExpert@ws-demo
Organization: a
Organization Unit: a
Locality: a
State: a
Country: DE
Public Key:
Key Type: RSA Public Key
Key Length: 2048
$> ./uacertmgr trust C4D35C1536E208F1463BF84EC2977C65866F3ACC
The certificate 'C4D35C1536E208F1463BF84EC2977C65866F3ACC' is now trusted.

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.

Importing PKI Hierarchies

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.

$> ./uacertmgr import-tree /path/to/uactt/ServerProjects/PKI/copyToServer/ApplicationInstance_PKI

Import User Certificates

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.

$> ./uacertmgr -s1 import joe.der

Example: Importing a CA certificate and the according CRL for user authentication.

$> ./uacertmgr -s1 import rootCA.der rootCA.crl

Resetting the PKI Store

By resetting a PKI store all contained data (certificates, CRLs, private keys) will be deleted and the PKI store folders will be recreated.

$> ./uacertmgr reset
Do you really want to reset the PKI store 0? All certificates and private keys will be lost!
Enter "YES" to continue: YES
The PKI store was resetted successfully.

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.

$> ./uacertmgr reset -f
The PKI store was resetted successfully.