Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/peterwaher/hardenmqtt

This project is aimed at students learning IoT communication over MQTT, as well as teachers, and how to harden their implementations so they avoid most common mistakes and vulnerabilities when using MQTT.
https://github.com/peterwaher/hardenmqtt

cybersecurity iot mqtt

Last synced: 3 days ago
JSON representation

Host: GitHub
URL: https://github.com/peterwaher/hardenmqtt
Owner: PeterWaher
License: mit
Created: 2022-11-25T17:23:05.000Z (almost 2 years ago)
Default Branch: main
Last Pushed: 2024-08-16T20:47:02.000Z (3 months ago)
Last Synced: 2024-08-16T21:22:52.406Z (3 months ago)
Topics: cybersecurity, iot, mqtt
Language: C#
Homepage:
Size: 1.25 MB
Stars: 7
Watchers: 2
Forks: 4
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE.md

Awesome Lists containing this project

README

Harden MQTT
================

This project is aimed at students learning IoT communication over MQTT, as well as teachers, helping them to harden their
implementations so they avoid most common mistakes and vulnerabilities when using MQTT. It shows how to use MQTT to transmit
sensor data in the following ways:

* Unsecured
* Unstructured
* Structured
* Interoperable
* Secured
* Cryptographically Signed & public
* Signed and encrypted

Signatures are based on public key cryptography, where public keys are transmitted over MQTT as well, and private keys are used
to sign information being published. The Twisted Edwards Curve `Ed25519` is used in these examples.

For encryption to be done, a hybrid cipher is used, where the asymetric ciphers (`Ed25519`) are used to derive shared secrets
using `EdDSA` and `SHA3-256`. These shared secrets are then used by a symmetric cipher (`AES-256`). As these shared secrets are
never transmitted, they can be used to securely to encrypt the content being communicated.

To achieve this level of encryption, pairing of devices and sensors have to be performed. This is also done publicly, but
securely over MQTT, highlighting the fact that malicious users can have access to the pairing process as well, if able to.
Public key cryptography and signatures are vital for the pairing process to be secured.

**Note**: The curve `Ed25519` with the corresponding `EdDSA` algorithm can be easily replaced by any other Elliptic Curve
or asymetric cipher with a corresponding algorithm for signing and generating shared keys. Likewise, the `AES-256` cipher can
be easily replaced by any other symmetric cipher, as soon as both parties have agreed on ciphers to be used. Cipher negotiation
is not included in the Pairing process however, but can be easily added.

Projects
---------

This repository consists of the following projects. They are developed in C#.

| Project | Description |
|:-------------------|:------------|
| [Sensor](Sensor) | A command-line app that represents a simple sensor that gets its values from the Internet and publishes it on an MQTT Broker. It publishes the information in five different ways: Unstructured, Structured, Interoperable (first three unsecured), and public, Confidential (last two secured). |
| [Display](Display) | A command-line app that acts as a display for sensor information published by the Sensor project. It displays information generated by all five methods transmitted. |
| [Troll](Troll) | A command-line app that spies on communication and tries to prohibit or alter information sent by sensors connected on the MQTT broker. Run this on the same broker as the sensor and display applications, to make it difficult for them to operate. |
| [Pairing](Pairing) | A class library that helps with the task of pairing two devices securely, over MQTT. |
| [Monitor](Monitor) | A Windows application (WPF) that helps you monitor communication on an MQTT broker in real-time. |

The [Sensor](Sensor), [Display](Display) and [Troll](Troll) are .NET Core command-line applications, and can run on any platform
or operating system supporting .NET Core. The [Monitor](Monitor) is a .NET Core WPF application.

### Sensor

The [Sensor](Sensor) project gets weather information from a location of your choice, using the Open Weather Map API. Following
is the process When starting the application:

