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:
| 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 your own certificates to a trusted CA to be signed.
Provided SSL related files
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 key files:
| Location | File | Format | Content | Purpose |
|---|---|---|---|---|
| ssl/ca | cakey.pem | RSA 4096 bits PKCS #8 | The provided CA key | Allows signing certificates with the provided CA |
| ssl/kiuwan.onpremise.local | domainkey.pem | RSA 4096 bits PKCS #8 | The Kiuwan on premises domain 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 and domaincert.pem files. Its password is the one provided in the default installation configuration (see java.keystore.password property). | Allows Kiuwan instances to identify themselves 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 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 |
Generating certificates for a custom domain
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 for 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 HTTPS configuration, certificates and Java keystores).
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 will read from to deploy them to the persistent volumes locations:
cd [INSTALL_DIR]/ssl ./kiuwan-cercopy.sh [DOMAIN_NAME]
Using certificates signed by a trusted CA
Adding the provided or a custom CA to Kiuwan on premises clients