Enabling client-to-node encryption and authentication for ZooKeeper

Client-to-node encryption protects data in the cluster against access from users without encryption keys. Client-to-node encryption is disabled by default and must be explicitly enabled with the keys in the keystore. When client-to-node encryption is enabled, client authentication is also enabled. When client authentication is enabled on the zookeeper cluster, a zookeeper server only allows connections from clients that present a personal certificate that is trusted by the server.

Before you begin

Set up a keystore on each ZooKeeper server in the local data center. Each ZooKeeper server must have a keystore containing a key-certificate (private key + public certificate). The key-certificate can be self-signed or signed by a certificate authority (CA). Complete Generating a self-signed personal certificate.

About this task

To set up client-to-node encryption and authentication:

Procedure

Log in to the ZooKeeper server as the user who installed Sterling B2B Integrator and Global Mailbox.
Add each server certificate to each other server truststore using the Java keytool command to import the certificate of every server into each server truststore.
```
-keytool -importcert -alias <name> -file <path to cert file> -keystore <path to truststore> -storepass <password> -storetype JKS
```
Where,
- -alias <name>: Alias can be anything that does not exist in the truststore. It might be a descriptive label, such as server 1.
- -file <path to cert file>: Specifies the fully-qualified path to the file where the server public certificate is exported when its personal certificate was created in Generating a self-signed personal certificate.
- -keystore <path to truststore>: Specifies the fully-qualified path of the server truststore file. For example, /etc/zookeeper/ssl/keystore.jks.
- -storepass <password>: The truststore password specifies the password of the server truststore file.
- -storetype JKS: The keystore type must be JKS.
Copy the truststore file (contains all servers certificates) created in the Step 2 to the following path on each datacenter: <StoragePath>/config/<truststore file>
Create self-signed certificates for client authentication.

Use the Java™ keytool utility that is provided in the IBM JDK to generate a self-signed certificate on every Sterling B2B Integrator and Global Mailbox node. Each Sterling B2B Integrator and Global Mailbox node will use a separate key to authenticate to the ZooKeeper servers.
```
keytool -genkeypair -alias <name> -keyalg <algorithm> -keysize <size> -dname <subject> -validity <days> -keystore <path to keystore> -storepass <password> -keypass <same password> -storetype JKS
```
Where,
- <name>: Any value.
- <algorithm>: The key algorithm, such as RSA.
- <size>: Key size, which must be at least 2048.
- <subject>: X.500 Distinguished Name (DN), with at least a common name (CN) token. For example, CN=zookeeper-client-1.
- <days>: Number of days before the certificate expires. For example, 3650.
- <path to keystore>: Fully qualified path to the keystore file that will be created.
- <password>: Password for the keystore that will be created.
Use the Java keytool utility that is provided in the IBM JDK to export the public certificate of the personal certificate that is created in step 4 on every Sterling B2B Integrator and Global Mailbox node by using the following command:
```
keytool -exportcert -rfc -alias <name> -keystore <path to keystore> -file <path to cert file> -storepass <password>
```
Where,
- <name>: Alias of the personal certificate created in Step 4.
- <path to keystore>: Fully qualified path to the keystore created in Step 4.
- <path to cert file>: Fully qualified path to the certificate that is to be exported.
- <password>: Password of the keystore that is created in Step 4.
Create trust store for client authentication.
1. Use the Java keytool utility that is provided in the IBM JDK to import the public certificate of the personal certificate, created in Step 5, into one trust store. Run the command:
```
keytool -importcert -alias <name> -file <path to cert file> -keystore <path to trust store> -storepass <password> -storetype JKS
```
  Where,
  - <name>: The alias of the personal certificate created in Step 5.
  - <path to cert file>: The fully qualified path to the certificate exported in Step 5. Copy the file to the zookeeper server, or to a shared file system that is accessible by the zookeeper server.
  - <path to trust store>: The fully qualified path to the trust store of the zookeeper server trust store, which is created if it does not exist.
  - <password>: The password of the trust store.
  This trust store is used by all ZooKeeper servers.
2. Copy this truststore to each ZooKeeper server, taking note of the full path. Recommended path is <install dir>/zookeeper/conf/truststore.jks.
Configure ZooKeeper to only accept secure connections.

Enable client-to-node encryption on each zookeeper server zoo.cfg file in the local data center. Client-to-node encryption is disabled by default and must be explicitly enabled by editing the zoo.cfg file located at <installed-directory>/zookeeper/conf in all servers with the following values:
1. By default, the client port is enabled. For client node encryption, enable the secure client port and comment the client port.
```
secureClientPort=<port value>
```
```
#clientPort=<port value>
```
  Where, <port value> is the port to listen on for secure client connections using SSL.
  
  Note: The port values must be same. If secureClientPort is enabled, then client to node encryption and authentication is enabled in ZooKeeper by default.
