Debian Codegraph @

manuals/en/developers/authplugin.tex

raw
1 \section{Bacula Auth Plugin Documentation}
2
3 \subsection{Overview}
4
5 Large companies are using central systems to handle authentication and
6 authorization data. It is very often based on LDAP databases. With one click,
7 the access to all software in the company can be granted or revoked. Today,
8 once a user can access the \texttt{bconsole.conf} file, Bacula doesn't require any
9 other form of authentication, basically, any user that have access to
10 \texttt{bconsole.conf} can interact with Bacula. It is mandatory to change the Console
11 resource and reload the Director to disable a user. The idea would be to let
12 the administrator the possibility to authenticate users with a central
13 database. For that, this document propose to design an
14 Authorization/Authentication mechanism based on a Director plugin. Once the
15 Console is properly connected, the plugin would be able to authenticate a given
16 user (password/user), and in a second time, would be also able to manage ACLs.
17
18 \subsection{Dictionary}
19
20 \begin{itemize}
21 \item [Authentication] is the act of proving an assertion, such as the identity
22 of a computer system user. In contrast with identification, the act of
23 indicating a person or thing's identity, authentication is the process of
24 verifying that identity. It might involve validating with personal password.
25 \item [Authorization] is the function of specifying access rights/privileges to
26 resources, which is related to information security and computer security in
27 general and to access control in particular. More formally, "to authorize"
28 is to define an access policy.
29 \item [Multi-factor authentication] (or MFA) is an authentication method in
30 which a computer user is granted access only after successfully presenting
31 two or more pieces of evidence (or factors) to an authentication mechanism:
32 knowledge (something the user and only the user knows), possession (something
33 the user and only the user has), and inherence (something the user and only
34 the user is).
35 \item [Two-Factor Authentication] (or 2FA) is a subset of MFA described above
36 with only two different factors, i.e. something they know, something they
37 have, or something they are.
38 \end{itemize}
39
40 \subsection{Bacula DIR Plugin API}
41
42 To write a Bacula plugin, you create a dynamic shared object program (or dll on
43 Win32) with a particular name and two exported entry points, place it in the
44 Plugins Directory, which is defined in the \texttt{bacula-dir.conf} file in the
45 \textbf{Director} resource, and when the Director starts, it will load all the
46 plugins that end with \texttt{-dir.so} (or \texttt{-dir.dll} on Win32) found
47 in that directory.
48
49 \subsubsection{Loading Plugins}
50
51 Once the Director loads the plugins, it asks the dynamic loader for the two
52 entry points (\texttt{loadPlugin} and \texttt{unloadPlugin}) then calls the
53 \texttt{loadPlugin} entry point (see below). Bacula passes information to the
54 plugin through this call and it gets back information that it needs to use the
55 plugin. Later, Bacula will call particular functions that are defined by the
56 loadPlugin interface. When Bacula is finished with the plugin (when Bacula is
57 going to exit), it will call the unloadPlugin entry point.
58
59 \smallskip{}
60
61 The two entry points are:
62
63 \begin{verbatim}
64 bRC loadPlugin(bDirInfo *lbinfo, bDirFuncs *lbfuncs, pDirInfo **pinfo, pDirFuncs **pfuncs)
65 \end{verbatim}
66
67 and
68
69 \begin{verbatim}
70 bRC unloadPlugin()
71 \end{verbatim}
72
73 both these external entry points to the shared object are defined as C entry
74 points to avoid name mangling complications with C++. However, the shared
75 object can actually be written in any language (preferably C or C++) providing
76 that it follows C language calling conventions.
77
78 The definitions for \texttt{bRC} and the arguments are \texttt{src/dird/dir\_plugins.h}
79 and so this header file needs to be included in your plugin. It along with
80 \texttt{src/lib/plugins.h} define basically the whole plugin interface. Within
81 this header file, it includes the following files:
82
83 \begin{verbatim}
84 #include <sys/types.h>
85 #include "config.h"
86 #include "bc_types.h"
87 #include "lib/plugins.h"
88 \end{verbatim}
89
90 \subsubsection*{loadPlugin}
91
92 As previously mentioned, the \texttt{loadPlugin} entry point in the plugin is
93 called immediately after Bacula loads the plugin when the Director itself is
94 first starting. This entry point is only called once during the execution of
95 the Director. In calling the plugin, the first two arguments are information
96 from Bacula that is passed to the plugin, and the last two arguments are
97 information about the plugin that the plugin must return to Bacula. The call
98 is:
99
100 \begin{verbatim}
101 bRC loadPlugin(bDirInfo *lbinfo, bDirFuncs *lbfuncs, pDirInfo **pinfo, pDirFuncs **pfuncs)
102 \end{verbatim}
103
104 and the arguments are:
105
106 \begin{itemize}
107 \item [lbinfo] This is information about Bacula in general. Currently, the only
108 value defined in the \texttt{bInfo} structure is the version, which is the
109 Bacula plugin interface version, currently defined as 1. The size is set to
110 the byte size of the structure. The exact definition of the \texttt{bInfo} structure
111 as of this writing is:
112
113 \begin{verbatim}
114 typedef struct s_dirbaculaInfo {
115 uint32_t size;
116 uint32_t version;
117 } bDirInfo;
118 \end{verbatim}
119
120 \item [lbfuncs] The \texttt{bFuncs} structure defines the callback entry points
121 within Bacula that the plugin can use register events, get Bacula values, set
122 Bacula values, and send messages to the Job output or debug output. The
123 exact definition as of this writing is:
124
125 \begin{verbatim}
126 typedef struct s_dirbaculaFuncs {
127 uint32_t size;
128 uint32_t version;
129 bRC (*registerBaculaEvents)(bpContext *ctx, ...);
130 bRC (*getBaculaValue)(bpContext *ctx, brDirVariable var, void *value);
131 bRC (*setBaculaValue)(bpContext *ctx, bwDirVariable var, void *value);
132 bRC (*JobMessage)(bpContext *ctx, const char *file, int line,
133 int type, utime_t mtime, const char *fmt, ...);
134 bRC (*DebugMessage)(bpContext *ctx, const char *file, int line,
135 int level, const char *fmt, ...);
136 } bDirFuncs;
137 \end{verbatim}
138
139 We will discuss these entry points and how to use them a bit later when
140 describing the plugin code.
141
142 \item [pInfo] When the \texttt{loadPlugin} entry point is called, the plugin
143 must initialize an information structure about the plugin and return a
144 pointer to this structure to Bacula. The exact definition as of this writing
145 is:
146
147 \begin{verbatim}
148 typedef struct s_dirpluginInfo {
149 uint32_t size;
150 uint32_t version;
151 const char *plugin_magic;
152 const char *plugin_license;
153 const char *plugin_author;
154 const char *plugin_date;
155 const char *plugin_version;
156 const char *plugin_description;
157 } pDirInfo;
158 \end{verbatim}
159
160 Where:
161 \begin{itemize}
162 \item [version] is the current Bacula defined plugin interface version, currently set to 1. If the interface
163 version differs from the current version of Bacula, the plugin will not be run (not yet implemented).
164
165
166 \item [plugin\_magic] is a pointer to the text string \texttt{DirPluginData} defined in \texttt{DIR\_PLUGIN\_MAGIC},
167 a sort of sanity check. If this value is not specified, the plugin will not be run (not yet implemented).
168 \item [plugin\_license] is a pointer to a text string that describes the plugin license. Bacula will only accept
169 compatible licenses. The accepted licenses as of this writing are: "Bacula AGPLv3", "AGPLv3",
170 "Bacula Systems(R) SA" and defined in \texttt{BPLUGIN\_LICENSE} compile time definition.
171 \item [plugin\_author] is a pointer to the text name of the author of the plugin. This string can be anything
172 but is generally the author’s name.
173 \item [plugin\_date] is the pointer to a text string containing the date of the plugin. This string can be
174 anything but is generally some human readable form of the date.
175
176 \item [plugin\_version] is a pointer to a text string containing the version of the plugin. The contents are
177 determined by the plugin writer.
178 \item [plugin\_description] is a pointer to a text string describing what the plugin does. The contents are
179 determined by the plugin writer.
180 \end{itemize}
181
182 The pInfo structure must be defined in static memory because Bacula does not copy it and may refer to the
183 values at any time while the plugin is loaded. All values must be supplied or the plugin will not
184 run (not yet implemented). All text strings must be either ASCII or UTF-8 strings that are terminated
185 with a zero (\texttt{nul}) byte.
186
187
188 \item [pFuncs] When the \texttt{loadPlugin} entry point is called, the plugin must initialize an entry point structure
189 about the plugin and return a pointer to this structure to Bacula. This structure contains pointer to each
190 of the entry points that the plugin must (or will) provide for Bacula. When Bacula is actually running the
191 plugin, it will call the defined entry points at particular times.
192 The \texttt{pFuncs} structure must be defined in static memory because Bacula does not copy it and may refer to the
193 values at any time while the plugin is loaded.
194
195 \smallskip{}
196
197 The exact definition as of this writing is:
198
199 \begin{verbatim}
200 typedef struct s_dirpluginFuncs
201 {
202 uint32_t size;
203 uint32_t version;
204 bRC (*newPlugin)(bpContext *ctx);
205 bRC (*freePlugin)(bpContext *ctx);
206 bRC (*getPluginValue)(bpContext *ctx, pDirVariable var, void *value);
207 bRC (*setPluginValue)(bpContext *ctx, pDirVariable var, void *value);
208 bRC (*handlePluginEvent)(bpContext *ctx, bDirEvent *event, void *value);
209 bRC (*getPluginAuthenticationData)(bpContext *ctx, const char *param, void **data);
210 bRC (*getPluginAuthorizationData)(bpContext *ctx, const char *param, void **data);
211 } pDirFuncs;
212 \end{verbatim}
213
214 The details of the entry points will be presented in separate sections below. Where:
215 \begin{itemize}
216 \item [size] is the byte size of the structure.
217 \item [version] is the plugin interface version currently set to 1 (defined in \texttt{DIR\_PLUGIN\_INTERFACE\_VERSION}).
218 \end{itemize}
219 \end{itemize}
220
221 \subsubsection**{unloadPlugin}
222
223 As previously mentioned, the \texttt{unloadPlugin} entry point in the plugin is called just before a Director finish
224 execution. This entry point is responsible for releasing any resources allocated by plugin during \texttt{loadPlugin}.
225
226 \subsubsection{Plugin Entry Points}
227
228 This section will describe each of the entry points (subroutines) within the plugin that the plugin must
229 provide for Bacula, when they are called and their arguments. As noted above, pointers to these subroutines
230 are passed back to Bacula in the \texttt{pFuncs} structure when Bacula calls the \texttt{loadPlugin()} externally defined
231 entry point.
232
233 \subsubsection*{newPlugin}
234
235 This is the entry point that Bacula will call when a new \texttt{instance} of
236 the plugin is created. This typically happens at the beginning of any Job or Console
237 connection. If 10 Jobs are running simultaneously, there will be at least
238 10 instances of the plugin.
239
240 \smallskip{}
241
242 The \texttt{bpContext} structure will be passed to the plugin, and during this
243 call, if the plugin needs to have its private working storage that is
244 associated with the particular instance of the plugin, it should create it from
245 the heap (malloc the memory) and store a pointer to its private working storage
246 in the pContext variable.
247
248 \smallskip{}
249
250 \textbf{Note:} since Bacula is a multi-threaded program, you must not keep any
251 variable data in your plugin unless it is truly meant to apply globally to the
252 whole plugin. In addition, you must be aware that except the first and last
253 call to the plugin (\texttt{loadPlugin} and \texttt{unloadPlugin}) all the other calls will
254 be made by threads that correspond to a Bacula job. The \texttt{bpContext} that will
255 be passed for each thread will remain the same throughout the Job thus you can
256 keep your private Job specific data in it (\texttt{bContext}).
257
258 \begin{verbatim}
259 typedef struct s_bpContext {
260 void *pContext; /* Plugin private context */
261 void *bContext; /* Bacula private context */
262 } bpContext;
263 \end{verbatim}
264
265 This context pointer will be passed as the first argument to all the entry
266 points that Bacula calls within the plugin. Needless to say, the plugin should
267 not change the bContext variable, which is Bacula’s private context pointer for
268 this instance (Job) of this plugin.
269
270 \subsubsection*{freePlugin}
271
272 This entry point is called when the this instance of the plugin is no longer
273 needed (the Job/Console is ending), and the plugin should release all memory it may
274 have allocated for this particular instance i.e. the \texttt{pContext}. This is
275 not the final termination of the plugin signaled by a call to
276 \texttt{unloadPlugin}. Any other instances (Job) will continue to run, and the entry
277 point newPlugin may be called again if other jobs start.
278
279 \subsubsection*{getPluginValue}
280
281 Bacula will call this entry point to get a value from the plugin. This entry
282 point is currently not called.
283
284 \subsubsection*{setPluginValue}
285
286 Bacula will call this entry point to set a value in the plugin. This entry
287 point is currently not called.
288
289 \subsubsection*{handlePluginEvent}
290
291 This entry point is called when Bacula encounters certain events. This is, in
292 fact, the main way that most plugins get control when a Job/Console runs and how they
293 know what is happening in the job. It can be likened to the RunScript feature
294 that calls external programs and scripts. When the plugin is called, Bacula
295 passes it the pointer to an event structure (\texttt{bDirEvent}), which currently has
296 one item, the \texttt{eventType}:
297
298 \begin{verbatim}
299 typedef struct s_bDirEvent {
300 uint32_t eventType;
301 } bDirEvent;
302 \end{verbatim}
303
304 which defines what event has been triggered, and for each event, Bacula will
305 pass a pointer to a value associated with that event. If no value is associated
306 with a particular event, Bacula will pass a NULL pointer, so the plugin must be
307 careful to always check value pointer prior to dereferencing it.
308
309 \smallskip{}
310
311 The current list of events are:
312
313 \begin{verbatim}
314 typedef enum {
315 bDirEventJobStart = 1,
316 bDirEventJobEnd = 2,
317 bDirEventJobInit = 3,
318 bDirEventJobRun = 4,
319 bDirEventVolumePurged = 5,
320 bDirEventNewVolume = 6,
321 bDirEventNeedVolume = 7,
322 bDirEventVolumeFull = 8,
323 bDirEventRecyle = 9,
324 bDirEventGetScratch = 10,
325 bDirEventAuthenticationQuestion = 1000, // *value is a bDirAuthValue struct allocated by Dir
326 // to get return value from
327 bDirEventAuthenticationResponse = 1001, // *value is a char* to user response
328 bDirEventAuthenticate = 1002, // return bRC_OK when authenticate is successful
329 } bDirEventsType;
330 \end{verbatim}
331
332 Most of the above are self-explanatory.
333
334 \begin{itemize}
335 \item [bEventJobStart] is called whenever a Job starts.
336 \item [bEventJobEnd] is called whenever a Job ends. No value is passed.
337 \item [bDirEventJobInit] is called when ... .
338 \item [bDirEventJobRun] is called when ... .
339 \item [bDirEventVolumePurged] is called when ... .
340 \item [bDirEventAuthenticationQuestion] is called for authentication plugin (see description below - BPAM)
341 whenever Director wants to get the next question in user (bconsole) authentication session.
342 A \textbf{value} is a pointer to \texttt{bDirAuthValue}. Plugin should return a single \texttt{bDirAuthData} structure
343 (described below) in this value.
344 \item [bDirEventAuthenticationResponse] is called for authentication plugin to forward user response for
345 the last handled authentication question.
346 A value is a pointer to \texttt{bDirAuthValue}. Plugin will get a response in \texttt{value->response}
347 (as a \texttt{char*}, a \texttt{nul} terminated string) and \texttt{value->seqdata} copied from authentication question.
348 Plugin should return \texttt{bRC\_OK} if Director can proceed to the next step.
349 \item [bDirEventAuthenticate] is called for authentication plugin whenever Director asks a plugin to
350 final authenticate result where \texttt{bRC\_OK} when successful and \texttt{bRC\_Error} when error.
351 \end{itemize}
352
353 During each of the above calls, the plugin receives either no specific value or
354 only one value, which in some cases may not be sufficient. However, knowing the
355 context of the event, the plugin can call back to the Bacula entry points it
356 was passed during the loadPlugin call and get to a number of Bacula
357 variables. (at the current time few Bacula variables are implemented, but it
358 easily extended at a future time and as needs require).
359
360 \subsection{Bacula Pluggable Authentication Modules API Framework \textbf{BPAM}]}
361
362 Starting from Bacula Enterprise 12.6 new user authentication API framework is
363 introduced which allows to configure a different authentication mechanisms
364 (user credentials verification) using a dedicated Director plugins and Console
365 resource configuration. This is called \textbf{BPAM} - \textbf{Bacula Pluggable
366 Authentication Modules}.
367
368 \smallskip{}
369
370 The new framework support standard \textbf{user/password} and \textbf{MFA}
371 authentication schemes which are fully driven by external plugins. On the
372 client side \texttt{bconsole} when noticed will perform user interaction to collect
373 required credentials. Bacula will still support all previous authentication
374 schemas including \texttt{CRAM-MD5} and \texttt{TLS}. You can even configure \textbf{TLS
375 Authentication} together with new BPAM authentication raising required security
376 level. BPAM authentication is available for named Console resources only.
377
378 The BPAM framework extend a standard Director Plugin API architecture with the following plugin
379 entry points:
380
381 \begin{verbatim}
382 bRC getPluginAuthenticationData(bpContext *ctx, const char *param, void **data);
383 bRC getPluginAuthorizationData(bpContext *ctx, const char *param, void **data);
384 \end{verbatim}
385
386 and plugin events mentioned above:
387
388 \begin{verbatim}
389 ...
390 bDirEventAuthenticationQuestion = 1000, // *value is a bDirAuthValue struct allocated by Dir
391 // to get return value from
392 bDirEventAuthenticationResponse = 1001, // *value is a char* to user response
393 bDirEventAuthenticate = 1002, // return bRC_OK when authenticate is successful
394 ...
395 \end{verbatim}
396
397 \subsubsection{BPAM Plugin registration}
398
399 BPAM assumes that any authentication or authorization workflows manages a very
400 sensitive information (user credentials or permissions) which must be handled
401 with extreme care, i.e. it should not be visible outside the selected
402 plugin. This makes a clear break in general Bacula's plugin workflow design
403 where every event is forwarded to every plugin until one of them raise event
404 handling is done. This kind of event workflow handling can leads to unexpected
405 user credentials data breach which is unacceptable.
406
407 Before a plugin will get authentication or authorization requests it has to
408 register its services with \texttt{getPluginAuthenticationData()} or
409 \texttt{getPluginAuthorizationData()} plugin entry points. Director will call this
410 plugin's functions (if defined in \texttt{pDirFuncs} structure) on every new bconsole
411 connection for selected plugin only when appropriate \texttt{Console} resource is
412 configured (see below for more info).
413
414 \begin{verbatim}
415 Console {
416 Name = "bpamauthconsole"
417 Password = "xxx"
418
419 # New directives
420 Authentication Plugin = "<plugin>:<optional parameters>"
421 Authorization Plugin = "<plugin>:<optional parameters>" # not implemented yet!
422 ...
423 }
424 \end{verbatim}
425
426 \subsubsection*{bacula-dir.conf - Console resource configuration}
427
428 The entry point \texttt{getPluginAuthenticationData()} is called when Director
429 needs to forward authentication to selected \texttt{<plugin>} which is defined with
430 \texttt{Authentication Plugin = ...} parameter. The name \texttt{<plugin>} has to match the
431 filename of the Director plugin (without a \texttt{-dir.*} suffix). No other plugin
432 will be bothered. The function takes the following parameters:
433
434 \begin{itemize}
435 \item [param] is a \texttt{nul} terminated string defined on the right side of the parameter, including plugin
436 name and optional plugin parameters.
437 \item [data] is a pointer to \texttt{bDirAuthenticationRegister} struct pointer (\texttt{bDirAuthenticationRegister**})
438 which should be filled as a return value for plugin data registration.
439 \end{itemize}
440
441 The \texttt{bDirAuthenticationRegister} structure is defined as:
442
443 \begin{verbatim}
444 typedef struct s_bDirAuthenticationRegister {
445 const char * name;
446 const char * welcome;
447 const uint32_t num;
448 const bDirAuthenticationData *data;
449 const int32_t nsTTL;
450 } bDirAuthenticationRegister;
451 \end{verbatim}
452
453 which together with \texttt{bDirAuthenticationData} structure will define a full authentication workflow managed
454 by this plugin. Where parameters are:
455
456 \begin{itemize}
457
458 \item [name] is a name of the authentication plugin and should match the \texttt{<plugin>} string in Console
459 resource configuration.
460 \item [welcome] is an optional authentication welcome string which will be displayed before first
461 authentication question.
462 \item [num] is a number of elements in authentication operation data table pointed by \texttt{data} below.
463 \item [data] the pointer to the authentication operation data (\texttt{bDirAuthenticationData}) table, the
464 first element, with a number of elements defined in \texttt{num} above.
465 \item [nsTTL] currently unimplemented, for future usage.
466 \end{itemize}
467
468 The structure \texttt{bDirAuthenticationData} is defines as:
469
470 \begin{verbatim}
471 typedef struct s_bDirAuthenticationData {
472 const bDirAuthenticationOperation operation;
473 const char * question;
474 const uint32_t seqdata;
475 } bDirAuthenticationData;
476 \end{verbatim}
477
478 where:
479
480 \begin{itemize}
481 \item [operation] a single authentication step (operation) which should be performed by Director + bconsole
482 application. The list of possible operations include: display user the message, get login from user, get
483 password from user, etc.
484 \item [question] the \texttt{nul} terminated string to display to the user during credentials collection.
485 \item [seqdata] 32 bit integer for full plugin use; this value will be added to
486 the user response send to the plugin.
487 \end{itemize}
488
489 Both \texttt{bDirAuthenticationRegister} and \texttt{bDirAuthenticationData}
490 structures could be a statically compiled data or assembled in
491 runtime. Director will read data from it and never change. BPAM defines the
492 following authentication operations:
493
494 \begin{verbatim}
495 typedef enum {
496 bDirAuthenticationOperationPlugin,
497 bDirAuthenticationOperationPluginAll,
498 bDirAuthenticationOperationMessage,
499 bDirAuthenticationOperationPlain,
500 bDirAuthenticationOperationLogin = bDirAuthenticationOperationPlain,
501 bDirAuthenticationOperationHidden,
502 bDirAuthenticationOperationPassword = bDirAuthenticationOperationHidden,
503 bDirAuthenticationOperationAuthenticate,
504 } bDirAuthenticationOperation;
505 \end{verbatim}
506
507 \begin{itemize}
508 \item [bDirAuthenticationOperationPlugin] Director will get the current operation from the plugin using
509 \texttt{bDirEventAuthenticationQuestion} plugin event, then it should execute the operation returned.
510 \item [bDirAuthenticationOperationPluginAll] Director will get all authentication operations from the plugin with
511 \texttt{bDirEventAuthenticationQuestion} plugin events loop.
512 \item [bDirAuthenticationOperationMessage] Director will ask bconsole to display a message pointed by
513 \texttt{bDirAuthenticationData.question} and will proceed to the next operation in the list.
514 \item [bDirAuthenticationOperationPlain] (alias \texttt{bDirAuthenticationOperationLogin}) Director will ask bconsole
515 to display a message pointed by \texttt{bDirAuthenticationData.question}, then get plain input visible to the user
516 and proceed to the next operation in the list.
517 \item [bDirAuthenticationOperationHidden] (alias \texttt{bDirAuthenticationOperationPassword}) Director will ask bconsole
518 to display a message pointed by \texttt{bDirAuthenticationData.question}, then get hidden (*) input invisible to the
519 user, i.e. a password, and proceed to the next operation in the list.
520 \item [bDirAuthenticationOperationAuthenticate] tells Director to finish all user interaction and asks plugin for
521 authentication using \texttt{bDirEventAuthenticate} plugin event.
522 \end{itemize}
523
524 Every authentication operation of \texttt{bDirAuthenticationOperationPlain} and
525 \texttt{bDirAuthenticationOperationHidden} will return with an user response
526 data which will be forwarded directly to plugin using
527 \texttt{bDirEventAuthenticationResponse} plugin event. No other operations will
528 do that. During this event a plugin is responsible to save user response as it
529 won't be saved by Director and lost forever. These collected responses should
530 be used for final user authenticate. The response is passed to plugin with
531 \texttt{bDirAuthValue.response} variable and filled with \texttt{seqdata} value from current
532 question operation.
533
534 \smallskip{}
535
536 As soon as the number of questions (\textbf{authenticate operations}) defined during registration (the
537 \texttt{bDirAuthenticationRegister.num} value) comes to the end or one of the operation executed is
538 \texttt{bDirAuthenticationOperationAuthenticate} then Director will stop asking a user more questions
539 and will generate the \texttt{bDirEventAuthenticate} plugin event. During this event handling a plugin
540 is responsible to verify all responses and perform user authentication.
541
542 \smallskip{}
543
544 There is a special operation in BPAM:
545 \texttt{bDirAuthenticationOperationPluginAll} which tells Director to asks in
546 runtime the plugin for every single operation to execute. This allow to build a
547 dynamic authentication procedure with a variable number of questions and
548 challenges. In this case a plugin is responsible to explicitly finish a
549 workflow with \texttt{bDirAuthenticationOperationAuthenticate}.
550
551 \bimageH[0.9\linewidth]
552 {bpamflow2}{BPAM General Workflow}{fig:bpamworkflow}
553
554 You can find below some examples for above structures.
555
556 \begin{verbatim}
557 static bDirAuthenticationData testquestions0[] =
558 {
559 // operation; question; data;
560 {bDirAuthenticationOperationLogin, "Username:", 0},
561 {bDirAuthenticationOperationPassword, "Password:", 1},
562 };
563
564 static bDirAuthenticationRegister testregister0 =
565 {
566 .name = "PLUGIN_NAME",
567 .welcome = "This is a test authplugin API Plugin. Use root/root to login.",
568 .num = 2,
569 .data = testquestions0,
570 .nsTTL = 0,
571 };
572 \end{verbatim}
573
574 Above you can find a simplest user/password authentication scheme with plain (visible) user input
575 and hidden (invisible) password input.
576
577 \begin{verbatim}
578 static bDirAuthenticationData testquestions1[] =
579 {
580 // operation; question; data;
581 {bDirAuthenticationOperationLogin, "Username:", 0},
582 {bDirAuthenticationOperationPlugin, NULL, 1},
583 {bDirAuthenticationOperationPlain, "Response:", 2},
584 };
585
586 static bDirAuthenticationData testquestions1_msg =
587 {
588 // operation; question; data;
589 bDirAuthenticationOperationMessage, NULL, 0
590 };
591
592 static bDirAuthenticationRegister testregister1 =
593 {
594 .name = "PLUGIN_NAME",
595 .welcome = "This is a test authplugin API Plugin. Use bacula username to login.",
596 .num = 3,
597 .data = testquestions1,
598 .nsTTL = 0,
599 };
600 \end{verbatim}
601
602 Above you can find a simplest MFA (\textbf{challenge-response}) authentication
603 scheme with out of band authentication verification. In this example a plugin
604 will display a message prepared in runtime by plugin.