Kiuwan On-Premises Managing Certificates

Here are the usual steps to follow when requesting a CA to create a certificate for your domain. Most of them can be carried out using OpenSSL (but there are other alternative tools available).

Step 1: Create a CSR (Certificate Signing Request)

Follow these steps:

1. Create a private key file (domainkey.pem).
2. Create a certificate signing request (CSR) file using the keyfile from the previous step.
3. Send the CSR file to your trusted CA for signing.
4. Store the files sent by your trusted CA:
   1. The CA certificate (cacert.pem).
   2. Your domain certificate (domaincert.pem).

Step 2: Create the java keystore

At this point, you will need three files. Your private key and those sent by your CA:

1. Create a pkcs12 file using the CA certificate, your private key file, and your domain certificate.
2. Create a Java keystore (domainkeystore.jks) that:
   1. Contains both the CA certificate and your domain's certificate.
   2. Its format is pkcs12.
   3. Has an alias "domainp12" for your domain's certificate.

Once you have all the needed files (remember that you can use the provided truststore.jks file), copy them to:

[INSTALLER_DIR]/user-content/certs

Step 3: Continue with your installation

The next step is to run the deploy-user-content.sh script to let the installer deploy your certificates to the persistent volumes. Note that once this is done, depending on your installation needs, the following steps may change. Please refer to the Kiuwan On-Premises Distributed Installation Guide page for more information.

Using certificates provided by your organization

If your organization manages its certificates, you should send a requirement for the domain where your Kiuwan On-Premises installation will be accessible. You should indicate that this domain should match the CN set in the generated certificate. You should receive these files from the department responsible for generating the certificate files:

• The public certificate of your organization's CA (cacert.pem).
• The public certificate for Kiuwan On-Premises domain (domaincert.pem).
• The private key of your Kiuwan On-Premises domain certificate (domainkey.pem).

Note that the previous files may have different names depending on your organization's naming policies.

Step 1: Verify files format

Depending on how your organization creates its certificates, your files may have a format not supported by the installation tool.

All provided certificates MUST be in PEM format. Please refer to Provided certificates and keystores section for more details.

In case you have received the certificate files in a different format, you should convert the files to PEM format.

Once the files have been converted and renamed, you should end up with three files:

• cacert.pem
• domaincert.pem
• domainkey.pem

Step 2: Backup provided files

To avoid confusion, rename the folder where the provided files reside to keep them separated from the ones you have already prepared:

cd [INSTALL_DIR]/ssl
mv ca kiuwanca

Step 3: Generate Java keystore and truststore

Copy your cacert.pem file to the ca folder:

cd [INSTALL_DIR]/ssl
mkdir ca
cp cacert.pem [INSTALL_DIR]/ssl/ca

cd [INSTALL_DIR]/ssl
mkdir [DOMAIN_NAME]
cp domaincert.pem [INSTALL_DIR]/ssl/[DOMAIN_NAME]
cp domainkey.pem [INSTALL_DIR]/ssl/[DOMAIN_NAME]

Invoke the kiuwan-certool.sh script to generate the needed java stores:

cd [INSTALL_DIR]/ssl
./kiuwan-certool.sh [DOMAIN_NAME]

This will create the missing jks files in the [DOMAIN_NAME] folder.

Step 4: Copy the generated files to the user-content folder

You can run the following commands to automatically copy the needed files to the user-content folder, where the installer tool deploy-user-content.sh will read from when deploying the user content to the persistent volumes locations:

cd [INSTALLER_DIR]/ssl
./kiuwan-cercopy.sh [DOMAIN_NAME]

Step 5: Continue with your installation

The following step is to run the deploy-user-content.sh script to let the installer deploy your certificates to the persistent volumes. Note that once this is done and depending on your installation needs, the following steps may change. Please refer to the Kiuwan On-Premises Distributed Installation Guide page for more information.

Adding the provided or a custom CA to Kiuwan On-Premises' clients

The Kiuwan On-Premises installer provides default certificates for the default hostname, signed by a supplied CA (Certificate Authority).

The CA public certificate is provided in this file:

[INSTALLER_DIR]/ssl/ca/cacert.pem

If you choose to sign your domain's certificate with the provided CA, a new CA created using kiuwan-certool.sh or your own CA, internet browsers and other clients accessing your Kiuwan On-Premises installation will not recognize it as a trusted CA by default. You will get error messages like this one:

Your connection is not private
Attackers might be trying to steal your information from kiuwan.onpremise.local (for example, passwords, messages, or credit cards).
NET::ERR_CERT_AUTHORITY_INVALID

This is the expected behavior as the CA store that your browser or client uses will not contain your own CA or the one supplied along with kiuwan-cluster.

To make your browser trust the supplied certificates, you will need to add this CA to your browser and Java clients that access your Kiuwan On-Premises installation:

• Fixefox, Chrome, Edge: import cacert.pem by using the tools provided by the browsers.
• Java clients (Kiuwan for developers Eclipse, Kiuwan for developers JetBrains, Jenkins plugin, KLA, etc): add the provided cacert.pem to the JRE keystore used by the client. Please refer to the official documentation of your JRE distribution about the Java keytool program.
• Windows clients (Kiuwan for developers VisualStudio): import cacert.pem by using the tools provided by Windows (certmgr.msc).
• Multiplatform clients (Kiuwan for developers VisualStudioCode): import cacert.pem by using the tools provided by your OS.