Configuring SSL connections

If the OPC UA server is using a Secure Socket Layer (SSL) connection to encrypt data exchanged over JMS and HTTP, you will need to configure the truststore for the HTTPS connection on the Tivoli Netcool/OMNIbus probe server. This is the server on which the probe is running.

Summary of SSL configuration

The SSL configuration requires that you perform some tasks on the OPC Unified Architecture (UA) server and some tasks on the Tivoli Netcool/OMNIbus probe server. The following list summarizes these tasks:

On the OPC UA server:
- Obtain the OPC UA server security certificate from the certificate authority (CA) or use a self-signed certificate.
- Import the CA or self-signed certificate into the server truststore.
- Export the server truststore (which contains the CA or self-signed certificate) into a certificate file that can be handed to the client (probe).
- Or, export the OPC UA server keystore file.
On the Tivoli Netcool/OMNIbus probe server (client):
- Import the OPC UA server security certificate or import the OPC UA server keystore file.
- Verify either the OPC UA server security certificate or the OPC UA server keystore file.
- Configure the probe either for one-way SSL connection or for two-way SSL connection.
Note: You can obtain the probe server (client) security certificate from the CA and use it directly in SSL configuration. Or, you can create a client truststore/keystore that includes the CA security certificate. You use the keytool utility to create a truststore that includes the CA certificate or you can import the CA certificate into an existing truststore.

Performing SSL configuration on the OPC UA server

To perform SSL configuration on the OPC UA server, use the following steps:

Note: For more details about configuring SSL security for the OPC UA server (including instructions about obtaining certificate files), refer to your vendor server's SSL configuration guide.

Either obtain the OPC UA server security certificate from the certificate authority (CA) or use a self-signed certificate.
Import the CA or self-signed certificate into the server truststore.
If you have the appropriate user access, export the OPC UA server truststore into a certificate file on the OPC UA server that can be handed to the client (probe). To export the OPC UA server keystore file into a certificate file on the OPC UA server, use the following command:
```
 
./keytool -export -alias alias_name -keystore keystore_file -storepass 
password -file certificate_file
 
```
Where:

alias_name - Specifies the keystore alias specified during OPC UA server keystore generation, for example: OPCUA.

keystore_file - Specifies the path to and name of the OPC UA server keystore file, for example: /opt/opcuaserver/opcua.keystore .

password - Specifies the OPC UA server keystore password, for example: the password of opcua.keystore.

certificate_file - Specifies the path to and name of the certificate file to be created, for example: /opt/opcuacert/opcuaprobecert.

Performing SSL configuration on the probe server

Note: You should now have an OPC UA server certificate file that resides on the OPC UA server. You will import the OPC UA server certificate file as part of the SSL configuration on the probe server.

To perform SSL configuration on the probe server, use the following steps:

Import the OPC UA server certificate file either into an existing truststore or into a new truststore.
1. To import the OPC UA server certificate file into an existing truststore, you need to point an alias to a key entry as the certificate reply. The alias must be the same as that specified during OPC UA server keystore file generation, for example:
```
 
 ./keytool -import -trustcacerts -alias alias_name -file certificate_file
 -keystore truststore_file -storepass password
```
2. To import the OPC UA server certificate file into a new truststore, make sure that the alias that you specify does not already exist in your truststore, for example:
```
 
./keytool -import -trustcacerts -alias new_alias_name -file 
certificate_file -keystore truststore_file -storepass password
 
```
  In the preceding examples (Step 1a and Step 1b):
  
  alias_name - Is the keystore alias specified during OPC UA server keystore generation, for example: OPCUA.
  
  new_alias_name - Specifies the keystore alias of a new keystore, for example: opcuaprobe.
  
  certificate_file - Specifies the path to and name of the certificate file created on the OPC UA server, for example: /opt/opcuacert/opcuaprobecert.
  
  truststore_file - Specifies the path to and name of the truststore file on the Tivoli Netcool/OMNIbus probe server that will contain the imported certificate, for example: /opt/tivoli/opcuaprobe.truststore .
  
  password - Specifies the OPC UA server keystore password, for example: the password of opcuaserver.truststore.
Verify that the certificate has been imported into the keystore using the following command:
```
 
./keytool -list -v -keystore truststore_file
```
Where:

truststore_file - Specifies the path to and name of the truststore file generated on the probe server, for example: /opt/tivoli/opcuaprobe.truststore.

Configuring the probe for one-way SSL connection

