net: mqtt: Add support for MQTT 5.0 AUTH packet

Add support for a new AUTH message introduced in MQTT 5.0.
This is a new mechanism specified by MQTT 5.0, which allows clients and
brokers for enhanced authentication in between CONNECT and CONNACK
exchange. An additional MQTT event (MQTT_EVT_AUTH) was specified which
is triggered when the AUTH packet arrives from the broker.

Signed-off-by: Robert Lubos <robert.lubos@nordicsemi.no>

Author: rlubos

include/zephyr/net/mqtt.h

@@ -79,6 +79,9 @@ enum mqtt_evt_type {
 
 	/** Ping Response from server. */
 	MQTT_EVT_PINGRESP,
+
+	/** Authentication packet received from server. MQTT 5.0 only. */
+	MQTT_EVT_AUTH,
 };
 
 /** @brief MQTT version protocol level. */
@@ -208,6 +211,13 @@ enum mqtt_disconnect_reason_code {
 	MQTT_DISCONNECT_WILDCARD_SUB_NOT_SUPPORTED = 162,
 };
 
+/** @brief MQTT Authenticate reason codes (MQTT 5.0, chapter 3.15.2.1). */
+enum mqtt_auth_reason_code {
+	MQTT_AUTH_SUCCESS = 0,
+	MQTT_AUTH_CONTINUE_AUTHENTICATION = 24,
+	MQTT_AUTH_RE_AUTHENTICATE = 25,
+};
+
 /** @brief Abstracts UTF-8 encoded strings. */
 struct mqtt_utf8 {
 	const uint8_t *utf8;       /**< Pointer to UTF-8 string. */
@@ -602,6 +612,39 @@ struct mqtt_disconnect_param {
 #endif /* CONFIG_MQTT_VERSION_5_0 */
 };
 
+#if defined(CONFIG_MQTT_VERSION_5_0)
+struct mqtt_auth_param {
+	/* MQTT 5.0, chapter 3.15.2.1 Authenticate Reason Code */
+	enum mqtt_auth_reason_code reason_code;
+
+	struct {
+		/** MQTT 5.0, chapter 3.15.2.2.5 User Property. */
+		struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];
+
+		/** MQTT 5.0, chapter 3.15.2.2.2 Authentication Method. */
+		struct mqtt_utf8 auth_method;
+
+		/** MQTT 5.0, chapter 3.15.2.2.3 Authentication Data. */
+		struct mqtt_binstr auth_data;
+
+		/** MQTT 5.0, chapter 3.15.2.2.4 Reason String. */
+		struct mqtt_utf8 reason_string;
+
+		/** Flags indicating whether given property was present in received packet. */
+		struct {
+			/** Authentication Method property was present. */
+			bool has_auth_method;
+			/** Authentication Data property was present. */
+			bool has_auth_data;
+			/** Reason String property was present. */
+			bool has_reason_string;
+			/** User Property property was present. */
+			bool has_user_prop;
+		} rx;
+	} prop;
+};
+#endif /* CONFIG_MQTT_VERSION_5_0 */
+
 /**
  * @brief Defines event parameters notified along with asynchronous events
  *        to the application.
@@ -639,6 +682,9 @@ union mqtt_evt_param {
 #if defined(CONFIG_MQTT_VERSION_5_0)
 	/** Parameters accompanying MQTT_EVT_DISCONNECT event. */
 	struct mqtt_disconnect_param disconnect;
+
+	/** Parameters accompanying MQTT_EVT_AUTH event. */
+	struct mqtt_auth_param auth;
 #endif /* CONFIG_MQTT_VERSION_5_0 */
 };
 
@@ -1117,6 +1163,20 @@ int mqtt_ping(struct mqtt_client *client);
 int mqtt_disconnect(struct mqtt_client *client,
 		    const struct mqtt_disconnect_param *param);
 
