mosquitto_plugin.h

This header contains function declarations for use when writing a Mosquitto plugin.

Summary
mosquitto_plugin.hThis header contains function declarations for use when writing a Mosquitto plugin.
Plugin Functions v5This is the plugin version 5 interface, which covers authentication, access control, the $CONTROL topic space handling, and message inspection and modification.
Functions
mosquitto_plugin_versionThe broker will attempt to call this function immediately after loading the plugin to check it is a supported plugin version.
mosquitto_plugin_initCalled after the plugin has been loaded and mosquitto_plugin_version has been called.
mosquitto_plugin_cleanupCalled when the broker is shutting down.
Plugin Functions v4This is the plugin version 4 interface, which is exclusively for authentication and access control, and which is still supported for existing plugins.
Functions
mosquitto_auth_plugin_versionThe broker will call this function immediately after loading the plugin to check it is a supported plugin version.
mosquitto_auth_plugin_initCalled after the plugin has been loaded and mosquitto_auth_plugin_version has been called.
mosquitto_auth_plugin_cleanupCalled when the broker is shutting down.
mosquitto_auth_security_init1.
mosquitto_auth_security_cleanup1.
mosquitto_auth_acl_checkCalled by the broker when topic access must be checked.
mosquitto_auth_unpwd_checkThis function is OPTIONAL.
mosquitto_psk_key_getThis function is OPTIONAL.
mosquitto_auth_startThis function is OPTIONAL.

Plugin Functions v5

This is the plugin version 5 interface, which covers authentication, access control, the $CONTROL topic space handling, and message inspection and modification.

This interface is available from v2.0 onwards.

There are just three functions to implement in your plugin.  You should register callbacks to handle different events in your mosquitto_plugin_init() function.  See mosquitto_broker.h for the events and callback registering functions.

Summary
Functions
mosquitto_plugin_versionThe broker will attempt to call this function immediately after loading the plugin to check it is a supported plugin version.
mosquitto_plugin_initCalled after the plugin has been loaded and mosquitto_plugin_version has been called.
mosquitto_plugin_cleanupCalled when the broker is shutting down.

Functions

mosquitto_plugin_version

mosq_plugin_EXPORT int mosquitto_plugin_version(int supported_version_count,
const int *supported_versions)

The broker will attempt to call this function immediately after loading the plugin to check it is a supported plugin version.  Your code must simply return the plugin interface version you support, i.e.  5.

The supported_versions array tells you which plugin versions the broker supports.

If the broker does not support the version that you require, return -1 to indicate failure.

mosquitto_plugin_init

mosq_plugin_EXPORT int mosquitto_plugin_init(mosquitto_plugin_id_t *identifier,
void **userdata,
struct mosquitto_opt *options,
int option_count)

Called after the plugin has been loaded and mosquitto_plugin_version has been called.  This will only ever be called once and can be used to initialise the plugin.

Parameters

identifierThis is a pointer to an opaque structure which you must save and use when registering/unregistering callbacks.
user_dataThe pointer set here will be passed to the other plugin functions.  Use to hold connection information for example.
optsPointer to an array of struct mosquitto_opt, which provides the plugin options defined in the configuration file.
opt_countThe number of elements in the opts array.

Return value

Return 0 on success Return >0 on failure.

mosquitto_plugin_cleanup

mosq_plugin_EXPORT int mosquitto_plugin_cleanup(void *userdata,
struct mosquitto_opt *options,
int option_count)

Called when the broker is shutting down.  This will only ever be called once per plugin.

Parameters

user_dataThe pointer provided in mosquitto_plugin_init.
optsPointer to an array of struct mosquitto_opt, which provides the plugin options defined in the configuration file.
opt_countThe number of elements in the opts array.

Return value

Return 0 on success Return >0 on failure.

Plugin Functions v4

This is the plugin version 4 interface, which is exclusively for authentication and access control, and which is still supported for existing plugins.  If you are developing a new plugin, please use the v5 interface.

You must implement these functions in your plugin.

Summary
Functions
mosquitto_auth_plugin_versionThe broker will call this function immediately after loading the plugin to check it is a supported plugin version.
mosquitto_auth_plugin_initCalled after the plugin has been loaded and mosquitto_auth_plugin_version has been called.
mosquitto_auth_plugin_cleanupCalled when the broker is shutting down.
mosquitto_auth_security_init1.
mosquitto_auth_security_cleanup1.
mosquitto_auth_acl_checkCalled by the broker when topic access must be checked.
mosquitto_auth_unpwd_checkThis function is OPTIONAL.
mosquitto_psk_key_getThis function is OPTIONAL.
mosquitto_auth_startThis function is OPTIONAL.

