Category: Mongoose-OS Notes, featuring the ESP32

This article is an extension to this one; I suggest you read it first.

Should you need more information on the MQTT client and using it with no TLS, read this article. For a bit more on TLS, this one.

TLS-PSK

There is a simpler solution to using full-blown TLS as we’ve seen on our first article; instead of using certificates, broker and connecting device can have a pre-shared key (PSK).

The connection process is similar, but in this case, instead of validating certificates and generating a derived key, the process starts with the pre-shared key. Depending on the scheme being used, demanding Public Key Cryptography operations can be avoided, and key management logistics can be a bit simpler, plus, we don’t need a CA (Certification Authority) anymore.

Even though there are currently three different ways to work, where one of these allows broker validation using certificates and device validation using a PSK, we’ve only tested the simplest form.

Configuration

Let’s configure the ESP32 running Mongoose-OS to use TLS-PSK.

libs:
  - origin: https://github.com/mongoose-os-libs/mqtt  # Include the MQTT client
config_schema:
  - ["mqtt.enable", true]             # Enable the MQTT client
  - ["mqtt.server", "address:port"]   # Broker IP address (and port)
  - ["mqtt.ssl_psk_identity", "bob"]  # identity to use for our key
  - ["mqtt.ssl_psk_key", "000000000000000000000000deadbeef"] # key AES-128 (or 256)
  - ["mqtt.ssl_cipher_suites", "TLS-PSK-WITH-AES-128-CCM-8:TLS-PSK-WITH-AES-128-GCM-SHA256:TLS-ECDHE-PSK-WITH-AES-128-CBC-SHA256:TLS-PSK-WITH-AES-128-CBC-SHA"] # cipher suites

The most common port for MQTT over TLS-PSK is 8883. The broker can also request we send a username and password, though the usual stuff is to configure it to take advantage of the identity we’re already sending, as we did on these tests (example below).

Regarding cipher suites, we need to provide a set of cryptographic schemes supported by our device, and at least one of them must also be supported by the broker. This is a mandatory parameter, otherwise our device won’t announce any TLS-PSK compatible cipher suite and TLS connection will not take place. Usually we negotiate this with the broker admins.

When starting the TLS connection, the device sends its supported cipher suites in its ClientHello message; the broker then chooses one that it supports and indicates this on its ServerHello message. As we’ve obtained this list by analyzing the source code, we decided to publish it here so it can be of use. In our particular case, only one of the device cipher suites was also supported by the broker: TLS-PSK-WITH-AES-128-CCM-8. The start handshake with these messages can be seen at the Wireshark snapshot below.

Finally, our pre-shared key (PSK, parameter ssl_psk_key) must be a 128-bit (16-byte) quantity for AES-128 suites and a 256-bit (32-byte) quantity for AES-256 suites.

Operation

At startup, we’ll watch the log and check if everything is going on as it should, or catch any possible errors. In this sad case, it is pretty hard to properly determine what is going on without a sniffer, as both sides are often not very verbose nor precise. The handshake, as well as the MQTT messages inside TLS, can be observed with a sniffer, by introducing the proper key (see the example using Wireshark below).

[Mar 31 17:28:32.349] mgos_mqtt_conn.c:435    MQTT0 connecting to 192.168.5.3:8883
[Mar 31 17:28:32.368] mongoose.c:4906         0x3ffc76ac ciphersuite: TLS-PSK-WITH-AES-128-CBC-SHA
[Mar 31 17:28:32.398] mgos_mqtt_conn.c:188    MQTT0 TCP connect ok (0)
[Mar 31 17:28:32.411] mgos_mqtt_conn.c:235    MQTT0 CONNACK 0
[Mar 31 17:28:32.420] init.js:34              MQTT connected
[Mar 31 17:28:32.434] init.js:26              Published:OK topic:/this/test/esp32_807A98 msg:CONNECTED!

Brokers: Mosquitto

