TLS & Certificates

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

• https://letsencrypt.org/docs/certificates-for-localhost/
• https://github.com/Azure/azure-xplat-cli/wiki/Getting-Self-Signed-SSL-Certificates-(.pem-and-.pfx)
• http://paulstovell.com/blog/x509certificate2

Create certificates for test

# 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 certificate must be stored in /data/certificates. If the folder does not exist, create it on your own. 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

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.

Usage

Example for encryption and user authentication with docker-compose file

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/
   

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.