Securing the example connector

In a production deployment, you must configure your connectors with client-authenticated SSL communication. You can configure the example connector to communicate with i2 Analyze by using client-authenticated SSL communication.

You must configure your connectors to use client-authenticated SSL communication with i2 Analyze. For more information about configuring security between connectors and i2 Analyze, see Client authenticated Secure Sockets Layer with the i2 Connect gateway.

Configure secure communication between Liberty and the example connector that is provided with i2 Analyze. The following steps demonstrate how to create the keystores, truststores, and certificates, then configure i2 Analyze and the example connector to use them.

When you create your own connector, you can implement the security implementation in the same way as used in the example connector, or a different method depending on your requirements.

In a production deployment, you must use a certificate that has been signed by a trusted certificate authority, which the connector can verify. The following steps use a self-signed certificate to demonstrate the functionality.

Create a keystore for Liberty that contains a signed certificate that is used to authenticate with the connector.

Create a keystore and a self-signed certificate for Liberty by using the Java keytool utility.
For more information about the Java keytool utility, see keytool - Key and Certificate Management Tool.
1. Open a command prompt and navigate to the i2analyze\deploy\java\bin directory.
2. Create the keystore and certificate by running the following command:
```
keytool -genkeypair -alias "libertyKey"
-keystore "C:\i2\i2analyze\i2-liberty-keystore.jks"
-dname "CN=hostname" -keyalg RSA -storepass "libertyKeyStorePassword"
```
  Important: Ensure that you enter values as follows:
  - Set the location of the keystore to the directory that contains the toolkit.
  - Set the value of CN to the hostname of the server that hosts Liberty, as defined in the topology.xml file.
  The password that is specified is used to access the keystore.
3. The example connector implementation requires the Liberty certificate in a base64 encoded format. Export the certificate in base64 encoding by running the following command:
```
keytool -exportcert -alias "libertyKey"
-keystore "C:\i2\i2analyze\i2-liberty-keystore.jks"
-file "C:\i2\i2analyze\i2-liberty-certificate.cer"
-rfc -storepass "libertyKeyStorePassword"
```

Create a keystore for the connector that contains a signed certificate that is used to authenticate with Liberty.

Create a keystore and certificate for the connector by using the IBM Key Management Utility command-line interface.
For more information about the IBM Key Management Utility, see Key Management Utility command-line interface (gskcmd) syntax.
1. In a command prompt, navigate to the bin directory of your IBM HTTP Server installation. For example: IBM\HTTPServer\bin or IBM\HTTPServer\IHS\bin.
2. Create a keystore in PKCS12 format. To create the keystore, run the following command:
```
gskcapicmd -keydb -create -type pkcs12
 -db "C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-keystore.p12"
 -pw "connectorKeyStorePassword"
```
  The password that is specified is used to access the keystore.
3. Create a self-signed certificate by running the following command:
```
gskcapicmd -cert -create
 -db "C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-keystore.p12"
 -label "connectorKey" -dn "CN=hostname" -pw "connectorKeyStorePassword"
```
  Important: Set the value of CN to the hostname of the server that hosts the connector, as defined in the topology.xml file. By default in the daod-opal example configuration, the value is localhost.

The example connector implementation requires the private key in the PEM format, and the certificate for the connector.

Export the personal certificate and private key into a PKCS12 file by running the following command:

gskcapicmd -cert -export
 -db "C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-keystore.p12"
 -pw "connectorKeyStorePassword" -label "connectorKey" -type pkcs12
 -target "C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-key.p12"
 -target_pw "connectorKeyPassword" -target_type pkcs12

Convert the private key from the PKCS12 format to the PEM format. You can use OpenSSL to do this. For more information about OpenSSL see https://www.openssl.org/source/. If you are using OpenSSL, you can run the following command:
```
openssl pkcs12 -in C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-key.p12
-out C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-key.pem
-nocerts -nodes
```
When you are prompted for a password, provide the password that you specified when you created the example-connector-key.p12 PKCS12 file. In this example, enter connectorKeyPassword.

Extract the certificate for the connector by running the following command:

gskcapicmd -cert -extract
-db "C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-keystore.p12"
-label "connectorKey"
-target "C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-certificate.cer"
-pw "connectorKeyStorePassword"