2. Add the below SSL properties:
```
serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory
ssl.keyStore.location=<path to keystore>
ssl.keyStore.password=<password>
ssl.trustStore.location=<path to truststore>
ssl.trustStore.password=<password>
```
  Where,
  - keystore.location: Specify the fully-qualified path to the server keystore file
  - keystore.password: Specify the password used when the keystore was created.
  - truststore.location: Specify the fully-qualified path to the server truststore file
  - truststore.password: Specify the password used when the truststore was created.
3. Optional: Configure a specific SSL version and its cipher suites.
  Add the properties:
```
ssl.protocol=<SSL protocol version>
ssl.ciphersuites=<list of SSL ciphers>
```
  Where,
  - ssl.protocol: Specify the SSL protocol version. If not specified, the default value TLSv1.2 is used. For the list of supported values, see SSL Protocols.
  - ssl.cipherSuites: Specify the comma separated list of cipher suites. If not specified, all supported cipher suites will be used. For the list of supported values, see Cipher suites.
  Note:
  - You can establish a more secure connection by configuring TLS 1.3 as the default mode of communication. To do this, you must override both the properties as follows:
    ssl.protocol=TLSv1.3 ssl.ciphersuites=<list of supported ciphers for TLS 1.3>
    Where, ssl.ciphersuites is the list of cipher suites as comma separated values. It can consist of one or a combination of all the supported ciphers.
    For example,
    ssl.protocol=TLSv1.3 ssl.ciphersuites=TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256
  - You must ensure that the global mailbox properties com.ibm.mailbox.zookeeper.ssl.protocol and com.ibm.mailbox.zookeeper.ssl.ciphers are also set to the same values in datacenter.properties. For more information, see datacenter.properties.
Configure Global Mailbox to connect to ZooKeeper securely:
1. Generate an encrypted password for a truststore file. To generate the encrypted password, see SSL Encryption Password Utility
2. After client-to-node encryption is enabled on the cluster, client-to-node encryption can be enabled on Global Mailbox clients by adding com.ibm.mailbox.zookeeper.ssl. * properties listed below in the <StoragePath>/config/datacenter.properties file, so the properties apply to all nodes in the data center.
```
com.ibm.mailbox.zookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty
com.ibm.mailbox.zookeeper.client.secure=true
com.ibm.mailbox.zookeeper.ssl.trustStore.location=<path to truststore>
com.ibm.mailbox.zookeeper.ssl.trustStore.password=<encrypted truststore password>
```
  Where,
  - client.secure: Specifies whether client-to-node encryption is enabled. Set to true to enable it.
  - trustStore.location: Specifies the fully-qualified path to the server trustStore file. It should be <StoragePath>/config/<truststore file>.
  - trustStore.password: Specifies the encrypted password.
Configure which key Global Mailbox should present when authenticating to ZooKeeper.
1. Configure client authentication keystore on every Sterling B2B Integrator and Global Mailbox node by adding the following SSL properties:
```
com.ibm.mailbox.zookeeper.ssl.keyStore.location=<path to keystore>
com.ibm.mailbox.zookeeper.ssl.keyStore.password=<encrypted keystore password>
com.ibm.mailbox.zookeeper.ssl.hostnameVerification=false
```
  into the following files:
  - <b2bi>/MailboxUtilities/admin/conf/mailbox.properties
  - <b2bi>/wlp/usr/servers/mailboxui/mailbox.properties
2. Add the following properties in the customer_overrides.properties file in IBM Sterling B2B Integrator. For more information, see Property Files.
```
global_mailbox.com.ibm.mailbox.zookeeper.ssl.keyStore.location=<path to keystore>
global_mailbox.com.ibm.mailbox.zookeeper.ssl.keyStore.password=<encrypted keystore password>
global_mailbox.com.ibm.mailbox.zookeeper.ssl.hostnameVerification=false
```
  Where,
  - keyStore.location: Specify the fully-qualified path to the client keyStore file
  - key Store.password: Specify the encrypted password used when the keystore is created. For more information, see SSL Encryption Password Utility.
Restart ZooKeeper by restarting Global Mailbox. From the /bin directory within the Global Mailbox installation folder:
- To stop ZooKeeper:
```
./stopGMCoordinate.sh
```
- To start ZooKeeper:
```
./startGMCoordinate.sh
```
Restart the Global Mailbox servers by running the commands:
- To stop Global Mailbox Administration Server:
```
./stopGMAdmin.sh
```
- To start Global Mailbox Administration Server:
```
./startGMAdmin.sh
```
Restart the Global Mailbox Client Adapter on every Sterling B2B Integrator node.
Restart the Sterling B2B Integrator service by running the hardstop.sh and runAll.sh command.