+#if defined(CONFIG_MQTT_VERSION_5_0)
+/**
+ * @brief API to send an authentication packet to the server.
+ *
+ * @param[in] client Client instance for which the procedure is requested.
+ *                   Shall not be NULL.
+ * @param[in] param Parameters to be used for the auth message.
+ *                  Shall not be NULL.
+ *
+ * @return 0 or a negative error code (errno.h) indicating reason of failure.
+ */
+int mqtt_auth(struct mqtt_client *client, const struct mqtt_auth_param *param);
+#endif /* CONFIG_MQTT_VERSION_5_0 */
+
 /**
  * @brief API to abort MQTT connection. This will close the corresponding
  *        transport without closing the connection gracefully at the MQTT level

subsys/net/lib/mqtt/mqtt.c

@@ -577,6 +577,58 @@ int mqtt_ping(struct mqtt_client *client)
 	return err_code;
 }
 
+#if defined(CONFIG_MQTT_VERSION_5_0)
+static int verify_auth_state(const struct mqtt_client *client)
+{
+	/* Enhanced authentication is only allowed when connecting at MQTT
+	 * level (before CONNACK is received).
+	 */
+	if (MQTT_HAS_STATE(client, MQTT_STATE_TCP_CONNECTED) &&
+	    !MQTT_HAS_STATE(client, MQTT_STATE_CONNECTED)) {
+		return 0;
+	}
+
+	/* Return generic protocol error */
+	return -EPROTO;
+}
+
+int mqtt_auth(struct mqtt_client *client, const struct mqtt_auth_param *param)
+{
+	int err_code;
+	struct buf_ctx packet;
+
+	NULL_PARAM_CHECK(client);
+	NULL_PARAM_CHECK(param);
+
+	mqtt_mutex_lock(client);
+
+	if (!mqtt_is_version_5_0(client)) {
+		NET_ERR("Auth packet only supported in MQTT 5.0");
+		err_code = -ENOTSUP;
+		goto error;
+	}
+
+	tx_buf_init(client, &packet);
+
+	err_code = verify_auth_state(client);
+	if (err_code < 0) {
+		goto error;
+	}
+
+	err_code = auth_encode(param, &packet);
+	if (err_code < 0) {
+		goto error;
+	}
+
+	err_code = client_write(client, packet.cur, packet.end - packet.cur);
+
+error:
+	mqtt_mutex_unlock(client);
+
+	return err_code;
+}
+#endif /* CONFIG_MQTT_VERSION_5_0 */
+
 int mqtt_abort(struct mqtt_client *client)
 {
 	NULL_PARAM_CHECK(client);

subsys/net/lib/mqtt/mqtt_decoder.c

@@ -1078,4 +1078,65 @@ int disconnect_decode(const struct mqtt_client *client, struct buf_ctx *buf,
 
 	return 0;
 }
+
+static int auth_properties_decode(struct buf_ctx *buf,
+				  struct mqtt_auth_param *param)
+{
+	struct property_decoder prop[] = {
+		{
+			&param->prop.auth_method,
+			&param->prop.rx.has_auth_method,
+			MQTT_PROP_AUTHENTICATION_METHOD
+		},
+		{
+			&param->prop.auth_data,
+			&param->prop.rx.has_auth_data,
+			MQTT_PROP_AUTHENTICATION_DATA
+		},
+		{
+			&param->prop.reason_string,
+			&param->prop.rx.has_reason_string,
+			MQTT_PROP_REASON_STRING
+		},
+		{
+			&param->prop.user_prop,
+			&param->prop.rx.has_user_prop,
+			MQTT_PROP_USER_PROPERTY
+		}
+	};
+
+	return properties_decode(prop, ARRAY_SIZE(prop), buf);
+}
+
+int auth_decode(const struct mqtt_client *client, struct buf_ctx *buf,
+		struct mqtt_auth_param *param)
+{
+	size_t remaining_len;
+	uint8_t reason_code;
+	int err;
+
+	if (!mqtt_is_version_5_0(client)) {
+		return -ENOTSUP;
+	}
+
+	remaining_len = buf->end - buf->cur;
+
+	if (remaining_len > 0) {
+		err = unpack_uint8(buf, &reason_code);
+		if (err < 0) {
+			return err;
+		}
+
+		param->reason_code = reason_code;
+	}
+
+	if (remaining_len > 1) {
+		err = auth_properties_decode(buf, param);
+		if (err < 0) {
+			return err;
+		}
+	}
+
+	return 0;
+}
 #endif /* CONFIG_MQTT_VERSION_5_0 */

subsys/net/lib/mqtt/mqtt_encoder.c

@@ -1480,3 +1480,109 @@ int ping_request_encode(struct buf_ctx *buf)
 
 	return 0;
 }