Create a truststore for Liberty that contains the certificate that is used to trust the certificate that it receives from the connector.

Create the Liberty truststore and populate it with the connector's certificate by using the Java keytool by running the following command:

keytool -importcert -alias "exampleconnector"
-keystore "C:\i2\i2analyze\i2-liberty-truststore.jks"
-file "C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-certificate.cer"
-storepass "libertyTrustStorePassword"

In response to the prompt, enter yes to trust the certificate.

Populate the connector keystore with Liberty's certificate by using the IBM Key Management Utility by running the following command:

gskcapicmd -cert -add -type pkcs12
-db "C:\i2\i2analyze\toolkit\examples\connectors\example-connector\example-connector-keystore.p12"
-pw "connectorKeyStorePassword" -label "libertyKey" -trust enable
-file "C:\i2\i2analyze\i2-liberty-certificate.cer"

The example connector implementation requires the certificate that is used to trust Liberty to also be present in the example-connector directory. Copy the C:\i2\i2analyze\i2-liberty-certificate.cer file to the C:\i2\i2analyze\toolkit\examples\connectors\example-connector directory.
If you are using the IBM HTTP Server, start or restart it.

The certificates are now in place to enable client authentication SSL between Liberty and the connector.

Configure the example connector to reference the certificates that you created, and the hostname of the gateway. Using a text editor, modify the security-config.json file with the following values.

https

Set to true to use the HTTPS protocol to connect to the connector.

keyFileName

The file name for the private key of the connector in PEM format. For this example, example-connector-key.pem.

keyPassphrase

The password that is required to access the key file specified in keyFileName. For this example, connectorKeyPassword.

certificateFileName

The file name for the certificate of the connector. For this example, example-connector-certificate.cer.

certificateAuthorityFileName

The file name of the certificate that enables trust of the certificate that is received from Liberty. For this example, i2-liberty-certificate.cer.

gatewayCN

The common name of the gateway. This must be the value of the common name in the certificate the connector receives from Liberty. You specified the value of the CN in the certificate in step 1.

Configure Liberty to use the keystore and truststore that you created.

In an XML editor, open the toolkit\configuration\environment\topology.xml file.
1. Add the <key-stores> element as a child of the <application> element. Then, add child <key-store> elements.
  For your keystore, specify the type as key-store, and file as the full path to your keystore. For your truststore, specify the type as trust-store, and file as the full path to your truststore.
  For example, add the attribute as highlighted in the following code:
```
<application http-server-host="true"
  name="opal-server" host-name="hostname">
...
    <key-stores>
        <key-store type="key-store"
          file="C:/i2/i2analyze/i2-liberty-keystore.jks"/>
        <key-store type="trust-store"
          file="C:/i2/i2analyze/i2-liberty-truststore.jks"/>
    </key-stores>
...
</application>
```
2. Update the base-url attribute of any connectors using SSL to use the HTTPS protocol.
  For example:
```
<connectors>
    <connector id="example-connector" name="Example" 
      base-url="https://localhost:3700/" />
</connector>
```
Note: Ensure that the hostname that is used in the base URL matches the common name on the certificate of the connector.
Specify the keystore and truststore passwords in the credentials file.
1. In a text editor, open the toolkit\configuration\environment\credentials.properties file.
2. Enter the password for the keystore and truststore that you specified in the topology.xml file.
```
ssl.truststore.password=libertyTrustStorePassword
ssl.keystore.password=libertyKeyStorePassword
```
In a command prompt, navigate to the toolkit\scripts directory.
Update the i2 Analyze application:
```
setup -t deployLiberty
```
Start the example connector.
1. In a new command prompt, navigate to the toolkit\examples\connectors\example-connector directory.
2. To start the Node.js server, run the following command:
```
npm start
```
  Note: The example connector uses port number 3700. Ensure that no other processes are using this port number before you start the connector.
Start Liberty:
```
setup -t startLiberty
```
If you are using the IBM HTTP Server, start or restart it.

Use Analyst's Notebook Premium to connect to your deployment. For more information, see Connecting i2 Analyst's Notebook Premium to i2 Analyze.

Now that the example connector is configured for SSL, no warnings are displayed in Analyst's Notebook Premium.