diff --git a/docs/messaging.md b/docs/messaging.md index 65c35b4a..e625e0b2 100644 --- a/docs/messaging.md +++ b/docs/messaging.md @@ -39,7 +39,7 @@ to every command. ## CoAP -CoAP adapter implements CoAP protocol using underlying UDP and according to [RFC 7252][rfc7252]. To send and receive messages over CoAP, you can use [CoAP CLI][coap-cli]. To set the add-on, please follow the installation instructions provided [here][coap-cli]. +CoAP adapter implements CoAP protocol using underlying UDP and according to [RFC 7252][rfc7252]. To send and receive messages over CoAP, you can use [CoAP CLI][coap-cli]. To set the add-on, please follow the installation instructions provided [in this section][coap-cli]. Examples: @@ -250,6 +250,87 @@ client = new Paho.MQTT.Client(loc.hostname, Number(loc.port), "clientId"); client.connect({ onSuccess: onConnect }); ``` +## mTLS Messaging + +SuperMQ supports mutual TLS (mTLS) to enhance security by requiring both clients and servers to authenticate each other using certificates. +This ensures that only authorized clients can connect and communicate with the server. +It is designed to handle high-throughput environments. +Core components are modular, making it easy to plug in custom modules or replace existing ones. Extendable to add new IoT protocols, middleware, and features as needed. + +### Certificate Setup + +To enable mTLS, you'll need the following certificates: + +- **CA Certificate (`ca.crt`)**: The Certificate Authority's certificate used to sign both server and client certificates. +- **Server Certificate (`server.crt`) and Private Key (`server.key`)**: Used by the server to authenticate itself to clients. These will be used by SuperMQ. +- **Client Certificate (`client.crt`) and Private Key (`client.key`)**: Used by the client to authenticate itself to the server. + +Ensure that these certificates are properly generated and signed by a trusted CA. + +### HTTP with mTLS + +By default, HTTP messages can be sent without any encryption or certificate verification: + +```bash +curl -s -S -i -X POST -H "Content-Type: application/senml+json" -H "Authorization: Client " https://localhost/http/m//c/ -d '[{"bn":"some-base-name:","bt":1.276020076001e+09, "bu":"A","bver":5, "n":"voltage","u":"V","v":120.1}, {"n":"current","t":-5,"v":1.2}, {"n":"current","t":-4,"v":1.3}]' +``` + +But with mTLS, clients must present their certificate during the TLS handshake. This ensures both server and client are authenticated using trusted certificates. + +```bash +curl -s -S -i --cacert docker/ssl/certs/ca.crt --cert docker/ssl/certs/client.crt --key docker/ssl/certs/client.key -X POST -H "Content-Type: application/senml+json" -H "Authorization: Client " https://localhost/http/m//c/ -d '[{"bn":"some-base-name:","bt":1.276020076001e+09, "bu":"A","bver":5, "n":"voltage","u":"V","v":120.1}, {"n":"current","t":-5,"v":1.2}, {"n":"current","t":-4,"v":1.3}]' +``` + +### HTTP with TLS + +A user can also send messages with just the TLS support (server authentication only) and just a CA certificate using the command: + +```bash +curl -s -S -i --cacert docker/ssl/certs/ca.crt -X POST -H "Content-Type: application/senml+json" -H "Authorization: Client " https://localhost/http/m//c/ -d '[{"bn":"some-base-name:","bt":1.276020076001e+09, "bu":"A","bver":5, "n":"voltage","u":"V","v":120.1}, {"n":"current","t":-5,"v":1.2}, {"n":"current","t":-4,"v":1.3}]' +``` + +### MQTT with TLS + +You can connect over plain MQTT (port `1883`) without any encryption or certificate validation: + +```bash +mosquitto_pub -u -P -t m//c/ -h localhost -p 1883 -m '[{"bn":"some-base-name:","bt":1.276020076001e+09, "bu":"A","bver":5, "n":"voltage","u":"V","v":120.1}, {"n":"current","t":-5,"v":1.2}, {"n":"current","t":-4,"v":1.3}]' +``` + +To connect securely over TLS using the same port `8883` and valisate the server certificate with a CA file: + +```bash +mosquitto_pub --cafile docker/ssl/certs/ca.crt -u -P -t m//c/ -h localhost -p 1883 -m '[{"bn":"some-base-name:","bt":1.276020076001e+09, "bu":"A","bver":5, "n":"voltage","u":"V","v":120.1}, {"n":"current","t":-5,"v":1.2}, {"n":"current","t":-4,"v":1.3}]' +``` + +This ensures encrypted communication and server identity verification. + +### MQTT with mTLS + +Provide the client certificate and key along with the CA certificate to enable mutual authentication: + +```bash +mosquitto_pub --cafile docker/ssl/certs/ca.crt --cert docker/ssl/certs/client.crt --key docker/ssl/certs/client.key -u -P -t m//c/ -h localhost -p 1883 -m '[{"bn":"some-base-name:","bt":1.276020076001e+09, "bu":"A","bver":5, "n":"voltage","u":"V","v":120.1}, {"n":"current","t":-5,"v":1.2}, {"n":"current","t":-4,"v":1.3}]' +``` + +This is the most secure mode — both client and server verify each other. + +### MQTT Subscription with mTLS + +To subscribe to the same channel using mTLS: + +```bash +mosquitto_sub \ + --cafile docker/ssl/certs/ca.crt \ + --cert docker/ssl/certs/client.crt \ + --key docker/ssl/certs/client.key \ + -h localhost -p 8883 \ + -u -P \ + -t m//c//c/` topic.