This is a minimal configuration for Mosquitto, take it as a quick help and not as a reference. Paths are in GNU/Linux form and we should put our keys there.

listener 8883 192.168.5.1
log_dest syslog
use_identity_as_username true # so the broker does not ask for username in the MQTT header
psk_file /etc/mosquitto/pskfile
psk_hint cualquiera           # any name

Parameter psk_hint serves as a hint for the client on which identity to use, in case it connects to several places; we don’t use it in this example.

The file pskfile must contain each identity and its corresponding pre-shared key; for example, for our user bob:

bob:000000000000000000000000deadbeef

Example

Companion example code available in Github.

Sniffers: Wireshark

With any sniffer we are able to see the TLS traffic, but not its payload

With Wireshark, we can decrypt TLS-PSK entering the desired pre-shared key in Edit->Preferences->Protocols->TLS->Pre-Shared-Key.

We are then able to see MQTT traffic as TLS payload.

Este artículo es una extensión de este otro; te recomiendo que lo veas primero.

Para mayor información sobre el cliente MQTT y la operación sin TLS, existe este artículo. Para más información sobre TLS, éste.

TLS-PSK

Existe una solución un poco más simple a la que vimos en el primer artículo; consiste en utilizar, en vez de certificados, una clave pre-compartida entre el broker y el dispositivo que se conecta.

El proceso de conexión es similar al empleado con certificados, sólo que en vez de validarse éstos y luego generarse una clave derivada, se utiliza como punto de partida la clave pre-compartida. Según el esquema utilizado, se evitan las costosas operaciones de clave pública/privada (Public Key Cryptography), y la logística de manejo de claves suele ser más simple, además del hecho de no requerir una CA (Certification Authority).

Si bien existen al momento tres formas de operar, una de las cuales permite validar al broker mediante certificados y al dispositivo mediante clave pre-compartida (PSK), sólo hemos probado la forma simple.

Configuración

Configuramos el ESP32 con Mongoose-OS para operar mediante TLS-PSK.

libs:
  - origin: https://github.com/mongoose-os-libs/mqtt  # incorpora el cliente MQTT
config_schema:
  - ["mqtt.enable", true]             # Habilita el cliente MQTT
  - ["mqtt.server", "address:port"]   # Dirección IP del broker a utilizar
  - ["mqtt.ssl_psk_identity", "bob"]  # identidad para la clave elegida
  - ["mqtt.ssl_psk_key", "000000000000000000000000deadbeef"] # clave AES-128 (ó 256)
  - ["mqtt.ssl_cipher_suites", "TLS-PSK-WITH-AES-128-CCM-8:TLS-PSK-WITH-AES-128-GCM-SHA256:TLS-ECDHE-PSK-WITH-AES-128-CBC-SHA256:TLS-PSK-WITH-AES-128-CBC-SHA"] # claves utilizables

El puerto comúnmente utilizado es 8883. El broker puede además solicitar que utilicemos nombre de usuario y password, aunque lo más común es configurarlo para aprovechar la identidad que se envía, como hicimos para estas pruebas (ejemplo más abajo).

Respecto a las cipher suites, se trata de indicar un conjunto de esquemas criptográficos que el sistema soporta y entre ellos debemos acertar a elegir uno que esté soportado por el broker. Este parámetro es obligatorio, sin él el dispositivo no anuncia ningún esquema criptográfico compatible con TLS-PSK y la conexión TLS no se establece. Lo habitual es acordarlo con el administrador del broker.

Al iniciar la conexión TLS, el dispositivo incluye los esquemas soportados en el mensaje ClientHello; el broker elige uno compatible y lo indica en el mensaje ServerHello. Dado que esta lista la obtuvimos analizando el código fuente, decidimos publicarla aquí para mayor utilidad. En nuestro caso en particular sólo uno de los esquemas coincidió con los disponibles en el broker: TLS-PSK-WITH-AES-128-CCM-8. El handshake de inicialización conteniendo estos mensajes puede observarse en la captura Wireshark que figura más abajo.

