User-provided SSL certificate

Before you begin

The native encryption features of Db2 Event Store use the cryptographic and SSL/TLS capabilities of the IBM® Global Security Kit (GSKit). The GSKit is used to implement the SSL and TLS protocols that enable protected communications over the network between the remote client and the IBM Db2 Engine in Db2 Event Store.

The Db2 Event Store has SSL authentication between remote client and engine enabled by default. At the time of installation, the Db2 Event Store will generate a key store file and a self-signed SSL certificate using the IBM GSKit library. After the initial installation, the user can replace the SSL certificate with their own SSL certificate stored in a key store.

When using the default generated SSL certificate, the user can use the REST API to get the client keystore file containing the public SSL certificate issued by the Db2 Event Store server, client keystore password, and the public SSL certificate file. After the user has provided their own SSL certificate, the REST server will, by default, stop returning the client keystore, client keystore password, and public SSL certificate to avoid leaking your SSL files without your permission. The user will have to explicitly enable or disable the REST API returning the SSL files.

Users also have the option to reset all changes to the SSL certificates, so that the default generated, self-signed certificate will be used.

Usage type 1: user-provided SSL certificate

Procedure

1. Copy the user's keystore file and keystore stash file (if the user wants to provide the password in a stash file format) into the designated location in the Db2 Event Store instance.
   1. Define the following shell variables using the command line:
      • NAMESPACE: The namespace that the Db2 Event Store instance is deployed under.
      • KEYSTORE_PATH: The absolute path to user's keystore file containing the certificate. The certificate must consist of a public and private keypair. This is not a path to the directory but to the actual keystore file. For example, if your keystore file is called new-keystore.pkcs12 and is in this directory on your local machine /root/new-ssl-files/, this variable must be set as KEYSTORE_PATH=/root/new-ssl-files/new-keystore.pkcs12.
      • KEYSTORE_STASH_PATH: This variable is required only when the user wants to provide the keystore password with a stash file. It should be the absolute path to the user's keystore stash file containing the encrypted keystore password. The stash file is usually generated together with the keystore file.
   2. Run the following commands to provide the keystore file and the keystore stash file (which is optional and only required when the user wants to provide the keystore password with a stash file) to the target Db2 Event Store instance.
      • Provide the keystore file:

        # Provide the keystore file
        kubectl cp ${KEYSTORE_PATH} ${NAMESPACE}/`kubectl get pods -n ${NAMESPACE} | 
        grep -E "eventstore.*-tenant-tools" | awk {'print $1'}`:user-ssl-files/user-provided-keystore

      • Provide the keystore stash file:
        Note: Only required when the user wants to provide the keystore password with a stash file.

        kubectl cp ${KEYSTORE_STASH_PATH} ${NAMESPACE}/`kubectl get pods -n ${NAMESPACE} | 
        grep -E "eventstore.*-tenant-tools" | awk {'print $1'}`:user-ssl-files/user-provided-keystore-stash

   3. Verify the correctness of the keystore file and the keystore stash file provided:
      • The user-provided keystore file will be shown with the name user-provided-keystore and the user provided stash file will be shown with the name user-provided-keystore-stash.

        Then use the following command to verify the data and the size of the keystore and keystore stash files:

        # list user provided files
        kubectl exec -n ${NAMESPACE} -it `kubectl get pods -n ${NAMESPACE} | 
        grep -E "eventstore.*-tenant-tools" | awk {'print $1'}` -- ls -l user-ssl-files

2. Define the eventstoreUtils macro, which allows users to pass commands to the Db2 Event Store engine.
   Note: For more information on using the eventstoreUtils macro, refer to IBM Db2 Event Store utilities setup and usage.
3. Run the eventstoreUtils macro to replace the key store, stash file, and SSL certificate. Replace the arguments accordingly.
   Note: When the default SSL certificate is replaced, the REST server will stop returning the client keystore, client keystore password, and public SSL certificate. The administrator will have to either distribute the public certificate to the trusted users manually, or explicitly enable the REST API returning the SSL files.
   • If the user wants to provide the keystore file and stash file:

     ## To replace with keystore file and stash file
     eventstoreUtils --tool update_client_ssl_keypair 
     --command "--replace-certificate --keystore-type kdb --use-stash-file --label SSLCert"

   • If the user wants to provide the keystore file and password string:

     ## To replace with keystore file and password
     eventstoreUtils --tool update_client_ssl_keypair 
     --command "--replace-certificate --keystore-type kdb --keystore-password "ExamplePassword" --label SSLCert"

Usage type 2: Enable or disable REST APIs returning SSL files

By default, the REST APIs described in Get client keystore and public SSL certificate using REST API will return the client keystore, client keystore password and the public SSL certificate to any authorized Db2 Event Store user.

When the default SSL certificate is replaced, the REST server will stop returning the client keystore, client keystore password and the public SSL certificate. The user will either have to distribute the public certificate manually to trusted users, or explicitly enable the REST API returning the SSL files.

If the user wants to stop the REST APIs from retuning the SSL files, they can explicitly disable the feature.

Enable REST APIs returning SSL files

1. Define the eventstoreUtils macro, which allows users to pass commands to the Db2 Event Store engine.
   Note: For more information on using the eventstoreUtils macro, refer to IBM Db2 Event Store utilities setup and usage.
2. Run the eventstoreUtils macro to enable the REST server to return the client keystore, client password, and the public SSL certificate to any authorized Db2 Event Store user.

   eventstoreUtils --tool update_client_ssl_keypair --command "--enable-rest"

Disable REST APIs from returning SSL files

1. Define the eventstoreUtils macro, which allows you to pass commands to the Db2 Event Store engine.
   Note: For more information on using the eventstoreUtils macro, refer to IBM Db2 Event Store utilities setup and usage.
2. Run the eventstoreUtils macro to disable the REST server from returning the client keystore, client password, and the public SSL certificate to any authorized Db2 Event Store user.

   eventstoreUtils --tool update_client_ssl_keypair --command "--disable-rest"

Usage type 3: Reset SSL certificate changes

1. Define the eventstoreUtils macro, which allows users to pass commands to the Db2 Event Store engine.
   Note: For more information on using the eventstoreUtils macro, refer to IBM Db2 Event Store utilities setup and usage.
2. Run the eventstoreUtils macro to deactivate the user-provided SSL certificate and to revert back to the default generated, self-signed certificate while enabling the REST server to return the default client keystore containing the default public SSL certificate, keystore password, and public SSL certificate.

   eventstoreUtils --tool update_client_ssl_keypair --command "--reset-default-ssl-certificate"