1. First, it will first ask you for a Device ID. This ID is used in all event logging and pairing communication, to help you
identify the different actors.
2. Private and public keys are loaded, or generated.
3. The it asks your for connection details to an MQTT broker. All information you provide will be persisted. You only have to
provide it once.
4. A Open Weather Map API key and location to use. You can [get an API key](https://openweathermap.org/api) for free.
5. Once information has been provided, the program will read the weather once a minute and publish it on the MQTT broker.
6. Once sampling has begin, pairing is commenced, if pairing with a display has not been performed earlier. Pairing allows the
sensor to send information confidentially to a specified recipient, without others being able to detect what information has
been sent. Pairing is done securely over MQTT using `EdDSA`.
7. The main loop simply waits for you to press `CTRL+Z` to quit the application.

The following topics will be used by the sensor, on the MQTT broker you've selected:

| Topic | Description |
|:--------------------------------------|:------------|
| `HardenMqtt/Events` | Events will be logged to this topic, as well as to the console screen, so you can follow what happens with all applications connected to the broker. |
| `HardenMqtt/Unsecured/Unstructured/+` | Weather information will be published in an unstructured manner to a series of topics, one field per topic, using this topic pattern. |
| `HardenMqtt/Unsecured/Structured` | The information will also be published to this topic, in the form of a JSON object. |
| `HardenMqtt/Unsecured/Interoperable` | A more interoperable, loosely coupled XML format containing the weather information will be published to this topic. |
| `HardenMqtt/Secured/Public` | A cryptographically signed version of the interoperable XML format will be published to this topic. It allows the recipient to make sure the integrity of the information is kept intact, as well as assuring the correct origin of the information. |
| `HardenMqtt/Secured/Confidential` | An encrypted version of the cryptographically signed interoperable XML format will be published to this topic. Symmetric key used for encryption is derived using `EdDSA`, and by secure pairing between a sensor and a display. |
| `HardenMqtt/Pairing` | All pairing of sensors with their corresponding displays is done using over this topic. |

**Note**: Pressing any key (except `CTRL+Z`) when the sensor is in the main loop, will trigger a republishing of current sensor
data to MQTT. This can be useful if you need to test something quickly, and do not want to wait for the next scheduled samling.

![Sensor Screen](Images/Sensor.png)

### Display

The [Display](Display) project gets information from the [Sensor](Sensor) and displays it to the user. The goal of the experiment,
is to highlight different methods of transport of information in MQTT, and their corresponding vulnerabilities. As you troll the
communication, you can see how it affects (or does not affect) what is presented on the display. When starting the application,
the following sequence of events occurs:

1. Application will ask you for a Device ID. This ID is used in all event logging and pairing communication, to help you
identify the different actors.
2. Private and public keys are loaded, or generated.
3. The it asks your for connection details to an MQTT broker. All information you provide will be persisted. You only have to
provide it once.
4. Pairing is then commenced, if pairing with a sensor has not been performed earlier. Pairing allows the
display to decrypt information sent by the sensor. Pairing is done securely over MQTT using `EdDSA`.
5. Subscribing to different topics is then performed, in accordance with what information you want to display.
6. The main loop simply waits for you to press `CTRL+Z` to quit the application.

You switch mode in the display application, by pressing the `1` to `5` keys, or the `F1` to `F5` keys, as follows:

| Key | Page |
|:------------|:--------------------------|
| `1` or `F1` | Unstructured information |
| `2` or `F2` | Structured information |
| `3` or `F3` | Interoperable information |
| `4` or `F4` | Signed information |
| `5` or `F5` | Confidential information |

![Display Screen](Images/Display.png)

### Troll

The [Troll](Troll) application listens to communication performed on the broker, and tries to disrupt it, to highlight some of
the vulnerabilities that exist inherent in MQTT. Most of these vulnerabilities are based on the following principles:

* MQTT does not provide you with information about who published information.
* MQTT does not provide a presentation layer, or information about encoding of content. It is up to the recipient to figure out
how binary information should be decoded.
* You can send very large messages, depleting resources or effectively making communication difficult or impossible for devices
with intermittant networks.
* You can subscribe to very large subtrees or the entire topic tree, giving you broad access to information communicated.
* Authentication and Authorization in MQTT is done out-of-band, by operators of the broker, and not negotiated between the
participants of the communication.

To resolve these vulnerabilities (some of which cannot be resolved efficiently by the participants themselves), special care has
to be taken. The purpose of the repository is to highlight how these things can be resolved, and the application be hardened.

**Note**: The [Troll](Troll) application can be used as a testing tool, to make sure applications that use MQTT are made
resilient. Please feel free to extend the application to include more ways to troll participants in the network. Note however,
that only *responsible use* is recommended and encouraged. Any malicious use is discouraged and should be desisted.

![Troll Screen](Images/Troll.png)

#### Level of Trolling

There's a constant named `Trolliness` in the code. Alter this constant, to change the amount of trolling the application
performs.

```
const int Trolliness = 3; // 1=maximum. Higher values decrease probability of content being altered.
```

#### Methods

While trolling the MQTT communication, output is performed on the console screen, in the form of characters. The following
table lists the characters that can be output, and what they represent. A space character is output, when an incoming message
is detected to have been sent by the troll application itself. It is an acknowledgement that the trolled message has been
successfully delivered.

| Character | Description |
|:---------:|:---------------------------|
| `h` | Halving |
| `d` | Doubling |
| `n` | Negating |
| `r` | Randomizing |
| `s` | Replace with a string |
| `f` | Format change |
| `y` | Year change |
| `m` | Month change |
| `D` | Day change |
| `t` | Hour change |
| `i` | Minute change |
| `S` | Second change |
| `c` | schema changed |
| `N` | Host Name changed |
| `u` | Path in Url changed |
| `o` | JSON Object changed |
| `a` | JSON Array changed |
| `x` | XML changed |
| `k` | 1 kB of random data sent |
| `M` | 1 MB of random data sent |
| `H` | 16 MB of random data sent |
| `G` | 192 MB of random data sent |

### Monitor

The [Monitor](Monitor) application is a Windows application that allows the user to monitor MQTT communication in a Windows GUI.
It displays the topic tree, and content published on individual topics. It also allows the user to edit published content, and
publish it back to MQTT. It is a simple but effective tool that can be used during development and testing of MQTT-based
applications.

![Monitor Screen](Images/Monitor.png)

For the Teacher
-----------------

You can find a proposed [Lab](LAB.md) in this repository, divided into three sessions, where studens learn to communicate over
MQTT, then learn about common vulnerabilities, and finally how to harden their solutions for these vulnerabilities. The projects
available in this repository can be run simultaneously during the lab, everyone using the same MQTT broker as shared infrastructure.

Other repositories of interest
----------------------------------

| Repository | Description |
|:---------------------------------------------------------------------------|:------------|
| [Mastering Internet of Things](https://github.com/PeterWaher/MIoT) | Contains multiple projects for sensors, actuators and concentrators using different protocols for comparison (such as HTTP, CoAP, LWM2M, MQTT and XMPP). All projects and associated information are described in a book with the same name. |
| [OpenWeatherMapSensor](https://github.com/PeterWaher/OpenWeatherMapSensor) | Contains a simple provisionable sensor publishing sensor data using the XMPP protocol. |
| [IoT Gateway™](https://github.com/PeterWaher/IoTGateway) | Contains multiple libraries for creating distributed applications for IoT, as well as an IoT Gateway host and client applications. Apart from containing the source code of the libraries used by the projects in this repository, it also contains a useful tool for [viewing events](https://github.com/PeterWaher/IoTGateway/tree/master/Clients/Waher.Client.MqttEventViewer) in distributed applications over MQTT, something that will come in handy when debugging or tracing what happens during development or the course of the lab. |
| [TAG Digital ID™](https://github.com/Trust-Anchor-Group/IdApp) | A Digital ID App that can be used for communicating with IoT devices, as well as to provision access to them, among many other things. |
| [TAG ComSim™](https://github.com/Trust-Anchor-Group/ComSim) | A communications-based simulator, which allows you to create stochastic simulation models to simulate large networks of IoT devices, as well as human users. |
| [TAG LegalLab™](https://github.com/Trust-Anchor-Group/LegalLab) | A tool for creating smart contracts that can be used for automation across domains in IoT and smart societies. |
| [NeuronⓇ Documentation](https://lab.tagroot.io/Documentation/Index.md) | Documentation about the TAG NeuronⓇ and how it can be used to secure interoperable and federated communication. |
| [IEEE XMPP IoT Interfaces](https://gitlab.com/IEEE-SA/XMPPI/IoT) | A repository hosted by IEEE for IoT Harmonization for smart societies. Contains the technical reference information necessary to understand cross-domain interoperability, digital identities, smart contracts, decision support and automated, legally binding, decision making, as the basis for automation across domains on the Internet. |