Version: 2.7

MQTT Server Configuration

The MQTT server plugin can handle multiple server instances. Each of them has its own context and runs as an independent task.

The server is configured in the "settings.json" located in the "Config/HumanOS.PeSeL.MqttServer/" folder

NOTE

The server only handles authentication, but not authorization, which means clients are only validated on connect.

Important

Using encrypted connections is not yet available. In addition, certificate based authentication is also not yet available.

There are four modes of authentication when configuring an mqtt server, whereas all of these modes can be combined:

Basic Authentication (Username, Password)
Certificate Authentication (Certificate provided by client must be in servers computer certificate store)
With/Without encrypted transport layer (Certificate provided by file on server)
Client Id white- or blacklisting

NOTE

The following table contains the differences to the mqtt client configuration. Lookup the section subscriber or publisher configuration in HumanOS.PeSeL.MQTTClient for base parameters. As it is not a data logger ignore reference to HumanOS.Kernel.PeSeL in the client manual.

Parameter	Description	Data Type	Default Value
Topic	Topic name - NOT AVAILABLE	System.String
AddressV6	Ip v6 address to listen on (:: for any IP -> 0.0.0.0 for Address parameter which is Ipv4)	System.String	::
QualityOfService	Quality of Service (QOS) - NOT AVAILABLE	System.Int32
CleanSession	[OPT] MQTT Clean Session Flag - NOT AVAILABLE YET	System.Boolean
RetainMessages	Flag if messages are retained in the broker - NOT AVAILABLE YET	System.Boolean
ReplyTopic	Reply topic address - NOT AVAILABLE	System.String
ReplyQualityOfService	Quality of Service for reply channel - NOT AVAILABLE	System.String
ClientCaCertificateFile	[OPT] Path to client chain certificate for certificate authentication. - NOT AVAILABLE	System.String
ClientCertificateFile	[OPT] Path to client certificate for certificate authentication. - NOT AVAILABLE	System.String
ClientCertificatePassword	[OPT] Password for the client certificate - NOT AVAILABLE	System.String
WhitelistedClientIds	[OPT] Specify a list of client ids which are allowed to connect - if set these are the ONLY clients allowed	System.String
BlacklistedClientIds	[OPT] Specify a list of client ids which are not allowed to connect	System.String
CertificateFile	[OPT] Path to certificate for certificate authentication. Requires a ".pfx" file (Is presented to to the client and encrypts the connection) - NOT AVAILABLE YET	System.String
CertificatePassword	[OPT] Password for the client certificate - NOT AVAILABLE YET	System.String
EnableCertificateBasedAuthentication	[OPT] Authenticates the incoming client certificate with a trusted root store client - NOT AVAILABLE YET	System.Boolean	false
EnableExtendedLogs	[OPT] Enables advanced logging - caution, this has performance impacts!	System.Boolean	false

Certificates

Important

The root CA in the pfx must be known, or contained by the certificate chain. It also must contain a private key.

Following is an example how to generate a certificate with a custom root CA:

Creating the root custom CA certificate

