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 ]
Options:
  -c: config file to load (default='settings.conf')
  -s: store index as defined in settings.conf (default=0)
  -h: print this help and exit
  -V: print version information
Commands:
  list        [ location ]                    List certificates.
  show        [ location ] <sha1>             Show certificate details.
  import      [ location ] <cert> [ <crl> ]   Import certificate (*.der) and optionally a CRL (*.crl)
  import-own  <cert> <key>                    Import own certificate (*.der) and private key (*.pem).
  import-tree [ location ] <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>                          Trust a rejected certificate.
  reset                                       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.

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

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.

$> ./uacertmgr 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
 E-Mail:
 Valid From:         2017-11-07T17:39:23
 Valid Till:         2022-11-06T17:39:23
 Serial:             5A01EFCB
 Key Usage:          0x0
Subject:
 Common Name:        UaExpert@ws-demo
 Organization:       a
 Organization Unit:  a
 Locality:           a
 State:              a
 Country:            DE
Issuer:
 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

Table of Contents