To configure the probe to connect to the OPC UA server using a one-way SSL connection, use the following steps:

Note: A one-way SSL connection does not require client authentication. For a one-way SSL connection, you configure the EnableSSL property and the truststore related properties (TrustStore, TrustStorePassword, and TrustStoreType).

Set the probe's EnableSSL property to true and configure the probe's EndpointHttpPort property to your OPC UA server's HTTPS port. You can use any valid HTTPS port based on your OPC UA server configuration.
Specify values for the following probe properties:
- TrustStore - Specify the path of the probe's keystore that you created in the steps for importing the certificate, for example: /opt/opcua.trustStore.
- TrustStorePassword - Specify the password that you set for the specified keystore in the TrustStore property.
- TrustStoreType - Specify the truststore type obtained from the truststore. For example, JKS (Java Keystore).
  Note: TrustStoreType has a default value of JKS (which represents Java Keystore). If you are using another type such as .pfx, then configure the TrustStoreType to the value PKCS12.

Configuring the probe for two-way SSL connection

To configure the probe to connect to the OPC UA server using a two-way SSL connection, use the following steps:

Note: A two-way SSL connection requires client authentication. This type of SSL connection is often referred to as required client authentication. For a two-way SSL connection, you configure the EnableSSL property, the truststore related properties (TrustStore, TrustStorePassword, and TrustStoreType), and the keystore related properties (KeyStore, KeyStorePassword, and KeyStoreType).

Set the probe's EnableSSL property to true and configure the probe's EndpointHttpPort property to use the default OPC UA server HTTPS port, 51511.
Note: You can use any valid HTTPS port based on your OPC UA server configuration. For the OPC Foundation sample application (the sample server) the default HTTPS port is 51212.
Create a keystore on the Tivoli Netcool/OMNIbus probe server. Specify values appropriate to your environment for the following properties:
- TrustStore - Specify the path of the probe's keystore that you created in the steps for importing the certificate, for example: /opt/opcua.trustStore.
- TrustStoreType - Specify the truststore type obtained from the truststore. For example, JKS (Java Keystore).
  Note: TrustStoreType has a default value of JKS (which represents Java Keystore). If you are using another type such as .pfx, then configure the TrustStoreType to the value PKCS12.
- TrustStorePassword - Specify the password that you set for the specified keystore in the TrustStore property.
- KeyStore - Specify the path of the probe's keystore that you created in the steps for importing the client certificate if client authentication is required. For example, /opt/opcua.trustStore (if the client certificate was imported there), or /opt/opcua.keyStore (if the client certificate is a separate keystore).
- KeyStoreType - Specify the keystore type obtained from the keystore. For example, JKS (Java Keystore).
  Note: KeyStoreType has a default value of JKS. If you are using another type such as .pfx, then configure the KeyStoreType to the value PKCS12.
- KeyStorePassword: Specify the password that you set for the specified keystore in the KeyStore property.

Example one-way SSL configuration property settings

The following example shows SSL configuration settings from the properties file of an example Probe for OPC UA for one-way SSL. Replace the sample values with those appropriate to your environment.

EndpointHttpHost          : "localhost"
EndpointHttpPort          : 51511
EnableSSL                 : "true"
TrustStore                  : 	"/opt/opcua.trustStore"
TrustStorePassword          : "newpassword"

Example two-way SSL configuration property settings

The following example shows SSL configuration settings from the properties file of an example Probe for OPC UA for two-way SSL. This example shows that the keystore property related values reuse the values specified for the truststore related property values. Replace the sample values with those appropriate to your environment.

EndpointHttpHost          : "localhost"
EndpointHttpPort          : 51511
EnableSSL                 : "true"
TrustStore : "/opt/opcua.trustStore"
TrustStorePassword : "newpassword"
TrustStoreType : "JKS"
KeyStore : "/opt/opcua.trustStore"
KeyStore Password : "newpassword"
KeyStore Type : "JKS"

The following example shows SSL configuration settings from the properties file of an example Probe for OPC UA for two-way SSL. This example shows that the keystore property related values (except for the type) are different from the values specified for the truststore related property values. Replace the sample values with those appropriate to your environment.

EndpointHttpHost          : "localhost"
EndpointHttpPort          : 51511
EnableSSL                 : "true"
TrustStore : "/opt/opcua.trustStore"
TrustStorePassword : "newpassword"
TrustStoreType : "JKS"
KeyStore : "/opt/opcua.keyStore"
KeyStore Password : "keypassword"
KeyStore Type : "JKS"