One-Way TLS Setup Explained
From a security perspective, it is essential to enforce security in transit. Most of our APIs are REST and they can enable secure endpoint over HTTPS. In this article, I will introduce key terminology and will demonstrate how to apply basic theory to API configuration. I will also discuss HTTPS on CloudHub. Let’s get started.
Key Terminology
Terminology tends to be a weak point for many developers. Understanding these terms may make your work easier.
- Private key: a key used by the server to decrypt. This file is confidential and should not be shared with anyone. It is created and owned by the creator.
- Public key: a key used by a TLS client to encrypt data.
- Certificate: a file used to verify that the consumer/server is the public key owner. The certificate contains the public key and extra metadata, such as the issuer.
- Keystore : a file used to store key-pairs (private and public keys) secured by a password on the key and keystore level.
- Truststore: a file used to store trusted certificates. The file is usually used for self-signed and client certificates.
- Self-signed certificate: an insecure certificate created by you and not signed by the Certificate Authority.
One Way TLS
One way TLSs are common; you encounter them seamlessly while browsing pages on the internet and calling modern APIs using HTTPS protocol.
Consider the diagram below. It depicts a MuleSoft API that is available over HTTPS and a keystore installed with a CA-signed key pair. What does communication look like in this pattern?
- API consumer issues a hello session request to the MuleSoft API.
- MuleSoft API responds with a certificate and a public key (remember, public keys are part of the certificate). Both are coming from the keystore.
- Key validation occurs. As this is a CA signed certificate, the API consumer requests the Certificate Authority to authenticate the certificate.
- From now on, all requests and responses are encrypted.
Remember that steps 1–3 are happing under the hood (i.e., they are the underlying implementation).
On the API consumer side, nothing was required to set up the one-way TLS. A truststore is optional; you could configure it but it is not needed for a CA-signed certificate. We only need to prepare a truststore if we are using self-signed certificates. Let’s see how it looks on the diagram below.
The main difference is happening at point three. We do not contact the CA to validate the certificate and the public key, but instead, to the locally stored truststore. The rest of the steps remain the same. This is a common scenario in non-production environments.
Configure Your API
In this walkthrough, we will enable HTTPS on MuleSoft API using a self-signed certificate.
Generate a self-signed certificate:
For simplicity, I prefer to generate certificates using graphical UI in the free tool KeyStore Explorer.
- Click ‘Create a New KeyStore’
- Select ‘PKCS #12’ (this is the suggested format)
- Right click and select ‘Generate Key Pair’
- Confirm the defaults
- Add a common name, like mulesoft.com
- Set key and key store password
You can use keytool to generate key pairs. You can learn more information on this topic by reading this documentation.
Configure a HTTP listener:
Enabling HTTPS is straightforward. First, place your keystore in the ‘resources’ folder. Then we need to configure the global configuration of the HTTP Listener.
In the ‘General’ section, you need to change the protocol to ‘HTTPS’ and the default port to ‘8082’ (in case you use CloudHub). You can learn more about networking configuration on CloudHub in this interactive infographic.
Next, let's move to the TLS tab and edit it inline. From the explanation above, you know that we need to configure only the keystore. Here are guidelines to achieve this:
- Type : select ‘PKCS12’ (recommended format of the keystore)
- Path: path to the keystore and its name
- Alias: the name of the key pair in the keystore
- Key Password: password used to protect the key
- Password: password protecting KeyStore file (use a different password than you used for the key password)
Now, you have enabled HTTPS on your API.
HTTPS on CloudHub
How does this apply to CloudHub? First, we configured HTTPS which is available directly from our API.
CloudHub 1.0
Let’s assume that our API is deployed in US East (Ohio) using the name blog-salesforce-sapi-dev. On the diagram below, you can see two calls scenarios:
- Calling via shared load balancer: the default path — https://blog-salesforce-sapi-dev.us-e2.cloudhub.io/api/
- Calling MuleSoft Worker directly: https://mule-worker-blog-salesforce-sapi-dev.us-e2.cloudhub.io:8082/api/
In the first approach, you will be presented with a MuleSoft CA-signed certificate for the subdomain cloudhub.io. Your certificate is used behind the load balancer within the network. In the latter case, we are calling our API directly so that we are presented with our certificate.
By the way, you can change only the MuleSoft Worker and dedicated load balancer certificates. The shared load balancer is unchangeable. This article describes how to do this on DLB.
CloudHub 2.0
For CloudHub 2.0, the situation looks a bit different. There is no need to configure HTTPS in your HTTP listener. Consider the diagram below.
As you can see, we have one public endpoint available in our non-production private space. By default, it is expecting traffic over HTTPS. Under the hood, your MuleSoft API is expected to be available over HTTP on port 8081. This port is available within the container, and the translation happens from port 443 over HTTPS to port 8081 over HTTP.
So what about the certificate? You will be presented again with the MuleSoft CA-signed certificate for the cloudhub.io subdomain.
Thank you for reading this article on one-way TLS setup and I hope you have learned new and useful information.
