bacula-dir.conf - Console Resource Configuration

The entry point getPluginAuthenticationData() is called when Director needs to forward authentication to selected <plugin> which is defined with Authentication Plugin = ... parameter. The name <plugin> has to match the filename of the Director plugin (without a -dir.* suffix). No other plugin will be bothered. The function takes the following parameters:

param: is a nul terminated string defined on the right side of the parameter, including plugin name and optional plugin parameters.
data: is a pointer to bDirAuthenticationRegister struct pointer (bDirAuthenticationRegister**) which should be filled as a return value for plugin data registration.

The bDirAuthenticationRegister structure is defined as:

typedef struct s_bDirAuthenticationRegister {
  const char * name;
  const char * welcome;
  const uint32_t num;
  const bDirAuthenticationData *data;
  const int32_t nsTTL;
} bDirAuthenticationRegister;

which together with bDirAuthenticationData structure will define a full authentication workflow managed by this plugin. Where parameters are:

name: is a name of the authentication plugin and should match the <plugin> string in Console resource configuration.
welcome: is an optional authentication welcome string which will be displayed before first authentication question.
num: is a number of elements in authentication operation data table pointed by data below.
data: the pointer to the authentication operation data (bDirAuthenticationData) table, the first element, with a number of elements defined in num above.
nsTTL: currently unimplemented, for future usage.

The structure bDirAuthenticationData is defines as:

typedef struct s_bDirAuthenticationData {
  const bDirAuthenticationOperation operation;
  const char * question;
  const uint32_t seqdata;
} bDirAuthenticationData;

where:

operation: a single authentication step (operation) which should be performed by Director + bconsole application. The list of possible operations include: display user the message, get login from user, get password from user, etc.
question: the nul terminated string to display to the user during credentials collection.
seqdata: 32 bit integer for full plugin use; this value will be added to the user response send to the plugin.

Both bDirAuthenticationRegister and bDirAuthenticationData structures could be a statically compiled data or assembled in runtime. Director will read data from it and never change. BPAM defines the following authentication operations:

typedef enum {
  bDirAuthenticationOperationPlugin,
  bDirAuthenticationOperationPluginAll,
  bDirAuthenticationOperationMessage,
  bDirAuthenticationOperationPlain,
  bDirAuthenticationOperationLogin = bDirAuthenticationOperationPlain,
  bDirAuthenticationOperationHidden,
  bDirAuthenticationOperationPassword = bDirAuthenticationOperationHidden,
  bDirAuthenticationOperationAuthenticate,
} bDirAuthenticationOperation;

bDirAuthenticationOperationPlugin: Director will get the current operation from the plugin using bDirEventAuthenticationQuestion plugin event, then it should execute the operation returned.
bDirAuthenticationOperationPluginAll: Director will get all authentication operations from the plugin with bDirEventAuthenticationQuestion plugin events loop.
bDirAuthenticationOperationMessage: Director will ask bconsole to display a message pointed by bDirAuthenticationData.question and will proceed to the next operation in the list.
bDirAuthenticationOperationPlain: (alias bDirAuthenticationOperationLogin) Director will ask bconsole to display a message pointed by bDirAuthenticationData.question, then get plain input visible to the user and proceed to the next operation in the list.
bDirAuthenticationOperationHidden: (alias bDirAuthenticationOperationPassword) Director will ask bconsole to display a message pointed by bDirAuthenticationData.question, then get hidden (*) input invisible to the user, i.e. a password, and proceed to the next operation in the list.
bDirAuthenticationOperationAuthenticate: tells Director to finish all user interaction and asks plugin for authentication using bDirEventAuthenticate plugin event.

Every authentication operation of bDirAuthenticationOperationPlain and bDirAuthenticationOperationHidden will return with an user response data which will be forwarded directly to plugin using bDirEventAuthenticationResponse plugin event. No other operations will do that. During this event a plugin is responsible to save user response as it won’t be saved by Director and lost forever. These collected responses should be used for final user authenticate. The response is passed to plugin with bDirAuthValue.response variable and filled with seqdata value from current question operation.

As soon as the number of questions (authenticate operations) defined during registration (the bDirAuthenticationRegister.num value) comes to the end or one of the operation executed is bDirAuthenticationOperationAuthenticate then Director will stop asking a user more questions and will generate the bDirEventAuthenticate plugin event. During this event handling a plugin is responsible to verify all responses and perform user authentication.

There is a special operation in BPAM: bDirAuthenticationOperationPluginAll which tells Director to asks in runtime the plugin for every single operation to execute. This allow to build a dynamic authentication procedure with a variable number of questions and challenges. In this case a plugin is responsible to explicitly finish a workflow with bDirAuthenticationOperationAuthenticate.

You can find below some examples for above structures.

static bDirAuthenticationData testquestions0[] =
{
  // operation; question; data;
  {bDirAuthenticationOperationLogin, "Username:", 0},
  {bDirAuthenticationOperationPassword, "Password:", 1},
};

static bDirAuthenticationRegister testregister0 =
{
  .name = "PLUGIN_NAME",
  .welcome = "This is a test authplugin API Plugin. Use root/root to login.",
  .num = 2,
  .data = testquestions0,
  .nsTTL = 0,
};

Above you can find a simplest user/password authentication scheme with plain (visible) user input and hidden (invisible) password input.

static bDirAuthenticationData testquestions1[] =
{
  // operation; question; data;
  {bDirAuthenticationOperationLogin, "Username:", 0},
  {bDirAuthenticationOperationPlugin, NULL, 1},
  {bDirAuthenticationOperationPlain, "Response:", 2},
};

static bDirAuthenticationData testquestions1_msg =
{
  // operation; question; data;
  bDirAuthenticationOperationMessage, NULL, 0
};

static bDirAuthenticationRegister testregister1 =
{
  .name = "PLUGIN_NAME",
  .welcome = "This is a test authplugin API Plugin. Use bacula username to login.",
  .num = 3,
  .data = testquestions1,
  .nsTTL = 0,
};

Above you can find a simplest MFA (challenge-response) authentication scheme with out of band authentication verification. In this example a plugin will display a message prepared in runtime by plugin.

Possible Next Steps

Go back to Bacula FD Plugin API.

Go back to Developer Guide.