mTLS

Client certificates are a popular way of adding an extra layer of security to your client authentication. It can either be added on top or instead of the regular authentication provided by the role based authentication using username and password. While connecting, a client identifies using a client certificate. The broker has stored a client certificate authority and allows a connection, if the client certificate gets validated, the connection is allowed.

The CA Management allows the upload of client CAs to the broker via a UI.

Listener configuration

MTLS has to be activated on a port (listener) level.

Default Cloud configuration

The default broker configuration, when mTLS is selected in a cloud subscription for a port looks like this (shown with port 8883):

# Listener for the application, MQTTS over TCP with client certs
listener 8883
certfile /mosquitto/config/certs/server.pem
keyfile /mosquitto/config/certs/server.key
capath /mosquitto/config/capath_mqtts
require_certificate true

enable_control_api true

plugin /usr/lib/cedalo_certificate_management.so

If you need any changes to this default please contact our support team.

On-premises configuration

The following options can be used for mTLS configuration.

Certificate and Key Settings (Server-side)

• cafile <path>: Specifies the path to the Certificate Authority (CA) file that the broker will use to validate client certificates.
• capath <path>: Specifies the path to the Certificate Authority (CA) folder that the broker will use to validate client certificates. This is needed if more then one file is present.
• certfile <path>: The server's public certificate file that will be presented to clients during the TLS handshake.
• keyfile <path>: The server's private key file used to establish the TLS connection. The private key should remain secure and not be shared.

The path of the capath configuration should contain at least a root CA cert.

Note: The cafile configuration with a single PEM file containing the CA chain is currently not supported for this command.

Certificate and Key Settings (Client-side validation)

• require_certificate <true|false>: Determines whether clients are required to present a valid certificate for authentication. Set this to true to enforce mTLS.
• tls_version <version>: Specifies the minimum TLS version allowed for the connection. Common values include tlsv1.2 or tlsv1.3 to ensure a secure connection.
• use_identity_as_username <true|false>: If set to true, the broker will use the client certificate's Common Name (CN) field as the client's username for authentication.

Plugin configuration

To enable the plugin it must be loaded into the broker with, by adding the following to your mosquitto.conf:

plugin /usr/lib/cedalo_certificate_management.so

Control API

In addition to enable the brokers internal $CONTROL/broker/v1 API we need to add:

enable_control_api true

This is required to determine the listeners identifier, where the changes should be applied to.

This plugin provides a Mosquitto control API which manages client CA certificates for certificate based authentication/validation. The topic of the plugins control API is $CONTROL/certificate-management/v1. Currently, supported commands offered by the API are insertCACertificate, which can be used to extend the existing Certificate Authority (CA) Chain or just the Root CA by an additional signing/validating certificate. To get rid of a previously added CA cert, the deleteCACertificate command can be used.