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 :
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 PC).
The MQTT helper library uses the TLS credentials subsystem of the Zephyr socket API to provision the credentials on the device at run-time. So we simply have to enable and configure this feature and store the server certificate from the MQTT broker somewhere in the application directory so the MQTT helper library can find it.
Exercise steps
In the GitHub repository for this course, go to the base code for this exercise, found in l4/l4_e2.
1. Enable TLS support in the MQTT library.
1.1 Enable TLS for the MQTT library by enabling CONFIG_MQTT_LIB_TLS in prj.conf.
CONFIG_MQTT_LIB_TLS=yThis will automatically change the broker port CONFIG_MQTT_HELPER_PORT that the MQTT helper library uses to 8883, which is the standard TLS port for MQTT.
1.2 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=yCONFIG_NET_SOCKETS_SOCKOPT_TLS: Enables the TLS socket options in the sockets API. This Kconfig will also selectCONFIG_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, which is the encryption used in the server certificate of the broker we want to connect to.
1.3 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 2. Change the broker hostname.
The nRF70 Series DK does not support the encryption used by the server certificate issued by mqtt.nordicsemi.academy, so in this exercise we will connect to a public broker instead, broker.hivemq.com.
Change the broker hostname by setting the Kconfig CONFIG_MQTT_SAMPLE_BROKER_HOSTNAME in the prj.conffile
CONFIG_MQTT_SAMPLE_BROKER_HOSTNAME="broker.hivemq.com"3. Configure the certificate in the MQTT helper library.
The MQTT helper handles issuing the certificate to the device, we just need to enable run-time provisioning, set the security tag and the path where the certificate is stored.
CONFIG_MQTT_HELPER_SEC_TAG=24
CONFIG_MQTT_HELPER_CERTIFICATES_FOLDER="src/credentials"CONFIG_MQTT_HELPER_SEC_TAG: Security tag where the TLS credentials are stored on the deviceCONFIG_MQTT_HELPER_CERTIFICATES_FOLDER: The default path for the folder that contains credentials, relative to the application source directory
Important
Enabling run-time provisioning of certificates is only intended for testing and should not be used in a production scenario. Enabling this option means that the credentials used in the TLS communication towards the server will be exposed in flash memory.
4. Obtain the certificate from the MQTT broker.
4.1 Open a browser and go to broker.hivemq.com.
Although the hostname redirects to mqtt-dashboard.com in the browser, the domain name has the same certificate chain as the MQTT broker.
Note
The images and descriptions in this step are taken from Google Chrome. This may vary depending on the Internet browser you are using.
4.2 Click on the lock besides the URL, go to Connection is secure and then Certificate is valid.
A Certificate Viewer should open.
4.3 Go to Details and under Certificate Hierarchy select the top most certificate. Then select Export.
4.4 Save the certificate in l4/l4_e2/src/credentials as ca-cert.pem.
- Path: The path where we store the credentials need to match the path we set in
CONFIG_MQTT_HELPER_CERTIFICATES_FOLDER, which is where the MQTT helper library will look. - File name: The file name of the server certificate has to be
ca-cert.pem, this is what the MQTT helper library expects.
5. 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.
| Board | Build with TF-M | Extra CMake arguments |
|---|---|---|
| nRF7002 DK | nrf7002dk/nrf5340/cpuapp/ns | N/A |
| nRF5340 DK + nRF7002 EK | nrf5340dk/nrf5340/cpuapp/ns | -DSHIELD=nrf7002ek |
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.
6. Connect to an MQTT broker on your computer.
6.1 Launch MQTT Explorer on your computer.
6.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.
6.2 Add the server root certificate.
Add the server (MQTT broker) root certificate (ca-cert.pem) by clicking on Server Certificate (CA) and select the .pem file we downloaded in a previous step.
Then click Back.
6.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_SAMPLE_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.
7. 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_SAMPLE_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.
8. 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.
