Securing HTTP and MQTT endpoints

Securing HTTP and MQTT endpoints

By default the integrated HTTP server and MQTT broker in the Node use unencrypted communication without authentication. In this article we will explain how you can configure your nodes with encryption and/or authentication.

TLS & Certificates

To enable encrypted communication (TLS) you need a certificate file that can be used by the node.

Good links for reading about certs

Create certificates for test

In a production environment we recommend using a trusted certificate. For testing purposes you can create a self-signed certificate by following the below steps.
A great tool for creating test certificates is openssl:
# Generate a private key and self-signed certificate for edgenode.local
openssl req -x509 -out edgenode.crt -keyout edgenode.key   -newkey rsa:2048 -nodes -sha256   -subj '/CN=edgenode.local' -extensions EXT -config <( \
   printf "[dn]\nCN=edgenode.local\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:edgenode.local\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")

# Generate a edgenode.pfx cert
openssl pkcs12 -export -in edgenode.crt -inkey edgenode.key -out edgenode.pfx

Register the cert

On the clients attaching to the node you should add the edgenode.crt file as a root cert in your cert store and change the cert to always be trusted.

Edit hosts

Edit your hosts file so that egdenode.local targets 127.0.0.1.

Configure Cert for HTTPS/MQTT

Note: We show HTTP here, but MQTT works the same way.

When starting the server all files will be created with default values, so make sure you have done that. Under the data/ folder you will find all configuration files. The httpconfiguration.json/mqttconfiguration.json files will look something like:

{
  "HttpConfiguration": {
    "HttpEndpoints": [
      {
        "Address": "0.0.0.0",
        "Port": 9090,
        "Name": "---",
        "AuthenticationType": "None",
        "AuthenticationEncryption": "MD5",
        "AuthenticationFolder": "authentication",
        "AuthenticationFile": "httpAccess9090.config",
        "CertificateType": "None",
        "StoreCertificate": {
          "Subject": "",
          "StoreName": "My",
          "StoreLocation": "LocalMachine",
          "AllowValidOnly": true,
          "SslProtocols": "Tls12"
        },
        "FileCertificate": {
          "CertificatePath": "",
          "CertificatePassword": "",
          "SslProtocols": "Tls12"
        }
      }
    ]
  }
}

Use cert from file

Below we have changed to configuration to have:

  • CertificateType = FileCertificate
  • FileCertificate.CertififcatePath = edgenode.pfx
  • FileCertificate.CertififcatePassword = !4U2know

The CertificatePath will use data/resources/certificates/ as root path. CertificatePassword should be whatever you used as password when creating the cert.

{
  "HttpConfiguration": {
    "HttpEndpoints": [
      {
        "Address": "0.0.0.0",
        "Port": 9090,
        "Name": "---",
        "AuthenticationType": "None",
        "AuthenticationEncryption": "MD5",
        "AuthenticationFolder": "authentication",
        "AuthenticationFile": "httpAccess9090.config",
        "CertificateType": "FileCertificate",
        "StoreCertificate": {
          "Subject": "",
          "StoreName": "My",
          "StoreLocation": "LocalMachine",
          "AllowValidOnly": true,
          "SslProtocols": "Tls12"
        },
        "FileCertificate": {
          "CertificatePath": "edgenode.pfx",
          "CertificatePassword": "!4U2know",
          "SslProtocols": "Tls12"
        }
      }
    ]
  }
}

Start the Node, then open a browser and navigate tohttps://edgenode.local:9090. The certificate should be valid and you are now accessing the Node over HTTPS with a file certificate.

Users

When the server is started it will create default configuration files for HTTP and MQTT if they do not exist: httpconfiguration.json and mqttconfiguration.json

Each file contains an array of endpoints to start and each endpoint can have its own security settings. The files will be located in the data folder.

Configuration Example

{
  "MqttConfiguration": {
    "MqttEndpoints": [
      {
        "Address": "0.0.0.0", // The address to bind to
        "Port": 1883, // The port to use
        "Name": "---", // A custom name for the endpoint (optional)
        "AuthenticationType": "Basic", // None or Basic are current options
        "AuthenticationEncryption": "MD5", // None or MD5 are current options
        "AuthenticationFolder": "authentication", // folder to store access config in
        "AuthenticationFile": "mqttAccess1883.config" // the name of the access file for the endpoint
      }
    ]
  }
}

By default the AuthenticationType is set to Nonebut if we change to Basic and restart the server we will see that we get new files in the folder data/authentication. We will see 2 files if we change to configuration above to use Basic authentication.

  • mqttAccess1883.config - Contains all encrypted passwords. Do not edit this file.
  • new_mqttAccess1883.config - Enter new users into this file in the format username:password in clear text. Separate users with new lines

When the server is started it will encrypt the password using the AuthenticationEncryption chosen in the endpoint configuration.

Example

