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
- 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
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. In 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 to https://edgenode.local:9090. The certificate should be valid and you are now accessing the Node over HTTPS with a file certificate.
Authentication
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 'None' but 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 the 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 'None' as AuthenticationEncryption the password will be stored in clear text.
Usage
When using MQTT you can use the Username/Password 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:
-
Certificates for endpoint must be available in ./data/certificates
-
edgenode.local 127.0.0.1 must be added to /etc/hosts (depending on the Operating System)
-
A 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__
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.
Search Documentation
Page Sections