Por último, la clave pre-compartida (PSK, parámetro ssl_psk_key) debe tener una longitud de 128-bits (16-bytes) para sets basados en AES-128 y de 256-bits (32-bytes) para sets basados en AES-256.

Operación

Al iniciar el procesador, observaremos en el log si todo funciona como debe, o los errores que se hayan producido. En este último caso, resulta bastante difícil determinar las causas sin un sniffer dado que las pistas de ambos lados no suelen ser muy precisas. Tanto el handshake como la operación MQTT dentro de TLS pueden observarse en un sniffer, ingresando dicha clave en el mismo (por ejemplo Wireshark, ejemplo más abajo).

[Mar 31 17:28:32.349] mgos_mqtt_conn.c:435    MQTT0 connecting to 192.168.5.3:8883
[Mar 31 17:28:32.368] mongoose.c:4906         0x3ffc76ac ciphersuite: TLS-PSK-WITH-AES-128-CBC-SHA
[Mar 31 17:28:32.398] mgos_mqtt_conn.c:188    MQTT0 TCP connect ok (0)
[Mar 31 17:28:32.411] mgos_mqtt_conn.c:235    MQTT0 CONNACK 0
[Mar 31 17:28:32.420] init.js:34              MQTT connected
[Mar 31 17:28:32.434] init.js:26              Published:OK topic:/this/test/esp32_807A98 msg:CONNECTED!

Brokers: Mosquitto

Detallamos, a modo instructivo y como ayuda rápida, la configuración mínima necesaria para operar en Mosquitto. El path está en formato GNU/Linux y se espera que pongamos nuestro archivo con las claves allí.

listener 8883 192.168.5.1
log_dest syslog
use_identity_as_username true # evitamos que requiera usuario en el header MQTT
psk_file /etc/mosquitto/pskfile
psk_hint cualquiera           # cualquier nombre

El parámetro psk_hint, en el caso que el cliente se conecte a varios lugares, le da un indicio (hint) de qué identidad utilizar para identificarse. No tiene utilidad en nuestro caso.

El archivo pskfile, por su parte, debe contener las identidades y claves pre-compartidas; por ejemplo, para el usuario bob:

bob:000000000000000000000000deadbeef

Ejemplo

El código de ejemplo se encuentra en Github.

Sniffers: Wireshark

En todo sniffer, veremos el tráfico TLS pero no lo que éste transporta

En Wireshark, poder decodificar el tráfico TLS-PSK es tan simple como ingresar la clave compartida en Edit->Preferences->Protocols->TLS->Pre-Shared-Key.

El sniffer es entonces capaz de descifrar el contenido y nos permite observar el tráfico MQTT.

Mongoose-OS has a built-in MQTT client and a simple mJS (a reduced JavaScript) interpreter. These tools allow us to quickly and easily connect to an MQTT broker and perform our proof-of-concept tests for more complex applications.

Configuration

We’ll configure the ESP32 running Mongoose-OS to use the MQTT client and connect to a WiFi network. Since we are going to connect to a server (the MQTT broker), this is perhaps the simplest and fastest way to run our tests. This action can be done manually using RPCs (Remote Procedural Calls), writing a JSON config file, or it can be defined in the YAML file that describes how the project will be built. We’ve chosen this last option for our tests.

libs:
  - origin: https://github.com/mongoose-os-libs/mqtt  # Include the MQTT client
config_schema:
  - ["mqtt.enable", true]            # Enable the MQTT client
  - ["mqtt.server", "address:port"]  # Broker IP address (and port)

The most common port for MQTT is 1883. The broker can also ask us to send a username and password, full configuration details are available at the corresponding Mongoose-OS doc page.

Operation

Before we build our project and execute our code, it is perhaps convenient to have an MQTT client connected to the broker, so we can see the message the device will send at connect time. We’ve used a broker we installed in a server in our lab:

