| 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. |