Securing the MQTT connection with TLS

Now we want to encrypt the MQTT connection that we set up in the previous exercise by implementing TLS. We will also cover how to verify the broker’s authenticity.

Recall from lesson 3 that TLS can provide :

• Confidentiality (communication cannot be read by third parties)
• Integrity (communication cannot be altered by third parties)
• Authenticity (verifies the identity of the client and server).

You can read more about how TLS provides authentication, confidentiality, and integrity here.

In this exercise, we will learn how to encrypt communication between the device (MQTT client) and the MQTT broker. Then we will get the root certificate of the MQTT broker and flash it to the device, so it can use it to verify the broker’s authenticity. We will also show how to encrypt the communication between the MQTT broker and the other MQTT client (running on your smartphone).

We will be using the TLS credentials subsystem of the Zephyr socket API to store the credentials on the device.

Exercise steps

In the GitHub repository for this course, go to the base code for this exercise, found in lesson4/wififund_less4_exer2.

1. Enable TLS support in the MQTT Library and change the port number

1.1 Enable TLS for the MQTT library by enabling CONFIG_MQTT_LIB_TLS in prj.conf.

CONFIG_MQTT_LIB_TLS=y

1.2 Change the MQTT broker port by changing the value to 8883. The 8883 is the standard TLS port for MQTT.

CONFIG_MQTT_BROKER_PORT=8883

1.3 Enable the TLS library and security relevant configurations.

Enable secure sockets (CONFIG_NET_SOCKETS_SOCKOPT_TLS) and the TLS credentials management subsystem (CONFIG_TLS_CREDENTIALS)

CONFIG_NET_SOCKETS_SOCKOPT_TLS=y
CONFIG_TLS_CREDENTIALS=y
CONFIG_MBEDTLS_RSA_C=y

• CONFIG_NET_SOCKETS_SOCKOPT_TLS: Enables the TLS socket options in the sockets API. This Kconfig will also select CONFIG_MBEDTLS, which enables the mbedTLS cryptography library.
• CONFIG_TLS_CREDENTIALS: Enables the TLS credentials subsystem of the socket API, which we will use to store the credentials on the device.
• CONFIG_MBEDTLS_RSA_C: Enables support for RSA cryptosystem in the mbedTLS library.

1.4 Increase the mbedTLS heap size, if building for the non-secure board target.

Open boards/nrf7002dk_nrf5340_cpuapp_ns.conf or boards/nrf5340dk_nrf5340_cpuapp_ns.conf, depending on the board you are using, and increase the mbedTLS heap size by changing the following Kconfig line

CONFIG_MBEDTLS_HEAP_SIZE=81920 

1.5 Increase the MQTT keep alive time to 5 seconds, as the introduction of TLS will cause some overhead processing such as certificates verification etc.

CONFIG_MQTT_KEEPALIVE=5

1.6 Include the header file for the TLS credentials subsystem.

#include <zephyr/net/tls_credentials.h>

2. Obtain the certificate from the MQTT broker and convert it into a C header file, certificate.h.

2.1 Open a browser and go to broker.hivemq.com.

Click on the lock besides the URL, go to Connection is secure and then Certificate is valid.

A Certificate Viewer should open. Go to Details and under Certificate Hierarchy select the top most certificate. Then select Export. Save the certificate in lesson4/wififund_less4_exer2 as ca_certificate.crt.

2.2 Convert the certificate into a header file in C.

In this exercise, we will use a simple Python script that takes care of that for us. It is provided with the exercise and it will convert the certificate file into a header file certificate.h that will contain the converted certificate as a C string.

Open a new terminal, navigate to the script folder (lesson4/wififund_less4_exer2/script), and then run the Python script cert_to_header.py by running the following command with the name of the certificate we want to convert as an argument.

python.exe .\cert_to_header.py ca_certificate.crt

This will generate the converted certificate.h in the /src subdirectory

Be aware that the script assumes that the certificate is placed in the root directory of your exercise (lesson4/wififund_less4_exer2).

2.3 Include the newly generated certificate.h file in main.c

Include the certificate as ca_certificate[].

static const unsigned char ca_certificate[] = {
#include "certificate.h"
};

3. Store the certificate in the device.

3.1 Define a macro for the security tag used to store the credential

#define MQTT_TLS_SEC_TAG 24

3.2 Store the credential on the device.

Now we want to store the certificate in the device using tls_credential_add() which as the following signature

• tag – The security tag associated with the certificate, in our case MQTT_TLS_SEC_TAG.
• type – The type of credential we are storing in the modem defined in tls_credential_type. To authenticate the server, we use TLS_CREDENTIAL_CA_CERTIFICATE, which is the root certificate of the server issues by the Certificate Authorities.
• cred – The actual certificate, defined in the header file certificate.h, and included as ca_certificate[].
• credlen – Length of the certificate.

Store the certificate after connection to Wi-Fi and before attempting to connect to the MQTT broker.

err = tls_credential_add(MQTT_TLS_SEC_TAG, TLS_CREDENTIAL_CA_CERTIFICATE, ca_certificate, sizeof(ca_certificate));
if (err < 0) {
	LOG_ERR("Failed to add TLS credentials, err: %d", err);
	return err;
}

