-
Notifications
You must be signed in to change notification settings - Fork 2.4k
/
mosquitto_plugin.h
418 lines (370 loc) · 15 KB
/
mosquitto_plugin.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
/*
Copyright (c) 2012-2020 Roger Light <[email protected]>
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
https://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_PLUGIN_H
#define MOSQUITTO_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>
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
*
* 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.
*/
/* =========================================================================
*
* 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.
*/
mosq_plugin_EXPORT int mosquitto_plugin_version(int supported_version_count, const int *supported_versions);
/*
* 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.
*
* 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.
*
* ========================================================================= */
/*
* 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