Mutual TLS

Kokomo services can be secured with mTLS and IP firewalling. Here we will discuss the former.

With mTLS we can secure any service being exposed via Kokomo, requesting that the client is presenting a valid TLS certificate in order to be able to consume the service.

This is an optional security capability that needs to be explicitly enabled, and when enabled Kokomo will refuse connections from any client that is presenting a wrong TLS certificate, or no certificate at all.

Please note that the mTLS capability protects the connections from the client to Kokomo, while the connection from Kokomo to the agent is already securely encrypted by default at all times.

To enable mutual TLS, first we need to start the agent with the right arguments with the file path to the CA certificate, the server certificate and key. Then we need to also generate the client certificates that the clients should be using when connecting to Kokomo.

1. Generating the CA and server certificate and keys

First we need to generate a CA private key (in the following example without a passphrase):

openssl genrsa -out ca.key 2048

Then we need to generate a self-signed CA certificate using the CA key we just generated (this creates a CA valid for 10 years -days 3650):

openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt -subj "/CN=Kokomo CA"

Then we generate the server key and CSR (Certificate Signing Request):

openssl req -newkey rsa:2048 -nodes -keyout server.key -out server.csr -subj "/CN=*.connect.getkokomo.io"

And we sign the server certificate with our CA:

openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt

These operations will generate the following files: ca.crt, ca.key, ca.srl, server.crt, server.csr, server.key.

2. Enabling mTLS

To enable mutual TLS, we need to start the agent CLI with additional parameters to upload the server key, server certificate and server certificate authority (CA) that will be used by Kokomo to setup the TLS infrastructure. We also need to pass the --tls-enabled flag.

$ kokomo --service-name "redis" \
  --local-port 1234 \
  --remote-port 1234 \
  --tls-enabled \
  --tls-ca-cert /PATH/TO/ca.crt \
  --tls-cert /PATH/TO/server.crt \
  --tls-key PATH/TO/server.key \
  --api-key [APIKEY]

To enable mTLS the following arguments need to be passed:

--tls-enabled, or the environment variable KOKOMO_TLS_ENABLED=true.
--tls-ca-cert with the file path to the CA certificate, or KOKOMO_TLS_CA_CERT=/file/path.
--tls-cert with the file path to the TLS server certificate, or KOKOMO_TLS_CERT=/file/path.
--tls-key with the file path to the TLS server key, or KOKOMO_TLS_KEY=/file/path.

After we start the agent with the following arguments, Kokomo will provision our infrastructure and it will request a valid client certificate to start processing requests. To make a request from the client, we need to provision a client certificate.

3. Generating the client certificate and keys

To generate one or more client certificates that can start using our service via Kokomo, we need to generate a client certificate and key using the same CA that we used for the server certificate and key.

First, we create a client key and CSR:

openssl req -newkey rsa:2048 -nodes -keyout client.key -out client.csr -subj "/CN=myclient"

Then we sign the client certificate with our CA:

openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt

These operations will generate the following files: client.crt, client.csr, client.key.

4. Make a secure request

Finally, now that we have setup mutual TLS on Kokomo and we have generated the client certificate, we can start making a request to our service using the Kokomo DNS that has been returned by the provisioning process:

curl --cert /PATH/TO/client.crt --key /PATH/TO/client.key https://abcdefg.connect.getkokomo.io:1234 -k

Of course this example is with curl, we can use any other client that allows us to set a client TLS certificate.