4. Modify the client client_init() function to use secure TCP transport instead of non-secure TCP transport.

In main.c, replace the line below

client->transport.type = MQTT_TRANSPORT_NON_SECURE;

With the following:

struct mqtt_sec_config *tls_cfg = &(client->transport).tls.config;
static sec_tag_t sec_tag_list[] = { MQTT_TLS_SEC_TAG };

client->transport.type = MQTT_TRANSPORT_SECURE;

tls_cfg->peer_verify = TLS_PEER_VERIFY_OPTIONAL;
tls_cfg->cipher_count = 0;
tls_cfg->cipher_list = NULL;
tls_cfg->sec_tag_count = ARRAY_SIZE(sec_tag_list);
tls_cfg->sec_tag_list = sec_tag_list;
tls_cfg->session_cache = TLS_SESSION_CACHE_DISABLED;
tls_cfg->hostname = CONFIG_MQTT_BROKER_HOSTNAME;

In the above code, we are populating the mqtt_sec_config member of the MQTT client instance, which has the following members

The sec_tag_list array holds the security tag associated with the server certificate, that the MQTT library should use for authentication. We set the peer certificate verification to optional by setting the peer_verify field to TLS_PEER_VERIFY_OPTIONAL. We do not specify cipher_list, to allow the use of all cipher suites available in the system. We set the hostname field to the broker hostname, which is required for server authentication.

5. Update the file descriptor for the socket to use the TLS socket instead of a plain TCP socket.

In main(), change the following line

fds.fd = client.transport.tcp.sock;

To this line

fds.fd = client.transport.tls.sock;

6. Build the exercise and flash it on your board.

This exercise uses the PSA backend for storing the Wi-Fi credentials. Therefore, you must build with TF-M.

If necessary, connect to Wi-Fi by issuing the relevant shell commands, as we have done in the previous exercises.

On a successful connection to the Wi-Fi network and connection to the MQTT broker, you should see the same log output as we did in the previous exercise.

Testing

We will basically follow the same test procedure we used in Exercise 1, except this time we will have to configure the client to use TLS before connecting.

• Android
• iOS
• Desktop

Android

7. Launch the Mqtt Dashboard app on your smart phone.

8. Configure the MQTT client to connect using TLS.

Tap on the + symbol in the app to add a broker.

• Broker name: Any name you choose
• Address: The hostname of the MQTT broker, preceded by the transport protocol: tls://broker.hivemq.com
• Port: The port number, in this case 8883, since we are connecting over TLS.

Note

Your phone’s OS already has the necessary certificate stored so we don’t need to provide a certificate in the app.

9. Repeat steps 12 through 15 in the previous exercise to test the communication over TLS.

iOS

7. Launch the EasyMQTT app on your smart phone.

8. Configure the MQTT client to connect using TLS.

Set up the MQTT client on your phone to connect to the same MQTT broker that the board is connecting to.

In the menu at the bottom, go to the Connect tab and input the relevant information.

• Name: Any name you choose
• Host: The hostname of the MQTT broker: broker.hivemq.com
• Port: The port number, in this case 8883, since we are connecting over TLS
• TLS/SSL: Enable this option to connect over TLS

Enabling TLS/SSL will open a separate TLS menu, which should remain with the default settings.

Note

Your phone’s OS already has the necessary certificate stored so we don’t need to provide a certificate in the app.

Select the white Connect button at the bottom of the page and if the connection is successful, the following message will appear and the Connect button will turn into a Disconnect button.

9. Repeat steps 12 and 13 in the previous exercise to test the communication over TLS.

Desktop

11. Connect to an MQTT broker on your computer.

11.1 Launch MQTT Explorer on your computer.

11.2 Connect to the MQTT broker.

Add a new connection and set it up as shown in the illustration below. Note that the port number is changed to 8883. Lastly, click on Advanced, then Certificates.

11.2 Add the server root certificate.

Add the server (MQTT broker) root certificate (ca_certificate.crt) by clicking on Server Certificate (CA) and select the .crt file we downloaded in step 2.1.

Then click Back.

11.3 Subscribe to topic

In the new window, under Topic, input the topic that the device is publishing to, specified in the Kconfig CONFIG_MQTT_PUB_TOPIC. The default value is wifi/fund/board/publish/button/topic99.

Select Add, and then Back to go to the previous window where you can select Connect to connect to the broker.

12. Publish commands to the LED topic, to control the LEDs on the board.

When the connection to the broker has been established, we want to publish a command to the LED topic, to control the LED on the board.

In the panel to the right, scroll down to the bottom. Enter the topic name that the board is subscribed to (set by CONFIG_MQTT_SUB_TOPIC defined in prj.conf). The default value is wifi/fund/board/subscribe/led/topic99.

Select raw as the message type and input one of the predefined commands to control the LEDs.

LED 1: LED1ON / LED1OFF

LED 2: LED2ON / LED2OFF

Click Publish and observe that the LED on the device reflects the command you sent.

13. Monitor the buttons on the board.

We programmed the device to publish a message whenever a button was pressed and we have configured the MQTT broker connection to subscribe to the topic that the device is publishing to.

Try to press button 1 or 2 on your board and notice a message appearing on the left-side of the screen. If you expand all the sub-headings, you will find the message posted at the bottom stating which button was pressed on the device.