Generate the root CA key
- openssl ecparam -out ca-cybertech-dev.key -name prime256v1 -genkey
Create the root CA certificate
- openssl req -new -sha256 -key ca-cybertech-dev.key -out ca-cybertech-dev.csr (When prompted, type the password for the root key, and the organizational information for the custom CA such as Country/Region, State, Org, OU, and the fully qualified domain name (this is the domain of the issuer)
Combine the key and csr to a bundle in .crt format (also called signing)
- openssl x509 -req -sha256 -days 4096 -in ca-cybertech-dev.csr -signkey ca-cybertech-dev.key -out ca-cybertech-dev.crt
Create a .pfx copy
- openssl pkcs12 -export -in ca-cybertech-dev.crt -inkey ca-cybertech-dev.key -out ca-cybertech-dev.pfx
Add the root certificate to your machine's trusted root store (Trusted root certification Authorities)

Create the server certificate

The CSR is a public key that is given to a CA when requesting a certificate. The CA issues the certificate for this specific request.

IMPORTANT

The CN (Common Name) for the server certificate must be different from the issuer's domain. For example, in this case, the CN for the issuer is www.ca-cybertech-dev.com and the server certificate's CN is www.cybertech.com.

Generate the server certificate private key and the certificate CSR
- openssl ecparam -out cybertech-dev.key -name prime256v1 -genkey
- openssl req -new -sha256 -key cybertech-dev.key -out cybertech-dev.csr (When prompted, type the password for the root key, and the organizational information for the custom CA: Country/Region, State, Org, OU, and the fully qualified domain name. This is the domain of the website and it should be different from the issuer. Type an asterisk in front of the fqdn if you want a wildcard like *.mydomain.com)
Combine the key and csr to a bundle (also called signing, use the key and sign it with the CA's root key)
- openssl x509 -req -in cybertech-dev.csr -CA ca-cybertech-dev.crt -CAkey ca-cybertech-dev.key -CAcreateserial -out cybertech-dev.crt -days 4096 -sha256
Verify the newly created certificate
- openssl x509 -in cybertech-dev.crt -text -noout
Verify the files in your directory, and ensure you have the following files:
- ca-cybertech-dev.crt
- ca-cybertech-dev.key
- cybertech-dev.crt
- cybertech-dev.key
Create a .pfx copy
- openssl pkcs12 -export -in cybertech-dev.crt -inkey cybertech-dev.key -out cybertech-dev.pfx
Specify the .pfx file path to the certificate file property and the password accordingly

Server Examples

The appendix contains working examples of MQTT configuration.

Unprotected Endpoint

{
  "Id": "B8DFA2BC-13B2-47D6-A9B0-AEA1257B33A6",
  "Name": "TestServer",
  "ServiceRule": {
    "BindingRuleId": "{8A80927A-B1F8-4505-B4BA-FB2DFED765E4}",
    "UnbindingRuleId": "{1058566D-0787-48C3-95A5-235E9A55CCF3}",
    "Type": "All"
  }
}

Unprotected Endpoint with Client Id Whitelisting

{
  "Id": "892E0492-DD90-4089-8F2B-460B9FAD53A5",
  "Name": "TestServer",
  "WhitelistedClientIds": [
    "MyClient1",
    "MyClient2"
  ],
  "ServiceRule": {
    "BindingRuleId": "{8A80927A-B1F8-4505-B4BA-FB2DFED765E4}",
    "UnbindingRuleId": "{1058566D-0787-48C3-95A5-235E9A55CCF3}",
    "Type": "All"
  }
}

Unprotected Endpoint with Client Id Blacklisting

{
  "Id": "6E352B62-974A-4685-ABE9-3950B19A532E",
  "Name": "TestServer",
  "BlacklistedClientIds": [
    "MyClient1",
    "MyClient2"
  ],
  "ServiceRule": {
    "BindingRuleId": "{8A80927A-B1F8-4505-B4BA-FB2DFED765E4}",
    "UnbindingRuleId": "{1058566D-0787-48C3-95A5-235E9A55CCF3}",
    "Type": "All"
  }
}

Protected Endpoint with Client Certificate Authentication

{
  "Id": "F17D0465-4071-4C4C-80EC-CF951B359D5A",
  "Name": "TestServer",
  "CertificateFile": "$(AppConfig:CertificatePath)\\ServerCert.pfx",
  "CertificatePassword": "MyPassword",
  "TransportLayerSecurity": "Tls12",
  "EnableCertificateBasedAuthentication": true,
  "ServiceRule": {
    "BindingRuleId": "{8A80927A-B1F8-4505-B4BA-FB2DFED765E4}",
    "UnbindingRuleId": "{1058566D-0787-48C3-95A5-235E9A55CCF3}",
    "Type": "All"
  }
}

Protected Endpoint with Client Basic Authentication

{
  "Id": "F43DD67A-0FCA-47C8-9C8F-0F3112DC24A7",
  "Name": "TestServer",
  "CertificateFile": "$(AppConfig:CertificatePath)\\ServerCert.pfx",
  "CertificatePassword": "MyPassword",
  "TransportLayerSecurity": "Tls12",
  "Username": "test",
  "Password": "AnotherPassword",
  "ServiceRule": {
    "BindingRuleId": "{8A80927A-B1F8-4505-B4BA-FB2DFED765E4}",
    "UnbindingRuleId": "{1058566D-0787-48C3-95A5-235E9A55CCF3}",
    "Type": "All"
  }
}

Certificates​

Creating the root custom CA certificate​

Create the server certificate​

Server Examples​

Unprotected Endpoint​

Unprotected Endpoint with Client Id Whitelisting​

Unprotected Endpoint with Client Id Blacklisting​

Protected Endpoint with Client Certificate Authentication​

Protected Endpoint with Client Basic Authentication​