Introduction
Kiuwan On-Premises fosters secure connections by providing a default installation environment where most communications are done under a secure protocol.
By default, Kiuwan On-Premises services connections use:
Communication between | Protocol | Secure connection | ||
---|---|---|---|---|
Any client (browser, KLA, K4D, custom REST API client, etc.) | ↔ | Kiuwan apache load balancer | HTTPS | Yes |
Kiuwan apache load balancer | ↔ | Kiuwan (frontal) | HTTPS | Yes |
Kiuwan (frontal, analyzer, scheduler, updater) | ↔ | MySQL database | mysql protocol (SSL can be optionally enabled) | Optional |
Kiuwan (frontal, analyzer, scheduler, updater) | ↔ | Redis cluster node | RESP (REdis Serialization Protocol) - SSL | Optional (only supported when using AWS elasticache) |
Redis cluster node | ↔ | Redis cluster node | RESP (REdis Serialization Protocol) | Optional (only supported when using AWS elasticache) |
Every time a client connects to a server using a secure protocol, it needs to make sure that the contacted server is who it claims to be. This is usually done by the server returning a certificate (signed by a Certification Authority, CA) that the client can check for authenticity.
As the client needs a way to identify if the server's certificate is trustable, all secure transmision enabled clients have or rely on a dictionary of trustable CAs.
In order to provide a default installation configuration that enables secure protocols on most communications channels, Kiuwan On-Premises comes with a set of certificates and keystores for the default configured domain (kiuwan.onpremise.local).
Note that the previous statement means that if you rely on the default installation configuration all your certificates will be the same as other Kiuwan customers certificates. We encourage you create your own CA for signing your own domain certificates or sending a CSR to a trusted CA. See the following sections for more information on this topic.
Provided certificates and keystores
Kiuwan On-Premises installation tool (kiuwan-cluster) provides a number of files to allow secure communications between containers. These files are located in kiuwan-cluster distributions under the ssl folder.
The following table shows the provided certificate files:
Location | File | Format | Content | Purpose | Expiration date |
---|---|---|---|---|---|
ssl/ca | cacert.pem | RSA 4096 bits SHA256 | The CA certificate that signed Kiuwan On-Premises domain certificate | Allows Kiuwan servers to provide the CA that signed their certificates | 2029/10/13 |
ssl/kiuwan.onpremise.local | domaincert.pem | RSA 4096 bits SHA256 | The Kiuwan On-Premises domain certificate | Allows Kiuwan servers to identify themselves | 2029/10/13 |
The following table shows the provided private key files:
Location | File | Format | Content | Purpose |
---|---|---|---|---|
ssl/ca | cakey.pem | RSA 4096 bits PKCS #8 | The provided CA private key | Allows signing certificates with the provided CA |
ssl/kiuwan.onpremise.local | domainkey.pem | RSA 4096 bits PKCS #8 | The Kiuwan On-Premises domain private key | Allows encrypting traffic for the provided domain |
The following table shows the provided Java keystore files:
Location | File | Content | Purpose |
---|---|---|---|
ssl/kiuwan.onpremise.local | domainkeystore.jks | This keystore contains cacert.pem, domaincert.pem and domainkey.pem files. Its password is the one provided in the default installation configuration (see java.keystore.password property). | Allows Kiuwan instances to identify themselves and encrypt traffic to enable secure connections |
ssl/kiuwan.onpremise.local | truststore.jks | This keystore contains all the CA certificates included in the OpenJDK default truststore (see next row in this table) plus the provided CA certificate. Its password is the one provided in the default installation configuration (see java.truststore.password property). | Allows Kiuwan instances to communicate to external servers that offer certificates signed by trusted CAs (needed both for AWS based installations and Kiuwan central servers communications) |
ssl/truststore | truststore.jks | This keystore contains the OpenJDK 13 trusted CAs as of 2019/10/16. Its password is the one provided by OpenJDK for its cacerts file. | Allows generating a custom truststore that includes most needed trusted CAs certificates plus the one provided by the installation tool |
Using certificates using the provided CA or your own CA
Kiuwan On-Premises installater (kiuwan-cluster) contains a handy tool for creating certificates both with the provided CA or your own CA.
The tool is a bash script located here:
- [INSTALL_DIR]/ssl/kiuwan-certool.sh
Remember that, as stated in Installation guide - Installation requirements, you will need the specified versions of a JRE and OpenSSL in order to be able to generate certificates using the provided tool.
When generating custom certificates, it is recommended that you change the default properties in the configuration file located here:
- [INSTALL_DIR]/ssl/config/certs.properties
These is the meaning of the customizable properties of the previous file (default passwords are ommited):
Property | Default value | Meaning |
---|---|---|
java.keystore.password | The password to set to the generated Java keystore | |
java.truststore.password | The password to set to the generated Java truststore | |
ssl.ca.password | The password to set to the generated CA (only applies when generating a new custom CA). The set password will be used when signing certificates as well | |
ssl.country | US | Country, state, locality, organization or organization unit to set both to the subject of the CA certificate (in case of you are generating a new custom CA) and to the subject of the specified domain signing request |
ssl.state | mystate | |
ssl.locality | mylocality | |
ssl.organization | mycompany | |
ssl.organization.unit | myorganizationunit | |
ssl.company.domain | mycompany.com | Company domain to set to the subject's Common Name (CN) of the CA certificate (in case of you are generating a new custom CA) |
ssl.subject.alt.names | DNS:kiuwan.onpremise.local[:443,:3306,:6379] DNS:wildflykiuwan-f[1-2][:8143,:8443] DNS:wildflykiuwanContainer-f[1-2][:8143,:8443] DNS:mysqlkiuwan[:3306] DNS:mysqlkiuwanContainer[:3306] DNS:redis_0000[1-6][:6379] | Subject Alternative Names (SANs) that will be set to the specified domain certificate. These are needed in order to be able to share the same certificate between different services of the Kiuwan On-Premises infrastructure. |
Step 1: set the CA to use when signing your certificates
The provided tool will use the CA files located here:
- [INSTALL_DIR]/ssl/ca/cacert.pem
- [INSTALL_DIR]/ssl/ca/cakey.pem
You can either:
- Use the provided CA.
- Let the tool generate a new CA.
- Use your own CA.
Use the provided CA
Just continue to Step 2: generate the certificates and keystores.
Let the tool generate a new CA
Just backup the provided CA files and a new CA will be automatically generated:
cd [INSTALL_DIR]/ssl/ca mv cacert.pem cacert.pem.bak mv cakey.pem cakey.pem.bak
Use your own CA
Just replace the provided files with your own CA's ([INSTALL_DIR]/ssl/ca/cacert.pem and [INSTALL_DIR]/ssl/ca/cakey.pem).
We recommend backuping the provided CA files just in case you want to get back to the provided defaults (see Use your own CA).
Step 2: generate the certificates and keystores
To generate all the needed files using the provided CA and the default configuration, just run the following commands:
cd [INSTALL_DIR]/ssl ./kiuwan-certool.sh [DOMAIN_NAME]
This will create the following files under the ssl/[DOMAIN_NAME] folder:
- domaincert.pem
- domainkey.pem
- domainkeystore.jks
- truststore.jks
Step 3: 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 [INSTALL_DIR]/ssl ./kiuwan-cercopy.sh [DOMAIN_NAME]
Step 4: 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 Installation guide page for more information.
Using certificates signed by a trusted CA
Note that Kiuwan On-Premises installation tool does not automate this process as it may be different between organizations based on their security policies.
The following table shows the files that Kiuwan On-Premises needs:
File | Where does it come from? | How can I get it? |
---|---|---|
domainkey.pem | You have to generate this file | Use a SSL tool to generate it |
cacert.pem | Your CA will provide this file | Your CA will send this file to you after a CSR (Certificate Signing Request) |
domaincert.pem | Your CA will provide this file | Your CA will send this file to you after a CSR (Certificate Signing Request) |
domainkeystore.jks | You have to generate this file | Use your JRE's keytool program to generate it |
truststore.jks | Provided by the installation tool | It is stored in [INSTALLER_DIR]/ssl/truststore/truststore.jks |
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:
- Create a private key file (domainkey.pem).
- Create a certificate signing request (CSR) file using the keyfile from the previous step.
- Send the CSR file to your trusted CA for signing.
- Store the files sent by your trusted CA:
- The CA certificate (cacert.pem).
- 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:
- Create a pkcs12 file using the CA certificate, your private key file and your domain certificate.
- Create a Java keystore (domainkeystore.jks) that:
- Contains both the CA certificate and your domain's certificate.
- Its format is pkcs12.
- 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:
- [INSTALL_DIR]/user-content/certs
Step 3: 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 Installation guide page for more information.
Adding the provided or a custom CA to Kiuwan On-Premises' clients
Kiuwan On-Premises installer tool provides default certificates for the default host name, signed by a supplied CA (Certificate Authority).
The CA public certificate is provided in this file:
- [INSTALL_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.
In order 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.