OpcLabs.MqttNet communication package: Difference between revisions

From OPC Labs Knowledge Base
 
(27 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:MQTT]]  
[[Category:Communication packages]] [[Category:MQTT]]  
== Configuring the communication package ==
This communication package is based on MQTTnet and MQTTnet.Extensions.ManagedClient libraries by Christian Kratky. See [[MQTT communication packages]] for a summary of the communication package and the library. The library supports Client and Server roles; the communication package only supports the Client role.


See [[Using communication packages]] for instructions on how to select the communication package, and configure it.
= Client role =
The type name of the message channel object is:
'''{{Style=Identifier|OpcLabs.MqttNet.ManagedMqttClientMessageChannel,OpcLabs.MqttNet}}''' .
== Opening the channel ==
=== URL string ===
If the URL string has "mqtt", "mqtts", "ssl", "tcp" or "tls" scheme, TCP protocol (possibly with SSL/TLS) will be used. In this case, the URL is parsed by the communication package and various pieces of information are extracted from it. The syntax is:
<code>''scheme'':[//[''username''[:''password'']@]''host''[:''port'']][/clientId=''clientId'']</code>
If the client credentials have not been specified in the configuration (see below), which is the default, the username and password from the URL are used. The port defaults to 1883 for "mqtt", "tcp" schemes, and to 8883 for "mqtts", "ssl" schemes.
The "mqtt" and "tcp" schemes are equivalent, and denote a use of TCP protocol without SSL/TLS. The "mqtts", "ssl" and "tls" schemes are equivalent, and denote a use of TCP protocol with SSL/TLS.
Using the clientId query parameter you can override the default clientId supplied by host software. Additional query parameters can be specified, and are ignored.
Examples:
<pre>
mqtt://test.mosquitto.org
mqtts://test.mosquitto.org
</pre>
If the URL string has "ws" or "wss" scheme, WebSocket protocol (possibly with TLS, for "wss") will be used. In this case, the URL is passed onto the underlying library unchanged (the user info is still extracted from it and interpreted by the communication package).
Examples:
<pre>
ws://test.mosquitto.org:8080/mqtt
wss://test.mosquitto.org:8081/mqtt
</pre>
If the scheme in the URL is not one of the schemes listed here, the message channel will still open, using the clientId and cleanSession flag provided by the host software, and all other parameters given by the configuration properties. This will fail under normal circumstances - unless you have carefully set all properties as necessary.
=== Interface name ===
The interface name, if provided by the host software, is ignored.
=== Certificates ===
Due to limitations imposed by the underlying library, if the host software specifies its own server certificate validation, this validation can allow additional server certificates be accepted over what the library accepts by default, but no server certificate accepted by the library by its default mechanism can be rejected by the host validation. Also, the host can provide a list of client certificates, but cannot influence the certificate selection.
== Configuration ==
The table below lists the available properties, their types, and descriptions. Most properties come from configurable options of the underlying library, so please refer to the its documentation for details (we could not find a comprehensive reference documentation for this library, that's why most descriptions are missing). Do not get scared by the number of configurable properties; the relevant ones can usually stay at their defaults, or usually overridden from the host software (as noted). We will emphasize specific properties if they are important.
{| class="wikitable"
{| class="wikitable"
!Property
!Type
!Description
|-
|-
|ClientWaitTimeout
|ClientWaitTimeout
|System.Int32
|System.Int32
|
|Determines the maximum wait time for the client to open before publishing a message. In milliseconds.
|-
|-
|ManagedMqttClientOptions
|ManagedMqttClientOptions
Line 28: Line 73:
|Default is 2^31-1.
|Default is 2^31-1.
|-
|-
|ManagedMqttClientOptions.PendingMessagesOverflowStrategy
|ManagedMqttClientOptions.<br>PendingMessagesOverflowStrategy
|MQTTnet.Server.MqttPendingMessagesOverflowStrategy
|MQTTnet.Server.MqttPendingMessagesOverflowStrategy
|Default is DropNewMessage.
|Default is DropNewMessage.
Line 50: Line 95:
|MqttClientOptions.ChannelOptions
|MqttClientOptions.ChannelOptions
|MQTTnet.Client.Options.IMqttClientChannelOptions
|MQTTnet.Client.Options.IMqttClientChannelOptions
|Default value is null. For known URL schemes, it gets overridden by a value determined during URL resolution. For "mqtt", "mqtts", "ssl", "tcp" schemes, value from the MqttClientTcpOptions property is used. For "ws", "wss" schemes, value from the MqttClientWebSocketOptions is used.
|Default value is null. For known URL schemes, it gets overridden by a value determined during URL resolution. For "mqtt", "mqtts", "ssl", "tcp" and "tls" schemes, value from the MqttClientTcpOptions property is used. For "ws", "wss" schemes, value from the MqttClientWebSocketOptions is used.
|-
|-
|MqttClientOptions.CleanSession
|MqttClientOptions.CleanSession
|System.Boolean
|System.Boolean
|Always gets set to the value specified by the host software (do not use).
|Always override by the value specified by the host software (do not use).
|-
|-
|MqttClientOptions.ClientId
|MqttClientOptions.ClientId
|System.String
|System.String
|Default value is null. When null, gets overridden by the ClientId specified by the host software. For "mqtt", "mqtts", "ssl", "tcp" URL schemes, it can further be overridden by a "clientId" query parameter in the URL.
|Default value is null. When null, gets overridden by the ClientId specified by the host software. For "mqtt", "mqtts", "ssl", "tcp" and "tls" URL schemes, it can further be overridden by a "clientId" query parameter in the URL.
|-
|-
|MqttClientOptions.Credentials
|MqttClientOptions.Credentials
|
|MQTTnet.Client.Options.IMqttClientCredentials
|
|Default value is null. When null, for "mqtt", "mqtts", "ssl", "tcp" and "tls" URL schemes, if the URL contains user-specific information, gets overridden by the credentials with user name and password from the URL.
|-
|-
|MqttClientOptions.CommunicationTimeout
|MqttClientOptions.CommunicationTimeout
Line 68: Line 113:
|Default is 10 seconds.
|Default is 10 seconds.
|-
|-
|MqttClientOptions.ExtendedAuthenticationExchangeHandler
|MqttClientOptions.<br>ExtendedAuthenticationExchangeHandler
|MQTTnet.Client.ExtendedAuthenticationExchange.IMqttExtendedAuthenticationExchangeHandler
|MQTTnet.Client.ExtendedAuthenticationExchange.<wbr>IMqttExtendedAuthenticationExchangeHandler
|
|
|-
|-
Line 84: Line 129:
|
|
|-
|-
|MqttClientOptions.ProtocolVersion
|'''MqttClientOptions.ProtocolVersion'''
|MQTTnet.Formatter.MqttProtocolVersion
|MQTTnet.Formatter.MqttProtocolVersion
|Default is V311.
|Default is V311. Other values: Unknown, V310, V500.
|-
|-
|MqttClientOptions.ReceiveMaximum
|MqttClientOptions.ReceiveMaximum
Line 134: Line 179:
|MqttClientTcpOptions.Port
|MqttClientTcpOptions.Port
|System.Nullable<System.Int32>
|System.Nullable<System.Int32>
|
|For "mqtt", "tcp" URL schemes, gets overridden by the value specified in the URL, or 1883 if not specified. For "mqtts", "ssl" and "tls" URL schemes, gets overridden by the value specified in the URL, or 8883 if not specified.
|-
|-
|MqttClientTcpOptions.Server
|MqttClientTcpOptions.Server
Line 142: Line 187:
|MqttClientTcpOptions.TlsOptions
|MqttClientTcpOptions.TlsOptions
|MQTTnet.Client.Options.MqttClientTlsOptions
|MQTTnet.Client.Options.MqttClientTlsOptions
|For "mqtt", "tcp", "mqtts", "ssl" URL schemes, some sub-properties (described here) get overridden.
|For "mqtt", "tcp", "mqtts", "ssl" and "tls" URL schemes, some sub-properties (described here) get overridden.
|-
|-
|MqttClientTcpOptions.TlsOptions.AllowUntrustedCertificates
|MqttClientTcpOptions.TlsOptions.<br>AllowUntrustedCertificates
|System.Boolean
|System.Boolean
|
|
|-
|-
|MqttClientTcpOptions.TlsOptions.Certificates
|MqttClientTcpOptions.TlsOptions.Certificates
|System.List<System.Security.Cryptography.X509Certificates.X509Certificate> ''(.NET Framework)''<br/>System.List<System.Byte[]> ''(.NET Standard)''
|System.List<System.Security.Cryptography.X509Certificates.<wbr>X509Certificate> ''(.NET Framework)''<br/>System.List<System.Byte[]> ''(.NET Standard)''
|For "mqtts", "ssl" URL schemes, may get overridden by hosting software.
|For "mqtts", "ssl" and "tls" URL schemes, may get overridden by hosting software.
|-
|-
|MqttClientTcpOptions.TlsOptions.CertificateValidationCallback
|MqttClientTcpOptions.TlsOptions.<br>CertificateValidationCallback
|System.Func<System.Security.Cryptography.X509Certificates.X509Certificate, System.Security.Cryptography.X509Certificates.X509Chain, System.Net.Security.SslPolicyErrors, MQTTnet.Client.Options.IMqttClientOptions, System.Boolean>
|System.Func<System.Security.Cryptography.X509Certificates.<wbr>X509Certificate, System.Security.Cryptography.X509Certificates.<wbr>X509Chain, System.Net.Security.SslPolicyErrors, MQTTnet.Client.Options.IMqttClientOptions, System.Boolean>
|For "mqtts", "ssl" URL schemes, may get overridden by hosting software.
|For "mqtts", "ssl" and "tls" URL schemes, may get overridden by hosting software.
|-
|-
|MqttClientTcpOptions.TlsOptions.IgnoreCertificateChainErrors
|MqttClientTcpOptions.TlsOptions.<br>IgnoreCertificateChainErrors
|System.Boolean
|System.Boolean
|
|
|-
|-
|MqttClientTcpOptions.TlsOptions.IgnoreCertificateRevocationErrors
|MqttClientTcpOptions.TlsOptions.<br>IgnoreCertificateRevocationErrors
|System.Boolean
|System.Boolean
|
|
Line 170: Line 215:
|MqttClientTcpOptions.TlsOptions.UseTls
|MqttClientTcpOptions.TlsOptions.UseTls
|System.Boolean
|System.Boolean
|Gets set to false for "mqtt", "tcp" URL schemes, gets set to true for "mqtts", "ssl" URL scheme.
|Gets overriden to false for "mqtt", "tcp" URL schemes, gets overridden to true for "mqtts", "ssl" and "tls" URL schemes.
|-
|-
|MqttClientWebSocketOptions
|MqttClientWebSocketOptions
Line 196: Line 241:
|For "ws", "wss" URL schemes, some sub-properties (described here) get overridden.
|For "ws", "wss" URL schemes, some sub-properties (described here) get overridden.
|-
|-
|MqttClientWebSocketOptions.TlsOptions.AllowUntrustedCertificates
|MqttClientWebSocketOptions.TlsOptions.<br>AllowUntrustedCertificates
|System.Boolean
|System.Boolean
|
|
|-
|-
|MqttClientWebSocketOptions.TlsOptions.Certificates
|MqttClientWebSocketOptions.TlsOptions.Certificates
|System.List<System.Security.Cryptography.X509Certificates.X509Certificate> ''(.NET Framework)''<br/>System.List<System.Byte[]> ''(.NET Standard)''
|System.List<System.Security.Cryptography.X509Certificates.<wbr>X509Certificate> ''(.NET Framework)''<br/>System.List<System.Byte[]> ''(.NET Standard)''
|For "wss" URL scheme, may get overridden by hosting software.
|For "wss" URL scheme, may get overridden by hosting software.
|-
|-
|MqttClientWebSocketOptions.TlsOptions.CertificateValidationCallback
|MqttClientWebSocketOptions.TlsOptions.<br>CertificateValidationCallback
|System.Func<System.Security.Cryptography.X509Certificates.X509Certificate, System.Security.Cryptography.X509Certificates.X509Chain, System.Net.Security.SslPolicyErrors, MQTTnet.Client.Options.IMqttClientOptions, System.Boolean>
|System.Func<System.Security.Cryptography.X509Certificates.<wbr>X509Certificate, System.Security.Cryptography.X509Certificates.<wbr>X509Chain, System.Net.Security.SslPolicyErrors, MQTTnet.Client.Options.IMqttClientOptions, System.Boolean>
|For "wss" URL scheme, may get overridden by hosting software.
|For "wss" URL scheme, may get overridden by hosting software.
|-
|-
|MqttClientWebSocketOptions.TlsOptions.IgnoreCertificateChainErrors
|MqttClientWebSocketOptions.TlsOptions.<br>IgnoreCertificateChainErrors
|System.Boolean
|System.Boolean
|
|
|-
|-
|MqttClientWebSocketOptions.TlsOptions.IgnoreCertificateRevocationErrors
|MqttClientWebSocketOptions.TlsOptions.<br>IgnoreCertificateRevocationErrors
|System.Boolean
|System.Boolean
|
|
Line 222: Line 267:
|MqttClientWebSocketOptions.TlsOptions.UseTls
|MqttClientWebSocketOptions.TlsOptions.UseTls
|System.Boolean
|System.Boolean
|Gets set to false for "ws" URL scheme, gets set to true for "wss" URL scheme.
|Gets overridden to false for "ws" URL scheme, gets overridden to true for "wss" URL scheme.
|-
|-
|-
|-
Line 229: Line 274:
|For "ws", "wss" URL schemes, gets overridden by the input URL string.
|For "ws", "wss" URL schemes, gets overridden by the input URL string.
|}
|}
= Server (broker) role =
Not implemented.
In development.
The type name of the message channel object is:
'''{{Style=Identifier|OpcLabs.MqttNet.ManagedMqttServerMessageChannel,OpcLabs.MqttNet}}''' .
= See also =
[[Certificate security plugin]]

Latest revision as of 16:33, 30 May 2024

This communication package is based on MQTTnet and MQTTnet.Extensions.ManagedClient libraries by Christian Kratky. See MQTT communication packages for a summary of the communication package and the library. The library supports Client and Server roles; the communication package only supports the Client role.

See Using communication packages for instructions on how to select the communication package, and configure it.

Client role

The type name of the message channel object is: OpcLabs.MqttNet.ManagedMqttClientMessageChannel,OpcLabs.MqttNet .

Opening the channel

URL string

If the URL string has "mqtt", "mqtts", "ssl", "tcp" or "tls" scheme, TCP protocol (possibly with SSL/TLS) will be used. In this case, the URL is parsed by the communication package and various pieces of information are extracted from it. The syntax is:

scheme:[//[username[:password]@]host[:port]][/clientId=clientId]

If the client credentials have not been specified in the configuration (see below), which is the default, the username and password from the URL are used. The port defaults to 1883 for "mqtt", "tcp" schemes, and to 8883 for "mqtts", "ssl" schemes.

The "mqtt" and "tcp" schemes are equivalent, and denote a use of TCP protocol without SSL/TLS. The "mqtts", "ssl" and "tls" schemes are equivalent, and denote a use of TCP protocol with SSL/TLS.

Using the clientId query parameter you can override the default clientId supplied by host software. Additional query parameters can be specified, and are ignored.

Examples: 

mqtt://test.mosquitto.org
mqtts://test.mosquitto.org

If the URL string has "ws" or "wss" scheme, WebSocket protocol (possibly with TLS, for "wss") will be used. In this case, the URL is passed onto the underlying library unchanged (the user info is still extracted from it and interpreted by the communication package).

Examples: 

ws://test.mosquitto.org:8080/mqtt
wss://test.mosquitto.org:8081/mqtt

If the scheme in the URL is not one of the schemes listed here, the message channel will still open, using the clientId and cleanSession flag provided by the host software, and all other parameters given by the configuration properties. This will fail under normal circumstances - unless you have carefully set all properties as necessary.

Interface name

The interface name, if provided by the host software, is ignored.

Certificates

Due to limitations imposed by the underlying library, if the host software specifies its own server certificate validation, this validation can allow additional server certificates be accepted over what the library accepts by default, but no server certificate accepted by the library by its default mechanism can be rejected by the host validation. Also, the host can provide a list of client certificates, but cannot influence the certificate selection.

Configuration

The table below lists the available properties, their types, and descriptions. Most properties come from configurable options of the underlying library, so please refer to the its documentation for details (we could not find a comprehensive reference documentation for this library, that's why most descriptions are missing). Do not get scared by the number of configurable properties; the relevant ones can usually stay at their defaults, or usually overridden from the host software (as noted). We will emphasize specific properties if they are important.

Property Type Description
ClientWaitTimeout System.Int32 Determines the maximum wait time for the client to open before publishing a message. In milliseconds.
ManagedMqttClientOptions MQTTnet.Extensions.ManagedClient.ManagedMqttClientOptions
ManagedMqttClientOptions.AutoReconnectDelay System.TimeSpan Default is 5 seconds.
ManagedMqttClientOptions.ClientOptions MQTTnet.Client.Options.IMqttClientOptions
ManagedMqttClientOptions.ConnectionCheckInterval System.TimeSpan Default is 1 second.
ManagedMqttClientOptions.MaxPendingMessages System.Int32 Default is 2^31-1.
ManagedMqttClientOptions.
PendingMessagesOverflowStrategy 		MQTTnet.Server.MqttPendingMessagesOverflowStrategy Default is DropNewMessage.
ManagedMqttClientOptions.Storage MQTTnet.Extensions.ManagedClient.IManagedMqttClientStorage
MqttClientOptions MQTTnet.Client.Options.MqttClientOptions
MqttClientOptions.AuthenticationData System.Byte[]
MqttClientOptions.AuthenticationMethod System.String
MqttClientOptions.ChannelOptions MQTTnet.Client.Options.IMqttClientChannelOptions Default value is null. For known URL schemes, it gets overridden by a value determined during URL resolution. For "mqtt", "mqtts", "ssl", "tcp" and "tls" schemes, value from the MqttClientTcpOptions property is used. For "ws", "wss" schemes, value from the MqttClientWebSocketOptions is used.
MqttClientOptions.CleanSession System.Boolean Always override by the value specified by the host software (do not use).
MqttClientOptions.ClientId System.String Default value is null. When null, gets overridden by the ClientId specified by the host software. For "mqtt", "mqtts", "ssl", "tcp" and "tls" URL schemes, it can further be overridden by a "clientId" query parameter in the URL.
MqttClientOptions.Credentials MQTTnet.Client.Options.IMqttClientCredentials Default value is null. When null, for "mqtt", "mqtts", "ssl", "tcp" and "tls" URL schemes, if the URL contains user-specific information, gets overridden by the credentials with user name and password from the URL.
MqttClientOptions.CommunicationTimeout System.Timespan Default is 10 seconds.
MqttClientOptions.
ExtendedAuthenticationExchangeHandler 		MQTTnet.Client.ExtendedAuthenticationExchange.IMqttExtendedAuthenticationExchangeHandler
MqttClientOptions.KeepAlivePeriod System.Timespan Default is 15 seconds.
MqttClientOptions.KeepAliveSendInterval System.Nullable<System.TimeSpan>
MqttClientOptions.MaximumPacketSize System.Nullable<System.UInt32>
MqttClientOptions.ProtocolVersion MQTTnet.Formatter.MqttProtocolVersion Default is V311. Other values: Unknown, V310, V500.
MqttClientOptions.ReceiveMaximum System.Nullable<UInt16>
MqttClientOptions.RequestProblemInformation System.Nullable<System.Boolean>
MqttClientOptions.RequestResponseInformation System.Nullable<System.Boolean>
MqttClientOptions.SessionExpiryInterval System.Nullable<System.UInt32>
MqttClientOptions.TopicAliasMaximum System.Nullable<System.UInt16>
MqttClientOptions.WillDelayInterval System.Nullable<System.UInt16>
MqttClientTcpOptions MQTTnet.Client.Options.MqttClientTcpOptions
MqttClientTcpOptions.AddressFamily System.Net.Sockets.AddressFamily Default is Unspecified.
MqttClientTcpOptions.BufferSize System.Int32 Default is 65536.
MqttClientTcpOptions.DualMode System.Nullable<System.Boolean>
MqttClientTcpOptions.NoDelay System.Boolean
MqttClientTcpOptions.Port System.Nullable<System.Int32> For "mqtt", "tcp" URL schemes, gets overridden by the value specified in the URL, or 1883 if not specified. For "mqtts", "ssl" and "tls" URL schemes, gets overridden by the value specified in the URL, or 8883 if not specified.
MqttClientTcpOptions.Server System.String
MqttClientTcpOptions.TlsOptions MQTTnet.Client.Options.MqttClientTlsOptions For "mqtt", "tcp", "mqtts", "ssl" and "tls" URL schemes, some sub-properties (described here) get overridden.
MqttClientTcpOptions.TlsOptions.
AllowUntrustedCertificates 		System.Boolean
MqttClientTcpOptions.TlsOptions.Certificates System.List<System.Security.Cryptography.X509Certificates.X509Certificate> (.NET Framework)
System.List<System.Byte[]> (.NET Standard) 		For "mqtts", "ssl" and "tls" URL schemes, may get overridden by hosting software.
MqttClientTcpOptions.TlsOptions.
CertificateValidationCallback 		System.Func<System.Security.Cryptography.X509Certificates.X509Certificate, System.Security.Cryptography.X509Certificates.X509Chain, System.Net.Security.SslPolicyErrors, MQTTnet.Client.Options.IMqttClientOptions, System.Boolean> For "mqtts", "ssl" and "tls" URL schemes, may get overridden by hosting software.
MqttClientTcpOptions.TlsOptions.
IgnoreCertificateChainErrors 		System.Boolean
MqttClientTcpOptions.TlsOptions.
IgnoreCertificateRevocationErrors 		System.Boolean
MqttClientTcpOptions.TlsOptions.SslProtocol System.Security.Authentication.SslProtocols Default is Tls12.
MqttClientTcpOptions.TlsOptions.UseTls System.Boolean Gets overriden to false for "mqtt", "tcp" URL schemes, gets overridden to true for "mqtts", "ssl" and "tls" URL schemes.
MqttClientWebSocketOptions MQTTnet.Client.Options.MqttClientWebSocketOptions
MqttClientWebSocketOptions.CookieContainer System.Net.CookieContainer
MqttClientWebSocketOptions.ProxyOptions MQTTnet.Client.Options.MqttClientWebSocketProxyOptions
MqttClientWebSocketOptions.RequestHeaders System.Collections.Generic.IDictionary<System.String, System.String>
MqttClientWebSocketOptions.SubProtocols System.Collections.Generic.ICollection<System.String> Default is { "mqtt" }.
MqttClientWebSocketOptions.TlsOptions MQTTnet.Client.Options.MqttClientTlsOptions For "ws", "wss" URL schemes, some sub-properties (described here) get overridden.
MqttClientWebSocketOptions.TlsOptions.
AllowUntrustedCertificates 		System.Boolean
MqttClientWebSocketOptions.TlsOptions.Certificates System.List<System.Security.Cryptography.X509Certificates.X509Certificate> (.NET Framework)
System.List<System.Byte[]> (.NET Standard) 		For "wss" URL scheme, may get overridden by hosting software.
MqttClientWebSocketOptions.TlsOptions.
CertificateValidationCallback 		System.Func<System.Security.Cryptography.X509Certificates.X509Certificate, System.Security.Cryptography.X509Certificates.X509Chain, System.Net.Security.SslPolicyErrors, MQTTnet.Client.Options.IMqttClientOptions, System.Boolean> For "wss" URL scheme, may get overridden by hosting software.
MqttClientWebSocketOptions.TlsOptions.
IgnoreCertificateChainErrors 		System.Boolean
MqttClientWebSocketOptions.TlsOptions.
IgnoreCertificateRevocationErrors 		System.Boolean
MqttClientWebSocketOptions.TlsOptions.SslProtocol System.Security.Authentication.SslProtocols Default is Tls12.
MqttClientWebSocketOptions.TlsOptions.UseTls System.Boolean Gets overridden to false for "ws" URL scheme, gets overridden to true for "wss" URL scheme.
MqttClientWebSocketOptions.Uri System.String For "ws", "wss" URL schemes, gets overridden by the input URL string.

Server (broker) role

Not implemented. In development. The type name of the message channel object is: OpcLabs.MqttNet.ManagedMqttServerMessageChannel,OpcLabs.MqttNet .

See also

Certificate security plugin

Retrieved from "https://kb.opclabs.com/index.php?title=OpcLabs.MqttNet_communication_package&oldid=5591"