Functions

mosquitto_auth_plugin_version

mosq_plugin_EXPORT int mosquitto_auth_plugin_version(void)

The broker will call this function immediately after loading the plugin to check it is a supported plugin version.  Your code must simply return the version of the plugin interface you support, i.e.  4.

mosquitto_auth_plugin_init

mosq_plugin_EXPORT int mosquitto_auth_plugin_init(void **user_data,
struct mosquitto_opt *opts,
int opt_count)

Called after the plugin has been loaded and mosquitto_auth_plugin_version has been called.  This will only ever be called once and can be used to initialise the plugin.

Parameters

user_dataThe pointer set here will be passed to the other plugin functions.  Use to hold connection information for example.
optsPointer to an array of struct mosquitto_opt, which provides the plugin options defined in the configuration file.
opt_countThe number of elements in the opts array.

Return value

Return 0 on success Return >0 on failure.

mosquitto_auth_plugin_cleanup

mosq_plugin_EXPORT int mosquitto_auth_plugin_cleanup(
   void *user_data,
   struct mosquitto_opt *opts,
   int opt_count
)

Called when the broker is shutting down.  This will only ever be called once per plugin.  Note that mosquitto_auth_security_cleanup will be called directly before this function.

Parameters

user_dataThe pointer provided in mosquitto_auth_plugin_init.
optsPointer to an array of struct mosquitto_opt, which provides the plugin options defined in the configuration file.
opt_countThe number of elements in the opts array.

Return value

Return 0 on success Return >0 on failure.

mosquitto_auth_security_init

mosq_plugin_EXPORT int mosquitto_auth_security_init(
   void *user_data,
   struct mosquitto_opt *opts,
   int opt_count,
   bool reload
)

This function is called in two scenarios

1.  When the broker starts up.  2. If the broker is requested to reload its configuration whilst running.  In this case, mosquitto_auth_security_cleanup will be called first, then this function will be called.  In this situation, the reload parameter will be true.

Parameters

user_dataThe pointer provided in mosquitto_auth_plugin_init.
optsPointer to an array of struct mosquitto_opt, which provides the plugin options defined in the configuration file.
opt_countThe number of elements in the opts array.
reloadIf set to false, this is the first time the function has been called.  If true, the broker has received a signal asking to reload its configuration.

Return value

Return 0 on success Return >0 on failure.

mosquitto_auth_security_cleanup

mosq_plugin_EXPORT int mosquitto_auth_security_cleanup(
   void *user_data,
   struct mosquitto_opt *opts,
   int opt_count,
   bool reload
)

This function is called in two scenarios

1.  When the broker is shutting down.  2. If the broker is requested to reload its configuration whilst running.  In this case, this function will be called, followed by mosquitto_auth_security_init.  In this situation, the reload parameter will be true.

Parameters

user_dataThe pointer provided in mosquitto_auth_plugin_init.
optsPointer to an array of struct mosquitto_opt, which provides the plugin options defined in the configuration file.
opt_countThe number of elements in the opts array.
reloadIf set to false, this is the first time the function has been called.  If true, the broker has received a signal asking to reload its configuration.

Return value

Return 0 on success Return >0 on failure.

mosquitto_auth_acl_check

mosq_plugin_EXPORT int mosquitto_auth_acl_check(
   void *user_data,
   int access,
   struct mosquitto *client,
   const struct mosquitto_acl_msg *msg
)

Called by the broker when topic access must be checked. access will be one of: MOSQ_ACL_SUBSCRIBE when a client is asking to subscribe to a topic string.  This differs from MOSQ_ACL_READ in that it allows you to deny access to topic strings rather than by pattern.  For example, you may use MOSQ_ACL_SUBSCRIBE to deny subscriptions to ‘#’, but allow all topics in MOSQ_ACL_READ.  This allows clients to subscribe to any topic they want, but not discover what topics are in use on the server.  MOSQ_ACL_READ when a message is about to be sent to a client (i.e. whether it can read that topic or not).  MOSQ_ACL_WRITE when a message has been received from a client (i.e. whether it can write to that topic or not).

Return

MOSQ_ERR_SUCCESS if access was granted.  MOSQ_ERR_ACL_DENIED if access was not granted.  MOSQ_ERR_UNKNOWN for an application specific error.  MOSQ_ERR_PLUGIN_DEFER if your plugin does not wish to handle this check.

mosquitto_auth_unpwd_check

mosq_plugin_EXPORT int mosquitto_auth_unpwd_check(void *user_data,
struct mosquitto *client,
const char *username,
const char *password)

