/src/mosquitto/include/mosquitto/broker_plugin.h

Source
/*
Copyright (c) 2012-2021 Roger Light <roger@atchoo.org>

All rights reserved. This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
and Eclipse Distribution License v1.0 which accompany this distribution.

The Eclipse Public License is available at
   https://www.eclipse.org/legal/epl-2.0/
and the Eclipse Distribution License is available at
  http://www.eclipse.org/org/documents/edl-v10.php.

SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause

Contributors:
   Roger Light - initial implementation and documentation.
*/

#ifndef MOSQUITTO_BROKER_PLUGIN_H
#define MOSQUITTO_BROKER_PLUGIN_H

/*
 * File: mosquitto_plugin.h
 *
 * This header contains function declarations for use when writing a Mosquitto plugin.
 */

#ifdef __cplusplus
extern "C" {
#endif

/* The generic plugin interface starts at version 5 */
#define MOSQ_PLUGIN_VERSION 5

/* The old auth only interface stopped at version 4 */
#define MOSQ_AUTH_PLUGIN_VERSION 4

#define MOSQ_ACL_NONE 0x00
#define MOSQ_ACL_READ 0x01
#define MOSQ_ACL_WRITE 0x02
#define MOSQ_ACL_SUBSCRIBE 0x04
#define MOSQ_ACL_UNSUBSCRIBE 0x08

#include <stdbool.h>
#include <stdint.h>

#include <mosquitto.h>
#include <mosquitto/broker.h>

struct mosquitto;

struct mosquitto_opt {
  char *key;
  char *value;
};

struct mosquitto_auth_opt {
  char *key;
  char *value;
};

struct mosquitto_acl_msg {
  const char *topic;
  const void *payload;
  long payloadlen;
  int qos;
  bool retain;
};

#ifdef WIN32
#  define mosq_plugin_EXPORT __declspec(dllexport)
#else
#  define mosq_plugin_EXPORT
#endif

/*
 * To create an authentication plugin you must include this file then implement
 * the functions listed in the "Plugin Functions" section below. The resulting
 * code should then be compiled as a shared library. Using gcc this can be
 * achieved as follows:
 *
 * gcc -I<path to mosquitto_plugin.h> -fPIC -shared plugin.c -o plugin.so
 *
 * On Mac OS X:
 *
 * gcc -I<path to mosquitto_plugin.h> -fPIC -shared plugin.c -undefined dynamic_lookup -o plugin.so
 *
 */

/* =========================================================================
 *
 * Helper Functions
 *
 * ========================================================================= */

/* There are functions that are available for plugin developers to use in
 * mosquitto_broker.h, including logging and accessor functions.
 */


/* =========================================================================
 *
 * Section: 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.
 *
 * ========================================================================= */

/*
 * Function: mosquitto_plugin_version
 *
 * 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.
 *
 * HELPER: If you only wish to declare support for a single version, you can
 * use the helper macro:
 *
 * MOSQUITTO_PLUGIN_DECLARE_VERSION(5);
 */
mosq_plugin_EXPORT int mosquitto_plugin_version(int supported_version_count, const int *supported_versions);

#define MOSQUITTO_PLUGIN_DECLARE_VERSION(A) \
    int mosquitto_plugin_version(int supported_version_count, const int *supported_versions) \
    { \
      int i; \
      for(i=0; i<supported_version_count; i++){ \
        if(supported_versions[i] == (A)){ \
          return (A); \
        } \
      } \
      return -1; \
    }

/*
 * Function: mosquitto_plugin_init
 *
 * 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:
 *
 *  identifier -     This is a pointer to an opaque structure which you must
 *                   save and use when registering/unregistering callbacks.
 *  user_data -      The pointer set here will be passed to the other plugin
 *                   functions. Use to hold connection information for example.
 *  opts -           Pointer to an array of struct mosquitto_opt, which
 *                   provides the plugin options defined in the configuration file.
 *  opt_count -      The number of elements in the opts array.
 *
 * Return value:
 *  Return 0 on success
 *  Return >0 on failure.
 */
mosq_plugin_EXPORT int mosquitto_plugin_init(mosquitto_plugin_id_t *identifier, void **userdata, struct mosquitto_opt *options, int option_count);


/*
 * Function: mosquitto_plugin_cleanup
 *
 * Called when the broker is shutting down. This will only ever be called once
 * per plugin.
 *
 * If you do not need to do any of your own cleanup, this function is not
 * required. The broker will automatically unregister your callbacks.
 *
 * Parameters:
 *
 *  user_data -      The pointer provided in <mosquitto_plugin_init>.
 *  opts -           Pointer to an array of struct mosquitto_opt, which
 *                   provides the plugin options defined in the configuration file.
 *  opt_count -      The number of elements in the opts array.
 *
 * 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);



/* =========================================================================
 *
 * Section: 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.
 *
 * Authentication plugins can implement one or both of authentication and
 * access control. If your plugin does not wish to handle either of
 * authentication or access control it should return MOSQ_ERR_PLUGIN_DEFER. In
 * this case, the next plugin will handle it. If all plugins return
 * MOSQ_ERR_PLUGIN_DEFER, the request will be denied.
 *
 * For each check, the following flow happens:
 *
 * * The default password file and/or acl file checks are made. If either one
 *   of these is not defined, then they are considered to be deferred. If either
 *   one accepts the check, no further checks are made. If an error occurs, the
 *   check is denied
 * * The first plugin does the check, if it returns anything other than
 *   MOSQ_ERR_PLUGIN_DEFER, then the check returns immediately. If the plugin
 *   returns MOSQ_ERR_PLUGIN_DEFER then the next plugin runs its check.
 * * If the final plugin returns MOSQ_ERR_PLUGIN_DEFER, then access will be
 *   denied.
 * ========================================================================= */

/*
 * Function: mosquitto_auth_plugin_version
 *
 * 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_version(void);


/*
 * Function: mosquitto_auth_plugin_init
 *
 * 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_data -      The pointer set here will be passed to the other plugin
 *                   functions. Use to hold connection information for example.
 *  opts -           Pointer to an array of struct mosquitto_opt, which
 *                   provides the plugin options defined in the configuration file.
 *  opt_count -      The number of elements in the opts array.
 *
 * Return value:
 *  Return 0 on success
 *  Return >0 on failure.
 */
mosq_plugin_EXPORT int mosquitto_auth_plugin_init(void **user_data, struct mosquitto_opt *opts, int opt_count);


/*
 * Function: mosquitto_auth_plugin_cleanup
 *
 * 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_data -      The pointer provided in <mosquitto_auth_plugin_init>.
 *  opts -           Pointer to an array of struct mosquitto_opt, which
 *                   provides the plugin options defined in the configuration file.
 *  opt_count -      The number of elements in the opts array.
 *
 * 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);


/*
 * Function: mosquitto_auth_security_init
 *
 * 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_data -      The pointer provided in <mosquitto_auth_plugin_init>.
 *  opts -           Pointer to an array of struct mosquitto_opt, which
 *                   provides the plugin options defined in the configuration file.
 *  opt_count -      The number of elements in the opts array.
 *  reload -         If 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.
 */
mosq_plugin_EXPORT int mosquitto_auth_security_init(void *user_data, struct mosquitto_opt *opts, int opt_count, bool reload);


/*
 * Function: mosquitto_auth_security_cleanup
 *
 * 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_data -      The pointer provided in <mosquitto_auth_plugin_init>.
 *  opts -           Pointer to an array of struct mosquitto_opt, which
 *                   provides the plugin options defined in the configuration file.
 *  opt_count -      The number of elements in the opts array.
 *  reload -         If 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.
 */
mosq_plugin_EXPORT int mosquitto_auth_security_cleanup(void *user_data, struct mosquitto_opt *opts, int opt_count, bool reload);


/*
 * Function: mosquitto_auth_acl_check
 *
 * 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_acl_check(void *user_data, int access, struct mosquitto *client, const struct mosquitto_acl_msg *msg);


/*
 * Function: mosquitto_auth_unpwd_check
 *
 * 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.
 */
mosq_plugin_EXPORT int mosquitto_auth_unpwd_check(void *user_data, struct mosquitto *client, const char *username, const char *password);


/*
 * Function: 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_data -   the pointer provided in <mosquitto_auth_plugin_init>.
 *  hint -        the psk_hint for the listener the client is connecting to.
 *  identity -    the identity string provided by the client
 *  key -         a string where the hex PSK should be copied
 *  max_key_len - the 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.
 */
mosq_plugin_EXPORT int mosquitto_auth_psk_key_get(void *user_data, struct mosquitto *client, const char *hint, const char *identity, char *key, int max_key_len);

/*
 * Function: mosquitto_auth_start
 *
 * This function is OPTIONAL. Only include this function in your plugin if you
 * are making extended authentication checks.
 *
 * Parameters:
 *  user_data -   the pointer provided in <mosquitto_auth_plugin_init>.
 *  method - the authentication method
 *  reauth - this 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_in - pointer to authentication data, or NULL
 *  data_in_len - length of data_in, in bytes
 *  data_out - if 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_len - Set 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_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);

mosq_plugin_EXPORT int mosquitto_auth_continue(void *user_data, struct mosquitto *client, const char *method, const void *data_in, uint16_t data_in_len, void **data_out, uint16_t *data_out_len);


#ifdef __cplusplus
}
#endif

#endif

Coverage Report

Created: 2025-12-29 07:00

Line	Count	Source
1		/*
2		Copyright (c) 2012-2021 Roger Light <roger@atchoo.org>
3
4		All rights reserved. This program and the accompanying materials
5		are made available under the terms of the Eclipse Public License 2.0
6		and Eclipse Distribution License v1.0 which accompany this distribution.
7
8		The Eclipse Public License is available at
9		https://www.eclipse.org/legal/epl-2.0/
10		and the Eclipse Distribution License is available at
11		http://www.eclipse.org/org/documents/edl-v10.php.
12
13		SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
14
15		Contributors:
16		Roger Light - initial implementation and documentation.
17		*/
18
19		#ifndef MOSQUITTO_BROKER_PLUGIN_H
20		#define MOSQUITTO_BROKER_PLUGIN_H
21
22		/*
23		* File: mosquitto_plugin.h
24		*
25		* This header contains function declarations for use when writing a Mosquitto plugin.
26		*/
27
28		#ifdef __cplusplus
29		extern "C" {
30		#endif
31
32		/* The generic plugin interface starts at version 5 */
33	0	#define MOSQ_PLUGIN_VERSION 5
34
35		/* The old auth only interface stopped at version 4 */
36		#define MOSQ_AUTH_PLUGIN_VERSION 4
37
38	830k	#define MOSQ_ACL_NONE 0x00
39	823k	#define MOSQ_ACL_READ 0x01
40	823k	#define MOSQ_ACL_WRITE 0x02
41	1.70M	#define MOSQ_ACL_SUBSCRIBE 0x04
42	4.17M	#define MOSQ_ACL_UNSUBSCRIBE 0x08
43
44		#include <stdbool.h>
45		#include <stdint.h>
46
47		#include <mosquitto.h>
48		#include <mosquitto/broker.h>
49
50		struct mosquitto;
51
52		struct mosquitto_opt {
53		char *key;
54		char *value;
55		};
56
57		struct mosquitto_auth_opt {
58		char *key;
59		char *value;
60		};
61
62		struct mosquitto_acl_msg {
63		const char *topic;
64		const void *payload;
65		long payloadlen;
66		int qos;
67		bool retain;
68		};
69
70		#ifdef WIN32
71		# define mosq_plugin_EXPORT __declspec(dllexport)
72		#else
73		# define mosq_plugin_EXPORT
74		#endif
75
76		/*
77		* To create an authentication plugin you must include this file then implement
78		* the functions listed in the "Plugin Functions" section below. The resulting
79		* code should then be compiled as a shared library. Using gcc this can be
80		* achieved as follows:
81		*
82		* gcc -I<path to mosquitto_plugin.h> -fPIC -shared plugin.c -o plugin.so
83		*
84		* On Mac OS X:
85		*
86		* gcc -I<path to mosquitto_plugin.h> -fPIC -shared plugin.c -undefined dynamic_lookup -o plugin.so
87		*
88		*/
89
90		/* =========================================================================
91		*
92		* Helper Functions
93		*
94		* ========================================================================= */
95
96		/* There are functions that are available for plugin developers to use in
97		* mosquitto_broker.h, including logging and accessor functions.
98		*/
99
100
101		/* =========================================================================
102		*
103		* Section: Plugin Functions v5
104		*
105		* This is the plugin version 5 interface, which covers authentication, access
106		* control, the $CONTROL topic space handling, and message inspection and
107		* modification.
108		*
109		* This interface is available from v2.0 onwards.
110		*
111		* There are just three functions to implement in your plugin. You should
112		* register callbacks to handle different events in your
113		* mosquitto_plugin_init() function. See mosquitto_broker.h for the events and
114		* callback registering functions.
115		*
116		* ========================================================================= */
117
118		/*
119		* Function: mosquitto_plugin_version
120		*
121		* The broker will attempt to call this function immediately after loading the
122		* plugin to check it is a supported plugin version. Your code must simply
123		* return the plugin interface version you support, i.e. 5.
124		*
125		* The supported_versions array tells you which plugin versions the broker supports.
126		*
127		* If the broker does not support the version that you require, return -1 to
128		* indicate failure.
129		*
130		* HELPER: If you only wish to declare support for a single version, you can
131		* use the helper macro:
132		*
133		* MOSQUITTO_PLUGIN_DECLARE_VERSION(5);
134		*/
135		mosq_plugin_EXPORT int mosquitto_plugin_version(int supported_version_count, const int *supported_versions);
136
137		#define MOSQUITTO_PLUGIN_DECLARE_VERSION(A) \
138		int mosquitto_plugin_version(int supported_version_count, const int *supported_versions) \
139	0	{ \
140	0	int i; \
141	0	for(i=0; i<supported_version_count; i++){ \
142	0	if(supported_versions[i] == (A)){ \
143	0	return (A); \
144	0	} \
145	0	} \
146	0	return -1; \
147	0	}
148
149		/*
150		* Function: mosquitto_plugin_init
151		*
152		* Called after the plugin has been loaded and <mosquitto_plugin_version>
153		* has been called. This will only ever be called once and can be used to
154		* initialise the plugin.
155		*
156		* Parameters:
157		*
158		* identifier - This is a pointer to an opaque structure which you must
159		* save and use when registering/unregistering callbacks.
160		* user_data - The pointer set here will be passed to the other plugin
161		* functions. Use to hold connection information for example.
162		* opts - Pointer to an array of struct mosquitto_opt, which
163		* provides the plugin options defined in the configuration file.
164		* opt_count - The number of elements in the opts array.
165		*
166		* Return value:
167		* Return 0 on success
168		* Return >0 on failure.
169		*/
170		mosq_plugin_EXPORT int mosquitto_plugin_init(mosquitto_plugin_id_t identifier, void userdata, struct mosquitto_opt options, int option_count);
171
172
173		/*
174		* Function: mosquitto_plugin_cleanup
175		*
176		* Called when the broker is shutting down. This will only ever be called once
177		* per plugin.
178		*
179		* If you do not need to do any of your own cleanup, this function is not
180		* required. The broker will automatically unregister your callbacks.
181		*
182		* Parameters:
183		*
184		* user_data - The pointer provided in <mosquitto_plugin_init>.
185		* opts - Pointer to an array of struct mosquitto_opt, which
186		* provides the plugin options defined in the configuration file.
187		* opt_count - The number of elements in the opts array.
188		*
189		* Return value:
190		* Return 0 on success
191		* Return >0 on failure.
192		*/
193		mosq_plugin_EXPORT int mosquitto_plugin_cleanup(void userdata, struct mosquitto_opt options, int option_count);
194
195
196
197		/* =========================================================================
198		*
199		* Section: Plugin Functions v4
200		*
201		* This is the plugin version 4 interface, which is exclusively for
202		* authentication and access control, and which is still supported for existing
203		* plugins. If you are developing a new plugin, please use the v5 interface.
204		*
205		* You must implement these functions in your plugin.
206		*
207		* Authentication plugins can implement one or both of authentication and
208		* access control. If your plugin does not wish to handle either of
209		* authentication or access control it should return MOSQ_ERR_PLUGIN_DEFER. In
210		* this case, the next plugin will handle it. If all plugins return
211		* MOSQ_ERR_PLUGIN_DEFER, the request will be denied.
212		*
213		* For each check, the following flow happens:
214		*
215		* * The default password file and/or acl file checks are made. If either one
216		* of these is not defined, then they are considered to be deferred. If either
217		* one accepts the check, no further checks are made. If an error occurs, the
218		* check is denied
219		* * The first plugin does the check, if it returns anything other than
220		* MOSQ_ERR_PLUGIN_DEFER, then the check returns immediately. If the plugin
221		* returns MOSQ_ERR_PLUGIN_DEFER then the next plugin runs its check.
222		* * If the final plugin returns MOSQ_ERR_PLUGIN_DEFER, then access will be
223		* denied.
224		* ========================================================================= */
225
226		/*
227		* Function: mosquitto_auth_plugin_version
228		*
229		* The broker will call this function immediately after loading the plugin to
230		* check it is a supported plugin version. Your code must simply return
231		* the version of the plugin interface you support, i.e. 4.
232		*/
233		mosq_plugin_EXPORT int mosquitto_auth_plugin_version(void);
234
235
236		/*
237		* Function: mosquitto_auth_plugin_init
238		*
239		* Called after the plugin has been loaded and <mosquitto_auth_plugin_version>
240		* has been called. This will only ever be called once and can be used to
241		* initialise the plugin.
242		*
243		* Parameters:
244		*
245		* user_data - The pointer set here will be passed to the other plugin
246		* functions. Use to hold connection information for example.
247		* opts - Pointer to an array of struct mosquitto_opt, which
248		* provides the plugin options defined in the configuration file.
249		* opt_count - The number of elements in the opts array.
250		*
251		* Return value:
252		* Return 0 on success
253		* Return >0 on failure.
254		*/
255		mosq_plugin_EXPORT int mosquitto_auth_plugin_init(void *user_data, struct mosquitto_opt opts, int opt_count);
256
257
258		/*
259		* Function: mosquitto_auth_plugin_cleanup
260		*
261		* Called when the broker is shutting down. This will only ever be called once
262		* per plugin.
263		* Note that <mosquitto_auth_security_cleanup> will be called directly before
264		* this function.
265		*
266		* Parameters:
267		*
268		* user_data - The pointer provided in <mosquitto_auth_plugin_init>.
269		* opts - Pointer to an array of struct mosquitto_opt, which
270		* provides the plugin options defined in the configuration file.
271		* opt_count - The number of elements in the opts array.
272		*
273		* Return value:
274		* Return 0 on success
275		* Return >0 on failure.
276		*/
277		mosq_plugin_EXPORT int mosquitto_auth_plugin_cleanup(void user_data, struct mosquitto_opt opts, int opt_count);
278
279
280		/*
281		* Function: mosquitto_auth_security_init
282		*
283		* This function is called in two scenarios:
284		*
285		* 1. When the broker starts up.
286		* 2. If the broker is requested to reload its configuration whilst running. In
287		* this case, <mosquitto_auth_security_cleanup> will be called first, then
288		* this function will be called. In this situation, the reload parameter
289		* will be true.
290		*
291		* Parameters:
292		*
293		* user_data - The pointer provided in <mosquitto_auth_plugin_init>.
294		* opts - Pointer to an array of struct mosquitto_opt, which
295		* provides the plugin options defined in the configuration file.
296		* opt_count - The number of elements in the opts array.
297		* reload - If set to false, this is the first time the function has
298		* been called. If true, the broker has received a signal
299		* asking to reload its configuration.
300		*
301		* Return value:
302		* Return 0 on success
303		* Return >0 on failure.
304		*/
305		mosq_plugin_EXPORT int mosquitto_auth_security_init(void user_data, struct mosquitto_opt opts, int opt_count, bool reload);
306
307
308		/*
309		* Function: mosquitto_auth_security_cleanup
310		*
311		* This function is called in two scenarios:
312		*
313		* 1. When the broker is shutting down.
314		* 2. If the broker is requested to reload its configuration whilst running. In
315		* this case, this function will be called, followed by
316		* <mosquitto_auth_security_init>. In this situation, the reload parameter
317		* will be true.
318		*
319		* Parameters:
320		*
321		* user_data - The pointer provided in <mosquitto_auth_plugin_init>.
322		* opts - Pointer to an array of struct mosquitto_opt, which
323		* provides the plugin options defined in the configuration file.
324		* opt_count - The number of elements in the opts array.
325		* reload - If set to false, this is the first time the function has
326		* been called. If true, the broker has received a signal
327		* asking to reload its configuration.
328		*
329		* Return value:
330		* Return 0 on success
331		* Return >0 on failure.
332		*/
333		mosq_plugin_EXPORT int mosquitto_auth_security_cleanup(void user_data, struct mosquitto_opt opts, int opt_count, bool reload);
334
335
336		/*
337		* Function: mosquitto_auth_acl_check
338		*
339		* Called by the broker when topic access must be checked. access will be one
340		* of:
341		* MOSQ_ACL_SUBSCRIBE when a client is asking to subscribe to a topic string.
342		* This differs from MOSQ_ACL_READ in that it allows you to
343		* deny access to topic strings rather than by pattern. For
344		* example, you may use MOSQ_ACL_SUBSCRIBE to deny
345		* subscriptions to '#', but allow all topics in
346		* MOSQ_ACL_READ. This allows clients to subscribe to any
347		* topic they want, but not discover what topics are in use
348		* on the server.
349		* MOSQ_ACL_READ when a message is about to be sent to a client (i.e. whether
350		* it can read that topic or not).
351		* MOSQ_ACL_WRITE when a message has been received from a client (i.e. whether
352		* it can write to that topic or not).
353		*
354		* Return:
355		* MOSQ_ERR_SUCCESS if access was granted.
356		* MOSQ_ERR_ACL_DENIED if access was not granted.
357		* MOSQ_ERR_UNKNOWN for an application specific error.
358		* MOSQ_ERR_PLUGIN_DEFER if your plugin does not wish to handle this check.
359		*/
360		mosq_plugin_EXPORT int mosquitto_auth_acl_check(void user_data, int access, struct mosquitto client, const struct mosquitto_acl_msg *msg);
361
362
363		/*
364		* Function: mosquitto_auth_unpwd_check
365		*
366		* This function is OPTIONAL. Only include this function in your plugin if you
367		* are making basic username/password checks.
368		*
369		* Called by the broker when a username/password must be checked.
370		*
371		* Return:
372		* MOSQ_ERR_SUCCESS if the user is authenticated.
373		* MOSQ_ERR_AUTH if authentication failed.
374		* MOSQ_ERR_UNKNOWN for an application specific error.
375		* MOSQ_ERR_PLUGIN_DEFER if your plugin does not wish to handle this check.
376		*/
377		mosq_plugin_EXPORT int mosquitto_auth_unpwd_check(void user_data, struct mosquitto client, const char username, const char password);
378
379
380		/*
381		* Function: mosquitto_psk_key_get
382		*
383		* This function is OPTIONAL. Only include this function in your plugin if you
384		* are making TLS-PSK checks.
385		*
386		* Called by the broker when a client connects to a listener using TLS/PSK.
387		* This is used to retrieve the pre-shared-key associated with a client
388		* identity.
389		*
390		* Examine hint and identity to determine the required PSK (which must be a
391		* hexadecimal string with no leading "0x") and copy this string into key.
392		*
393		* Parameters:
394		* user_data - the pointer provided in <mosquitto_auth_plugin_init>.
395		* hint - the psk_hint for the listener the client is connecting to.
396		* identity - the identity string provided by the client
397		* key - a string where the hex PSK should be copied
398		* max_key_len - the size of key
399		*
400		* Return value:
401		* Return 0 on success.
402		* Return >0 on failure.
403		* Return MOSQ_ERR_PLUGIN_DEFER if your plugin does not wish to handle this check.
404		*/
405		mosq_plugin_EXPORT int mosquitto_auth_psk_key_get(void user_data, struct mosquitto client, const char hint, const char identity, char *key, int max_key_len);
406
407		/*
408		* Function: mosquitto_auth_start
409		*
410		* This function is OPTIONAL. Only include this function in your plugin if you
411		* are making extended authentication checks.
412		*
413		* Parameters:
414		* user_data - the pointer provided in <mosquitto_auth_plugin_init>.
415		* method - the authentication method
416		* reauth - this is set to false if this is the first authentication attempt
417		* on a connection, set to true if the client is attempting to
418		* reauthenticate.
419		* data_in - pointer to authentication data, or NULL
420		* data_in_len - length of data_in, in bytes
421		* data_out - if your plugin wishes to send authentication data back to the
422		* client, allocate some memory using malloc or friends and set
423		* data_out. The broker will free the memory after use.
424		* data_out_len - Set the length of data_out in bytes.
425		*
426		* Return value:
427		* Return MOSQ_ERR_SUCCESS if authentication was successful.
428		* Return MOSQ_ERR_AUTH_CONTINUE if the authentication is a multi step process and can continue.
429		* Return MOSQ_ERR_AUTH if authentication was valid but did not succeed.
430		* Return any other relevant positive integer MOSQ_ERR_* to produce an error.
431		*/
432		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);
433
434		mosq_plugin_EXPORT int mosquitto_auth_continue(void user_data, struct mosquitto client, const char method, const void data_in, uint16_t data_in_len, void *data_out, uint16_t data_out_len);
435
436
437		#ifdef __cplusplus
438		}
439		#endif
440
441		#endif