One-way and Two-way TLS and their implementation in MuleSoft

Introduction:

In this article, we will focus on the role of one-way and two-way TLS in API Integrations and their implementation in MuleSoft integration. Transport Layer Security, or TLS, is a widely adopted security protocol designed to facilitate privacy and data security for communications over the Internet. A primary use case of TLS is encrypting the communication between web applications and servers.

Keystore and Truststore

Before discussing the implementation of one-way and two-way TLS in MuleSoft, let’s first discuss Keystore and Truestore. In short, a Keystore or Truststore is a file that contains certificates; Keytool facilitates the generation of these files and is a part of the JDK, or you can use a GUI tool like Keystore explorer.

Keystore

• A Keystore contains private keys and associated certificates having the public key
• KeyStore has its dedicated password
• Each entry of a private key/certificate combination in Keystore has its own dedicated password.
• The owner/Server retrieves a certificate from its KeyStore and presents it to the other side.

Truststore

• A trust store has a list of all certificates which client trust
• These could be certificates of Trusted CA and self-signed certificates of trusted parties
• So when a server presents its certificate, the Client will verify it using the certificates stored in TrustStore
• A password also protects TrustStore.

One Way TLS

In one–way TLS authentication (Server Certificate Authentication), only the Client validates the server; the server does not verify the client application. When implementing one–way TLS authentication, the server application shares its public certificate with the Client.

• Generate Keystore for server:

You can generate the Keystore for the server using the Java Keytool tool preinstalled with the JDK. To generate the Keytool, open your terminal/cmd and enter the following command, which would generate Keystore with RSA 4096 bit keypair saved in location C:/Documents/test/server-keystore.jks and with an alias as mule-server

keytool -genkey -alias mule-server -keysize 4096 -keyalg RSA -keystore C:/Documents/test/server-keystore.jks

After executing the above, it will password, first name, last name, common name and other details, including the key password.

• Export the public certificates from the Keystore and add them to Client Truststore

To export the public certificate execute the command

keytool -export -alias mule-server -keystore C:/Documents/test/server-keystore.jks

 -file C:/Documents/test/server_public.crt

This will export the public certificates that can now be imported into the Truststore.

• Import the server public certificate in the client Trustore

The below command will generate the Truestore and import the server’s public certificates that we exported in the previous step into the generated Truststore

keytool -import -alias mule-client-public -keystore C:/Documents/test/client-truststore.jks -file C:/Documents/test/server_public.crt

• Add Truststore and Kestore to mule listener and requester

Server/listener configuration

• Copy Truststore and Keystore in src/main/resources folder
• Configure the port as 8082 in the listener config or define it as port
• Add the configuration for the Keystore you generated in TLS config of the Listener (alias can be left blank if your Keystore has one 1 keypair), the type should be set as jks.

• Client/Requester Configuration:
  • Set HTTPS as protocol and host as the server host (localhost) and server port 8082 (defaults to 443 and could be left blank for a website/web application)
  • Click on TLS configuration option and select edit inline
  • Add the Truststore name and password.

This is it! You just set up a TLS connection with our HTTP listener acting as a server and the requester acting as a Client. To test the application, you can create a HTTP listener sending a request to our server endpoint; You can refer to the image; the client HTTP listener accepts HTTP request here so we can hit with the postman or any other client without any issue

Two-way TLS

In two-way SSL authentication, the client application verifies the server application’s identity, and then the server application verifies the identity of the client application. Both parties share their public certificates, and then validation is performed. Two-way SSL authentication works with a mutual handshake by exchanging the certificates.

Implementing Two Way TLS in a MuleSoft Application

Implementation of two way TLS is similar to the implementation of one way TLS. However, here we would be configuring the Keystore and Truststore in both the Listener (server) and Requester (Client).

In this scenario, the Keystore will consist of their respective key pairs for server and Client and the server Truststore consisting of the Client public certificates and the Client Truststore consisting of the server’s public certificates.

• Generate Keystore for server:

Execute the following command and write the details and Keystore password like you did for 1 way TLS

You can ignore the warning that comes after executing the query

keytool -genkey -alias mule-server -keysize 4096 -keyalg RSA -keystore C:\Users\jayank\Documents\2wayTLS\server-keystore.jks

You can ignore the warning that comes after executing the query

• Export the public certificates from the server Keystore and add them to Client Truststore

The following command will export the server public certificate:

keytool -export -alias mule-server -keystore C:\Users\jayank\Documents\2wayTLS\server-keystore.jks -file C:\Users\jayank\Documents\2wayTLS\server_public.crt

To generate the client Truststore and add the server public certificate into it, execute:

keytool -import -alias mule-client-public -keystore C:\Users\jayank\Documents\2wayTLS\client-truststore.jks -file C:\Users\jayank\Documents\2wayTLS\server_public.crt

• Generate the Client Keystore

keytool -genkey -alias mule-client -keysize 4096 -keyalg RSA -keystore C:\Users\jayank\Documents\2wayTLS\client-keystore.jks

• Export the public certificates from Client Keystore and import them into the servers Truststore

keytool -export -alias mule-client -keystore

C:\Users\jayank\Documents\2wayTLS\client-keystore.jks -file

C:\Users\jayank\Documents\2wayTLS\client_public.crt

keytool -import -alias mule-server-public -keystore

C:\Users\jayank\Documents\2wayTLS\server-truststore.jks -file

C:\Users\jayank\Documents\2wayTLS\client_public.crt

• Configure HTTP Listener (Server) with server Keystore and Truststore

Now, if you have followed all the above steps correctly, you will have 4 jks files in your directory 2 Keystores and 2 Truststores 1 each for Client and server.

Now add the server Keystore and server Truststore in HTTP listener with the password and alias (for server) you used while generating those.

• Configure HTTP Requester (Client) with client Keystore and Truststore

Add the Client-Truststore and Client-Keystore in the HTTP request TLS configuration similar to you did for the server/listener.

Troubleshooting Tips:

• You can use a test HTTP listener connection to call the requester (Client), which will call the Listener (server) refer to 1 TLS instructions for the same.
• Add -M-Djavax.net.debug=ssl in MuleSoft Anypoint Studio as an argument or add a runtime property as javax.net.debug=ssl in Mulesoft CloudHub to see the complete TLS debug logs for your MuleSoft API. This will allow you to see where exactly in the TLS handshaking process your request is failing, do remember to turn them off immediately as these logs are hefty.

Thanks for reading. Hope this will help all of you MuleSoft developers in implementing one-way and two-way TLS.

Find More MuleSoft best practices at Caelius Consulting Resource Centre.