This function is OPTIONAL.  Only include this function in your plugin if you are making basic username/password checks.

Called by the broker when a username/password must be checked.

Return

MOSQ_ERR_SUCCESS if the user is authenticated.  MOSQ_ERR_AUTH if authentication failed.  MOSQ_ERR_UNKNOWN for an application specific error.  MOSQ_ERR_PLUGIN_DEFER if your plugin does not wish to handle this check.

mosquitto_psk_key_get

This function is OPTIONAL.  Only include this function in your plugin if you are making TLS-PSK checks.

Called by the broker when a client connects to a listener using TLS/PSK.  This is used to retrieve the pre-shared-key associated with a client identity.

Examine hint and identity to determine the required PSK (which must be a hexadecimal string with no leading “0x”) and copy this string into key.

Parameters

user_datathe pointer provided in mosquitto_auth_plugin_init.
hintthe psk_hint for the listener the client is connecting to.
identitythe identity string provided by the client
keya string where the hex PSK should be copied
max_key_lenthe size of key

Return value

Return 0 on success.  Return >0 on failure.  Return MOSQ_ERR_PLUGIN_DEFER if your plugin does not wish to handle this check.

mosquitto_auth_start

mosq_plugin_EXPORT int mosquitto_auth_start(void *user_data,
struct mosquitto *client,
const char *method,
bool reauth,
const void *data_in,
uint16_t data_in_len,
void **data_out,
uint16_t *data_out_len)

This function is OPTIONAL.  Only include this function in your plugin if you are making extended authentication checks.

Parameters

user_datathe pointer provided in mosquitto_auth_plugin_init.
methodthe authentication method
reauththis is set to false if this is the first authentication attempt on a connection, set to true if the client is attempting to reauthenticate.
data_inpointer to authentication data, or NULL
data_in_lenlength of data_in, in bytes
data_outif your plugin wishes to send authentication data back to the client, allocate some memory using malloc or friends and set data_out.  The broker will free the memory after use.
data_out_lenSet the length of data_out in bytes.

Return value

Return MOSQ_ERR_SUCCESS if authentication was successful.  Return MOSQ_ERR_AUTH_CONTINUE if the authentication is a multi step process and can continue.  Return MOSQ_ERR_AUTH if authentication was valid but did not succeed.  Return any other relevant positive integer MOSQ_ERR_* to produce an error.

mosq_plugin_EXPORT int mosquitto_plugin_version(int supported_version_count,
const int *supported_versions)
The broker will attempt to call this function immediately after loading the plugin to check it is a supported plugin version.
mosq_plugin_EXPORT int mosquitto_plugin_init(mosquitto_plugin_id_t *identifier,
void **userdata,
struct mosquitto_opt *options,
int option_count)
Called after the plugin has been loaded and mosquitto_plugin_version has been called.
mosq_plugin_EXPORT int mosquitto_plugin_cleanup(void *userdata,
struct mosquitto_opt *options,
int option_count)
Called when the broker is shutting down.
mosq_plugin_EXPORT int mosquitto_auth_plugin_version(void)
The broker will call this function immediately after loading the plugin to check it is a supported plugin version.
mosq_plugin_EXPORT int mosquitto_auth_plugin_init(void **user_data,
struct mosquitto_opt *opts,
int opt_count)
Called after the plugin has been loaded and mosquitto_auth_plugin_version has been called.
mosq_plugin_EXPORT int mosquitto_auth_plugin_cleanup(
   void *user_data,
   struct mosquitto_opt *opts,
   int opt_count
)
Called when the broker is shutting down.
mosq_plugin_EXPORT int mosquitto_auth_security_init(
   void *user_data,
   struct mosquitto_opt *opts,
   int opt_count,
   bool reload
)
1.
mosq_plugin_EXPORT int mosquitto_auth_security_cleanup(
   void *user_data,
   struct mosquitto_opt *opts,
   int opt_count,
   bool reload
)
1.
mosq_plugin_EXPORT int mosquitto_auth_acl_check(
   void *user_data,
   int access,
   struct mosquitto *client,
   const struct mosquitto_acl_msg *msg
)
Called by the broker when topic access must be checked.
mosq_plugin_EXPORT int mosquitto_auth_unpwd_check(void *user_data,
struct mosquitto *client,
const char *username,
const char *password)
This function is OPTIONAL.
mosq_plugin_EXPORT int mosquitto_auth_start(void *user_data,
struct mosquitto *client,
const char *method,
bool reauth,
const void *data_in,
uint16_t data_in_len,
void **data_out,
uint16_t *data_out_len)
This function is OPTIONAL.
Close