mosquitto_plugin.h

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.

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

Return value

Return 0 on success Return >0 on failure.

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

Return value

Return 0 on success Return >0 on failure.

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.

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

Return value

Return 0 on success Return >0 on failure.

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

Return value

Return 0 on success Return >0 on failure.

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

Return value

Return 0 on success Return >0 on failure.

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

Return value

Return 0 on success Return >0 on failure.

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.

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.

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

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.

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

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.