If you enter uffe:foo into the file new_mqttAccess1883.config the server will encrypt the password into something like uffe:$MD5$eTtZYr8vuDnBnQL/o2IM2ayZRnvhGC3lChmi8X98N2QOhzdNDII8mGhrv9bUZIPu1+pclAYohitAY9FpfY5IB+TsZiH79yCTxLpHr+z91jgacfA3YiOP8PZpcFTy1PIRLbMcOnTChzsdYYOlhMWv3LYm/iobDxq6ccX3uEL5+lo=$ITVf94re52wCB2lQqF2NeQ== and store the information in the mqttAccess1883.config file. The content that was saved in clear text in new_mqttAccess1883.config will be removed.

Note that if you use Noneas AuthenticationEncryption the password will be stored in clear text.

Usage

When using MQTT you can use the Username/Pasword feature of the protocol. So that you can connect to the Crosser MQTT Broker with client credentials.
When using HTTP you can use this to get Basic Authentication. ​

Example for encryption and user authentication with docker-compose file

If you prefer to specify the endpoint configuration within your docker-compose file, you can use the example for MQTT below.
Keep in mind that all requirements still apply:
  1. Certificates for endpoint must be available in ./data/certificates
  2. edgenode.local 127.0.0.1 must be added to /etc/hosts (depending on the Operating System)
  3. file which holds the new users, in this case new_mqttAccess8883.config, must be available in ./data/authentication/
Note: You could specify multiple MQTT endpoints, therefore you have to specify the index __0__

version: '3.5'

services:
  edgenode:
    image: docker.crosser.io/crosser/edgenode:latest
    container_name: crosser-edgenode
    restart: always
    environment:
      - SecurityConfiguration__Credentials__NodeId=ENTER-YOUR-NODEID-HERE
      - SecurityConfiguration__Credentials__AccessKey=ENTER-YOUR-ACCESS-KEY-HERE
      - MqttConfiguration__MqttEndpoints__0__Address=0.0.0.0
      - MqttConfiguration__MqttEndpoints__0__Port=8883
      - MqttConfiguration__MqttEndpoints__0__AuthenticationType=Basic
      - MqttConfiguration__MqttEndpoints__0__AuthenticationEncryption=MD5
      - MqttConfiguration__MqttEndpoints__0__AuthenticationFolder=authentication
      - MqttConfiguration__MqttEndpoints__0__AuthenticationFile=mqttAccess8883.config
      - MqttConfiguration__MqttEndpoints__0__CertificateType=FileCertificate
      - MqttConfiguration__MqttEndpoints__0__clientCertificateRequired=false
      - MqttConfiguration__MqttEndpoints__0__StoreCertificate__StoreName=My
      - MqttConfiguration__MqttEndpoints__0__StoreCertificate__StoreLocation=LocalMachine
      - MqttConfiguration__MqttEndpoints__0__StoreCertificate__AllowValidOnly=true
      - MqttConfiguration__MqttEndpoints__0__StoreCertificate__SslProtocols=Tls12
      - MqttConfiguration__MqttEndpoints__0__FileCertificate__CertificatePath=edgenode.pfx
      - MqttConfiguration__MqttEndpoints__0__FileCertificate__CertificatePassword=ENTER-YOUR-CERTIFICATE-PASSWORD-HERE
      - MqttConfiguration__MqttEndpoints__0__FileCertificate__SslProtocols=Tls12
    ports:
      - 9090:9090
      - 9191:9191
      - 8883:8883
    volumes:
      - "./data:/application/data"
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "2"


Limitations

  • You should only use one settings file per endpoint. Do not try to use one file for several endpoints
  • Only Basic authentication is currently supported. 

    • Related Articles

    • Flow to Flow communication

      Introduction One of the benefits of the Crosser solution is that you can deploy multiple flows (processes) into one existing container. Due to that, you can add new use cases without influencing running processes at the edge, even without restarting ...
    • Crosser Node 2.6.0

      Release Note Release date: 2023-06-29 Note: A critical bug was found in 2.6.0 and is now deprecated, use 2.6.1 instead. New features Retry on all modules Each module now has settings for Retry (Common Settings). When the Max Number Of Retries setting ...
    • Monitoring the Crosser Node

      Introduction Once you have your first flows deployed, you might think about how to integrate the Crosser Node and Flows into your existing monitoring solution. In this article we describe what options you have and how to utilize provided interfaces ...
    • Crosser Node 3.0.0

      Release Note Release date: 2023-10-31 Changes Python upgraded The docker images for the Node come with Python pre-installed. The version has now been updated to 3.11. For Nodes that run on Windows, Python has to be manually installed. Removed ...
    • Solution Overview

      Solution Overview The Crosser Solution is entirely focused on streaming analytics, i.e. analyzing data in motion. It is optimized for collecting data close to the source and then analyze the data in real time. The results can be delivered to ...