$ mosquitto_sub -h mqtt.lab -p 1883 -t "#" -v

In addition (if daily traffic allows), it is also possible to use Eclipse’s open MQTT broker, in that case we should be a bit more specific in the topic we subscribe to, in order to try to receive only our messages

$ mosquitto_sub -h mqtt.eclipseprojects.io -p 1883 -t "/this/#" -v

After the code is compiled and linked (mos build) and the microcontroller’s flash is programmed (mos flash) using mos tool, we’ll watch the log and check if everything is going on as it should, or catch any possible errors. Remember we need to configure the proper access credentials to connect to our WiFi network of choice (SSID and password), and the address and port for the MQTT broker we are going to use.

[Feb 11 15:19:42.353] mgos_mqtt_conn.c:435    MQTT0 connecting to mqtt.sensors.lab:1883
[Feb 11 15:19:42.370] mgos_mqtt_conn.c:188    MQTT0 TCP connect ok (0)
[Feb 11 15:19:42.380] mgos_mqtt_conn.c:235    MQTT0 CONNACK 0
[Feb 11 15:19:42.385] mgos_mqtt_conn.c:168    MQTT0 sub /this/sub @ 1
[Feb 11 15:19:42.393] init.js:38              MQTT connected
[Feb 11 15:19:42.407] init.js:26              Published:OK topic:/this/pub/esp32_807A98 msg:CONNECTED!

At this time we’ll see that message in our MQTT client window:

$ mosquitto_sub -h mqtt.lab -p 1883 -t "#" -v
/this/pub/esp32_807A98 CONNECTED!

Then, we can send a message to our device by publishing to the topic to which it is subscribed:

$ mosquitto_pub -t /this/sub -h mqtt.lab -m "This message"

At this time we’ll see that message in our MQTT client window:

$ mosquitto_sub -h mqtt.lab -p 1883 -t "#" -v
/this/pub/esp32_807A98 CONNECTED!
/this/sub This message

and in our device’s log

[Feb 11 15:20:02.647] init.js:32              Got a msg: This message

Finally, we’ll power off our ESP32 and after a while (minutes) the broker will detect the disconnection; at that time we’ll see the last-will message in our MQTT client window

$ mosquitto_sub -h mqtt.lab -p 1883 -t "#" -v
/this/pub/esp32_807A98 CONNECTED!
/this/sub This message
/this/test lost

The mJS code

Whenever we want to publish a message, we’ll call MQTT.pub(). There’s no need to wait nor perform any handshakes, just invoke that method and see the results. Internally, the message is queued and will be sent as soon as possible; the value returned by the publishing method is an indicator of the result of the queuing action, not the actual transmission of the message.

This article has companion code, there we’ve written a simple function as a usage example:

let publish = function (topic, msg) {
    let ok = MQTT.pub(topic, msg, 1, false); // QoS = 1, do not retain
    Log.print(Log.INFO, 'Published:' + (ok ? 'OK' : 'FAIL') + ' topic:' + topic + ' msg:' +  msg);
    return ok;
};

let device_id = Cfg.get('device.id');
publish('/this/pub/'+device_id,'CONNECTED!');

Should we want our message to be retained, the fourth parameter for the MQTT.pub() method call must be true.

To receive messages, we subscribe to the desired topic invoking the MQTT.sub() method. Its second parameter is a handler for a callback function that will be run when we get a message. The following example can also be found in the companion code:

MQTT.sub('/this/sub', function(conn, topic, msg) {
    Log.print(Log.INFO, 'Got a msg: ' + msg);
}, null);

Last-will messages

If we want to configure a “last-will message”, that is, a message that will be published by the broker in our behalf when it detects we are no longer connected, we can do it this way:

  - ["mqtt.will_topic", "/this/test"]
  - ["mqtt.will_message", "lost"]