+
+#if defined(CONFIG_MQTT_VERSION_5_0)
+static uint32_t auth_properties_length(const struct mqtt_auth_param *param)
+{
+	return string_property_length(&param->prop.auth_method) +
+	       binary_property_length(&param->prop.auth_data) +
+	       string_property_length(&param->prop.reason_string) +
+	       user_properties_length(param->prop.user_prop);
+}
+
+static int auth_properties_encode(const struct mqtt_auth_param *param,
+				  struct buf_ctx *buf)
+{
+	uint32_t properties_len;
+	int err;
+
+	/* Precalculate total properties length */
+	properties_len = auth_properties_length(param);
+	if (properties_len == 0) {
+		return 0;
+	}
+
+	err = pack_variable_int(properties_len, buf);
+	if (err < 0) {
+		return err;
+	}
+
+	err = encode_string_property(MQTT_PROP_AUTHENTICATION_METHOD,
+				     &param->prop.auth_method, buf);
+	if (err < 0) {
+		return err;
+	}
+
+	err = encode_binary_property(MQTT_PROP_AUTHENTICATION_DATA,
+				     &param->prop.auth_data, buf);
+	if (err < 0) {
+		return err;
+	}
+
+	err = encode_string_property(MQTT_PROP_REASON_STRING,
+				     &param->prop.reason_string, buf);
+	if (err < 0) {
+		return err;
+	}
+
+	err = encode_user_properties(param->prop.user_prop, buf);
+	if (err < 0) {
+		return err;
+	}
+
+	return 0;
+}
+
+static int empty_auth_encode(struct buf_ctx *buf)
+{
+	const uint8_t empty_auth_packet[] = {
+		MQTT_PKT_TYPE_AUTH,
+		0x00
+	};
+	uint8_t *cur = buf->cur;
+	uint8_t *end = buf->end;
+
+	if ((end - cur) < sizeof(empty_auth_packet)) {
+		return -ENOMEM;
+	}
+
+	memcpy(cur, empty_auth_packet, sizeof(empty_auth_packet));
+	buf->end = (cur + sizeof(empty_auth_packet));
+
+	return 0;
+}
+
+int auth_encode(const struct mqtt_auth_param *param, struct buf_ctx *buf)
+{
+	const uint8_t message_type =
+		MQTT_MESSAGES_OPTIONS(MQTT_PKT_TYPE_AUTH, 0, 0, 0);
+	uint8_t *start;
+	int err;
+
+	/* Reserve space for fixed header. */
+	buf->cur += MQTT_FIXED_HEADER_MAX_SIZE;
+	start = buf->cur;
+
+	if ((param->reason_code == MQTT_AUTH_SUCCESS) &&
+	    (auth_properties_length(param) == 0U)) {
+		return empty_auth_encode(buf);
+	}
+
+	err = pack_uint8(param->reason_code, buf);
+	if (err < 0) {
+		return err;
+	}
+
+	err = auth_properties_encode(param, buf);
+	if (err != 0) {
+		return err;
+	}
+
+	err = mqtt_encode_fixed_header(message_type, start, buf);
+	if (err != 0) {
+		return err;
+	}
+
+	return 0;
+}
+#endif /* CONFIG_MQTT_VERSION_5_0 */

subsys/net/lib/mqtt/mqtt_internal.h

@@ -54,6 +54,7 @@ extern "C" {
 #define MQTT_PKT_TYPE_PINGREQ     0xC0
 #define MQTT_PKT_TYPE_PINGRSP     0xD0
 #define MQTT_PKT_TYPE_DISCONNECT  0xE0
+#define MQTT_PKT_TYPE_AUTH        0xF0
 
 /**@brief MQTT Property Types. */
 #define MQTT_PROP_PAYLOAD_FORMAT_INDICATOR          0x01
@@ -346,6 +347,20 @@ int unsubscribe_encode(const struct mqtt_client *client,
  */
 int ping_request_encode(struct buf_ctx *buf);
 
+#if defined(CONFIG_MQTT_VERSION_5_0)
+/**@brief Constructs/encodes Authenticate packet.
+ *
+ * @param[in] param Authenticate message parameters.
+ * @param[inout] buf_ctx Pointer to the buffer context structure,
+ *                       containing buffer for the encoded message.
+ *                       As output points to the beginning and end of
+ *                       the frame.
+ *
+ * @return 0 if the procedure is successful, an error code otherwise.
+ */
+int auth_encode(const struct mqtt_auth_param *param, struct buf_ctx *buf);
+#endif /* CONFIG_MQTT_VERSION_5_0 */
+
 /**@brief Decode MQTT Packet Type and Length in the MQTT fixed header.
  *
  * @param[inout] buf A pointer to the buf_ctx structure containing current
@@ -469,6 +484,18 @@ int unsubscribe_ack_decode(const struct mqtt_client *client, struct buf_ctx *buf
  */
 int disconnect_decode(const struct mqtt_client *client, struct buf_ctx *buf,
 		      struct mqtt_disconnect_param *param);
+
+/**@brief Decode MQTT Auth packet.
+ *
+ * @param[in] MQTT client for which packet is decoded.
+ * @param[inout] buf A pointer to the buf_ctx structure containing current
+ *                   buffer position.
+ * @param[out] param Pointer to buffer for decoded Auth parameters.
+ *
+ * @return 0 if the procedure is successful, an error code otherwise.
+ */
+int auth_decode(const struct mqtt_client *client, struct buf_ctx *buf,
+		struct mqtt_auth_param *param);
 #endif /* CONFIG_MQTT_VERSION_5_0 */
 
 /**

subsys/net/lib/mqtt/mqtt_rx.c

@@ -154,6 +154,17 @@ static int mqtt_handle_packet(struct mqtt_client *client,
 			notify_event = false;
 		}
 
+		break;
+
+	case MQTT_PKT_TYPE_AUTH:
+		evt.type = MQTT_EVT_AUTH;
+		err_code = auth_decode(client, buf, &evt.param.auth);
+		if (err_code == 0) {
+			evt.result = evt.param.auth.reason_code;
+		} else {
+			notify_event = false;
+		}
+
 		break;
 #endif