For some applications it is required that this message is also retained by the broker, so if other clients connect after we disconnected and before we reconnect, they can receive that message, which will in turn inform them that we are not available at that time.

  - ["mqtt.will_retain", true]

Retain, persistence

Message retention (be them last-will or common messages with the retain flag set) requires an MQTT broker with persistence capability, that is, with a database in which to store the latest messages that have been marked as persistent in every topic and send them to whoever client subscribes to that topic when it does so.

In our case, we’ve used Eclipse Mosquitto as our broker, but there are other available options.

When using Mosquitto, to configure persistence we need to add

persistence true

to the config file (if we search for it, we’ll find it). It is also possible that we have to add the name and path to the persistence database (paths in GNU/Linux environment form):

persistence_file mosquitto.db
persistence_location /var/lib/mosquitto/

but that will depend on our distro, it may already be configured as default. The user running the Mosquitto process has to have write permission on this database.

Example

The companion example code is available at Github.

Mongoose-OS incorpora un cliente MQTT y un simple intérprete mJS (una versión reducida de JavaScript). Con ellos podemos rápida y fácilmente conectarnos a un broker MQTT y realizar pruebas de concepto de aplicaciones más complejas.

Configuración

Configuramos el ESP32 con Mongoose-OS para tener un cliente MQTT y conectarse como cliente a una red WiFi. Dado que debemos conectarnos a un servidor, ésta nos resulta la forma tal vez más rápida y simple de realizar las pruebas y explicar la operación. La configuración puede realizarse manualmente mediante RPC, en un archivo de configuración JSON; o definirla en el archivo YAML que describe el proyecto. Para las pruebas elegimos esta última opción.

libs:
  - origin: https://github.com/mongoose-os-libs/mqtt  # incorpora el cliente MQTT
config_schema:
  - ["mqtt.enable", true]            # Habilita el cliente MQTT
  - ["mqtt.server", "address:port"]  # Dirección IP del broker a utilizar

El puerto comúnmente utilizado es 1883. El broker puede además solicitar que utilicemos nombre de usuario y password, los detalles de la configuración completa los podemos encontrar en la página de Mongoose-OS.

Operación

Antes de compilar y ejecutar, es conveniente tener un cliente conectado al broker para poder observar el mensaje enviado al momento de conexión. Hemos utilizado un broker instalado en nuestro lab:

$ mosquitto_sub -h mqtt.lab -p 1883 -t "#" -v

También (si el tráfico habitual lo permite) es posible usar el broker abierto de Eclipse , en cuyo caso deberemos limitar un poco el tópico a suscribirnos a fin de intentar recibir sólo nuestros mensajes

$ mosquitto_sub -h mqtt.eclipseprojects.io -p 1883 -t "/this/#" -v

Luego de compilado el código (mos build) y grabado el microcontrolador (mos flash) mediante mos tool, observaremos en el log si todo funciona como debe, o los errores que se hayan producido. Recordemos que debemos configurar las credenciales para conectarnos por WiFi a nuestra red (SSID y clave) y la dirección y port del broker MQTT que vayamos a utilizar.

[Feb 11 15:19:42.353] mgos_mqtt_conn.c:435    MQTT0 connecting to mqtt.sensors.lab:1883
[Feb 11 15:19:42.370] mgos_mqtt_conn.c:188    MQTT0 TCP connect ok (0)
[Feb 11 15:19:42.380] mgos_mqtt_conn.c:235    MQTT0 CONNACK 0
[Feb 11 15:19:42.385] mgos_mqtt_conn.c:168    MQTT0 sub /this/sub @ 1
[Feb 11 15:19:42.393] init.js:38              MQTT connected
[Feb 11 15:19:42.407] init.js:26              Published:OK topic:/this/pub/esp32_807A98 msg:CONNECTED!

En este momento observaremos el mensaje en nuestro cliente:

$ mosquitto_sub -h mqtt.lab -p 1883 -t "#" -v
/this/pub/esp32_807A98 CONNECTED!

A continuación, enviamos un mensaje a nuestro dispositivo publicando uno en el tópico al que éste se halla suscripto:

$ mosquitto_pub -t /this/sub -h mqtt.lab -m "This message"

En este momento observaremos el mensaje en nuestro cliente

$ mosquitto_sub -h mqtt.lab -p 1883 -t "#" -v
/this/pub/esp32_807A98 CONNECTED!
/this/sub This message

y en el log de nuestro dispositivo

[Feb 11 15:20:02.647] init.js:32              Got a msg: This message

Finalmente, apagamos nuestro ESP32 y al cabo de unos minutos el broker detectará la desconexión; en ese momento observaremos el mensaje “de última voluntad” en nuestro cliente

$ mosquitto_sub -h mqtt.lab -p 1883 -t "#" -v
/this/pub/esp32_807A98 CONNECTED!
/this/sub This message
/this/test lost

El código mJS

Cuando queremos publicar algo, invocamos el método MQTT.pub(). No debemos esperar ni hacer handshakes, sólo llamarlo y observar el resultado. Internamente el mensaje es puesto en una cola, de donde saldrá cuando sea posible. El valor devuelto indica que ha sido posible encolar el mensaje, no que éste ha llegado a destino. En el código que acompaña a este artículo creamos una función como ejemplo de uso:

let publish = function (topic, msg) {
    let ok = MQTT.pub(topic, msg, 1, false); // QoS = 1, do not retain
    Log.print(Log.INFO, 'Published:' + (ok ? 'OK' : 'FAIL') + ' topic:' + topic + ' msg:' +  msg);
    return ok;
};

let device_id = Cfg.get('device.id');
publish('/this/pub/'+device_id,'CONNECTED!');

Si queremos que el mensaje sea retenido, el cuarto parámetro de MQTT.pub() debe ser verdadero.

Para recibir mensajes, nos suscribimos al tópico deseado usando el método MQTT.sub(). El segundo parámetro es un handler a una función callback que se ejecutará cuando recibamos un mensaje. En el código que acompaña a este artículo mostramos un ejemplo de uso:

MQTT.sub('/this/sub', function(conn, topic, msg) {
    Log.print(Log.INFO, 'Got a msg: ' + msg);
}, null);

Last will, mensajes “de última voluntad”

Si deseamos configurar una “última voluntad”, es decir, un mensaje que el broker publicará por nosotros ante la detección de una desconexión, podemos hacerlo como se ve a continuación:

  - ["mqtt.will_topic", "/this/test"]
  - ["mqtt.will_message", "lost"]

En algunas aplicaciones es necesario que este mensaje sea retenido por el broker, de modo que otros clientes que se conecten luego de nuestra desconexión y antes de nuestra reconexión puedan recibir dicho mensaje, que por lo general tiene la misión de indicar que no estamos disponibles.

  - ["mqtt.will_retain", true]

Retain, persistencia

La retención de mensajes (sean “de última voluntad” o mensajes corrientes con el flag retain seteado) requiere de un broker MQTT con capacidad de persistencia (persistence), es decir, con una base de datos que almacene los últimos mensajes marcados como persistentes y los retransmita a quien se suscribe al tópico correspondiente al momento de iniciar la suscripción.

En nuestro caso hemos utilizado como broker Eclipse Mosquitto, pero hay otras opciones.

En el caso de Mosquitto, para configurar la persistencia debemos agregar

persistence true

en el archivo de configuración (si lo buscamos lo encontramos). También es posible que además debamos agregar el nombre y ubicación de la base de datos de persistencia (paths en formato ambiente GNU/Linux):

persistence_file mosquitto.db
persistence_location /var/lib/mosquitto/

pero eso depende de la distribución que utilicemos, por lo que puede que ya esté hecho por defecto. El usuario bajo el cual se ejecuta el proceso debe tener permisos de escritura a esta base de datos.

Ejemplo

El código de ejemplo se encuentra en Github.