source4/lib/ldb/ldb_map/ldb_map.c

   1 /*
   2    ldb database mapping module
   3
   4    Copyright (C) Jelmer Vernooij 2005
   5    Copyright (C) Martin Kuehl <mkhl@samba.org> 2006
   6
   7      ** NOTE! The following LGPL license applies to the ldb
   8      ** library. This does NOT imply that all of Samba is released
   9      ** under the LGPL
  10
  11    This library is free software; you can redistribute it and/or
  12    modify it under the terms of the GNU Lesser General Public
  13    License as published by the Free Software Foundation; either
  14    version 3 of the License, or (at your option) any later version.
  15
  16    This library is distributed in the hope that it will be useful,
  17    but WITHOUT ANY WARRANTY; without even the implied warranty of
  18    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19    Lesser General Public License for more details.
  20
  21    You should have received a copy of the GNU Lesser General Public
  22    License along with this library; if not, write to the Free Software
  23    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24
  25 */
  26
  27 /*
  28  *  Name: ldb
  29  *
  30  *  Component: ldb ldb_map module
  31  *
  32  *  Description: Map portions of data into a different format on a
  33  *  remote partition.
  34  *
  35  *  Author: Jelmer Vernooij, Martin Kuehl
  36  */
  37
  38 #include "ldb_includes.h"
  39
  40 #include "ldb_map.h"
  41 #include "ldb_map_private.h"
  42
  43 #ifndef _PUBLIC_
  44 #define _PUBLIC_
  45 #endif
  46
  47 /* Description of the provided ldb requests:
  48  - special attribute 'isMapped'
  49
  50  - search:
  51      - if parse tree can be split
  52          - search remote records w/ remote attrs and parse tree
  53      - otherwise
  54          - enumerate all remote records
  55      - for each remote result
  56          - map remote result to local message
  57          - search local result
  58          - is present
  59              - merge local into remote result
  60              - run callback on merged result
  61          - otherwise
  62              - run callback on remote result
  63
  64  - add:
  65      - split message into local and remote part
  66      - if local message is not empty
  67          - add isMapped to local message
  68          - add local message
  69      - add remote message
  70
  71  - modify:
  72      - split message into local and remote part
  73      - if local message is not empty
  74          - add isMapped to local message
  75          - search for local record
  76          - if present
  77              - modify local record
  78          - otherwise
  79              - add local message
  80      - modify remote record
  81
  82  - delete:
  83      - search for local record
  84      - if present
  85          - delete local record
  86      - delete remote record
  87
  88  - rename:
  89      - search for local record
  90      - if present
  91          - rename local record
  92          - modify local isMapped
  93      - rename remote record
  94 */
  95
  96
  97
  98 /* Private data structures
  99  * ======================= */
 100
 101 /* Global private data */
 102 /* Extract mappings from private data. */
 103 const struct ldb_map_context *map_get_context(struct ldb_module *module)
 104 {
 105         const struct map_private *data = talloc_get_type(module->private_data, struct map_private);
 106         return data->context;
 107 }
 108
 109 /* Create a generic request context. */
 110 static struct map_context *map_init_context(struct ldb_handle *h, struct ldb_request *req)
 111 {
 112         struct map_context *ac;
 113
 114         ac = talloc_zero(h, struct map_context);
 115         if (ac == NULL) {
 116                 map_oom(h->module);
 117                 return NULL;
 118         }
 119
 120         ac->module = h->module;
 121         ac->orig_req = req;
 122
 123         return ac;
 124 }
 125
 126 /* Create a search request context. */
 127 struct map_search_context *map_init_search_context(struct map_context *ac, struct ldb_reply *ares)
 128 {
 129         struct map_search_context *sc;
 130
 131         sc = talloc_zero(ac, struct map_search_context);
 132         if (sc == NULL) {
 133                 map_oom(ac->module);
 134                 return NULL;
 135         }
 136
 137         sc->ac = ac;
 138         sc->local_res = NULL;
 139         sc->remote_res = ares;
 140
 141         return sc;
 142 }
 143
 144 /* Create a request context and handle. */
 145 struct ldb_handle *map_init_handle(struct ldb_request *req, struct ldb_module *module)
 146 {
 147         struct map_context *ac;
 148         struct ldb_handle *h;
 149
 150         h = talloc_zero(req, struct ldb_handle);
 151         if (h == NULL) {
 152                 map_oom(module);
 153                 return NULL;
 154         }
 155
 156         h->module = module;
 157
 158         ac = map_init_context(h, req);
 159         if (ac == NULL) {
 160                 talloc_free(h);
 161                 return NULL;
 162         }
 163
 164         h->private_data = (void *)ac;
 165
 166         h->state = LDB_ASYNC_INIT;
 167         h->status = LDB_SUCCESS;
 168
 169         return h;
 170 }
 171
 172
 173 /* Dealing with DNs for different partitions
 174  * ========================================= */
 175
 176 /* Check whether any data should be stored in the local partition. */
 177 bool map_check_local_db(struct ldb_module *module)
 178 {
 179         const struct ldb_map_context *data = map_get_context(module);
 180
 181         if (!data->remote_base_dn || !data->local_base_dn) {
 182                 return false;
 183         }
 184
 185         return true;
 186 }
 187
 188 /* Copy a DN with the base DN of the local partition. */
 189 static struct ldb_dn *ldb_dn_rebase_local(void *mem_ctx, const struct ldb_map_context *data, struct ldb_dn *dn)
 190 {
 191         struct ldb_dn *new_dn;
 192
 193         new_dn = ldb_dn_copy(mem_ctx, dn);
 194         if ( ! ldb_dn_validate(new_dn)) {
 195                 talloc_free(new_dn);
 196                 return NULL;
 197         }
 198
 199         /* may be we don't need to rebase at all */
 200         if ( ! data->remote_base_dn || ! data->local_base_dn) {
 201                 return new_dn;
 202         }
 203
 204         if ( ! ldb_dn_remove_base_components(new_dn, ldb_dn_get_comp_num(data->remote_base_dn))) {
 205                 talloc_free(new_dn);
 206                 return NULL;
 207         }
 208
 209         if ( ! ldb_dn_add_base(new_dn, data->local_base_dn)) {
 210                 talloc_free(new_dn);
 211                 return NULL;
 212         }
 213
 214         return new_dn;
 215 }
 216
 217 /* Copy a DN with the base DN of the remote partition. */
 218 static struct ldb_dn *ldb_dn_rebase_remote(void *mem_ctx, const struct ldb_map_context *data, struct ldb_dn *dn)
 219 {
 220         struct ldb_dn *new_dn;
 221
 222         new_dn = ldb_dn_copy(mem_ctx, dn);
 223         if ( ! ldb_dn_validate(new_dn)) {
 224                 talloc_free(new_dn);
 225                 return NULL;
 226         }
 227
 228         /* may be we don't need to rebase at all */
 229         if ( ! data->remote_base_dn || ! data->local_base_dn) {
 230                 return new_dn;
 231         }
 232
 233         if ( ! ldb_dn_remove_base_components(new_dn, ldb_dn_get_comp_num(data->local_base_dn))) {
 234                 talloc_free(new_dn);
 235                 return NULL;
 236         }
 237
 238         if ( ! ldb_dn_add_base(new_dn, data->remote_base_dn)) {
 239                 talloc_free(new_dn);
 240                 return NULL;
 241         }
 242
 243         return new_dn;
 244 }
 245
 246 /* Run a request and make sure it targets the remote partition. */
 247 /* TODO: free old DNs and messages? */
 248 int ldb_next_remote_request(struct ldb_module *module, struct ldb_request *request)
 249 {
 250         const struct ldb_map_context *data = map_get_context(module);
 251         struct ldb_message *msg;
 252
 253         switch (request->operation) {
 254         case LDB_SEARCH:
 255                 if (request->op.search.base) {
 256                         request->op.search.base = ldb_dn_rebase_remote(request, data, request->op.search.base);
 257                 } else {
 258                         request->op.search.base = data->remote_base_dn;
 259                         /* TODO: adjust scope? */
 260                 }
 261                 break;
 262
 263         case LDB_ADD:
 264                 msg = ldb_msg_copy_shallow(request, request->op.add.message);
 265                 msg->dn = ldb_dn_rebase_remote(msg, data, msg->dn);
 266                 request->op.add.message = msg;
 267                 break;
 268
 269         case LDB_MODIFY:
 270                 msg = ldb_msg_copy_shallow(request, request->op.mod.message);
 271                 msg->dn = ldb_dn_rebase_remote(msg, data, msg->dn);
 272                 request->op.mod.message = msg;
 273                 break;
 274
 275         case LDB_DELETE:
 276                 request->op.del.dn = ldb_dn_rebase_remote(request, data, request->op.del.dn);
 277                 break;
 278
 279         case LDB_RENAME:
 280                 request->op.rename.olddn = ldb_dn_rebase_remote(request, data, request->op.rename.olddn);
 281                 request->op.rename.newdn = ldb_dn_rebase_remote(request, data, request->op.rename.newdn);
 282                 break;
 283
 284         default:
 285                 ldb_debug(module->ldb, LDB_DEBUG_ERROR, "ldb_map: "
 286                           "Invalid remote request!\n");
 287                 return LDB_ERR_OPERATIONS_ERROR;
 288         }
 289
 290         return ldb_next_request(module, request);
 291 }
 292
 293
 294 /* Finding mappings for attributes and objectClasses
 295  * ================================================= */
 296
 297 /* Find an objectClass mapping by the local name. */
 298 static const struct ldb_map_objectclass *map_objectclass_find_local(const struct ldb_map_context *data, const char *name)
 299 {
 300         int i;
 301
 302         for (i = 0; data->objectclass_maps && data->objectclass_maps[i].local_name; i++) {
 303                 if (ldb_attr_cmp(data->objectclass_maps[i].local_name, name) == 0) {
 304                         return &data->objectclass_maps[i];
 305                 }
 306         }
 307
 308         return NULL;
 309 }
 310
 311 /* Find an objectClass mapping by the remote name. */
 312 static const struct ldb_map_objectclass *map_objectclass_find_remote(const struct ldb_map_context *data, const char *name)
 313 {
 314         int i;
 315
 316         for (i = 0; data->objectclass_maps && data->objectclass_maps[i].remote_name; i++) {
 317                 if (ldb_attr_cmp(data->objectclass_maps[i].remote_name, name) == 0) {
 318                         return &data->objectclass_maps[i];
 319                 }
 320         }
 321
 322         return NULL;
 323 }
 324
 325 /* Find an attribute mapping by the local name. */
 326 const struct ldb_map_attribute *map_attr_find_local(const struct ldb_map_context *data, const char *name)
 327 {
 328         int i;
 329
 330         for (i = 0; data->attribute_maps[i].local_name; i++) {
 331                 if (ldb_attr_cmp(data->attribute_maps[i].local_name, name) == 0) {
 332                         return &data->attribute_maps[i];
 333                 }
 334         }
 335         for (i = 0; data->attribute_maps[i].local_name; i++) {
 336                 if (ldb_attr_cmp(data->attribute_maps[i].local_name, "*") == 0) {
 337                         return &data->attribute_maps[i];
 338                 }
 339         }
 340
 341         return NULL;
 342 }
 343
 344 /* Find an attribute mapping by the remote name. */
 345 const struct ldb_map_attribute *map_attr_find_remote(const struct ldb_map_context *data, const char *name)
 346 {
 347         const struct ldb_map_attribute *map;
 348         const struct ldb_map_attribute *wildcard = NULL;
 349         int i, j;
 350
 351         for (i = 0; data->attribute_maps[i].local_name; i++) {
 352                 map = &data->attribute_maps[i];
 353                 if (ldb_attr_cmp(map->local_name, "*") == 0) {
 354                         wildcard = &data->attribute_maps[i];
 355                 }
 356
 357                 switch (map->type) {
 358                 case MAP_IGNORE:
 359                         break;
 360
 361                 case MAP_KEEP:
 362                         if (ldb_attr_cmp(map->local_name, name) == 0) {
 363                                 return map;
 364                         }
 365                         break;
 366
 367                 case MAP_RENAME:
 368                 case MAP_CONVERT:
 369                         if (ldb_attr_cmp(map->u.rename.remote_name, name) == 0) {
 370                                 return map;
 371                         }
 372                         break;
 373
 374                 case MAP_GENERATE:
 375                         for (j = 0; map->u.generate.remote_names && map->u.generate.remote_names[j]; j++) {
 376                                 if (ldb_attr_cmp(map->u.generate.remote_names[j], name) == 0) {
 377                                         return map;
 378                                 }
 379                         }
 380                         break;
 381                 }
 382         }
 383
 384         /* We didn't find it, so return the wildcard record if one was configured */
 385         return wildcard;
 386 }
 387
 388
 389 /* Mapping attributes
 390  * ================== */
 391
 392 /* Check whether an attribute will be mapped into the remote partition. */
 393 bool map_attr_check_remote(const struct ldb_map_context *data, const char *attr)
 394 {
 395         const struct ldb_map_attribute *map = map_attr_find_local(data, attr);
 396
 397         if (map == NULL) {
 398                 return false;
 399         }
 400         if (map->type == MAP_IGNORE) {
 401                 return false;
 402         }
 403
 404         return true;
 405 }
 406
 407 /* Map an attribute name into the remote partition. */
 408 const char *map_attr_map_local(void *mem_ctx, const struct ldb_map_attribute *map, const char *attr)
 409 {
 410         if (map == NULL) {
 411                 return talloc_strdup(mem_ctx, attr);
 412         }
 413
 414         switch (map->type) {
 415         case MAP_KEEP:
 416                 return talloc_strdup(mem_ctx, attr);
 417
 418         case MAP_RENAME:
 419         case MAP_CONVERT:
 420                 return talloc_strdup(mem_ctx, map->u.rename.remote_name);
 421
 422         default:
 423                 return NULL;
 424         }
 425 }
 426
 427 /* Map an attribute name back into the local partition. */
 428 const char *map_attr_map_remote(void *mem_ctx, const struct ldb_map_attribute *map, const char *attr)
 429 {
 430         if (map == NULL) {
 431                 return talloc_strdup(mem_ctx, attr);
 432         }
 433
 434         if (map->type == MAP_KEEP) {
 435                 return talloc_strdup(mem_ctx, attr);
 436         }
 437
 438         return talloc_strdup(mem_ctx, map->local_name);
 439 }
 440
 441
 442 /* Merge two lists of attributes into a single one. */
 443 int map_attrs_merge(struct ldb_module *module, void *mem_ctx,
 444                     const char ***attrs, const char * const *more_attrs)
 445 {
 446         int i, j, k;
 447
 448         for (i = 0; *attrs && (*attrs)[i]; i++) /* noop */ ;
 449         for (j = 0; more_attrs && more_attrs[j]; j++) /* noop */ ;
 450
 451         *attrs = talloc_realloc(mem_ctx, *attrs, const char *, i+j+1);
 452         if (*attrs == NULL) {
 453                 map_oom(module);
 454                 return -1;
 455         }
 456
 457         for (k = 0; k < j; k++) {
 458                 (*attrs)[i + k] = more_attrs[k];
 459         }
 460
 461         (*attrs)[i+k] = NULL;
 462
 463         return 0;
 464 }
 465
 466 /* Mapping ldb values
 467  * ================== */
 468
 469 /* Map an ldb value into the remote partition. */
 470 struct ldb_val ldb_val_map_local(struct ldb_module *module, void *mem_ctx,
 471                                  const struct ldb_map_attribute *map, const struct ldb_val *val)
 472 {
 473         if (map && (map->type == MAP_CONVERT) && (map->u.convert.convert_local)) {
 474                 return map->u.convert.convert_local(module, mem_ctx, val);
 475         }
 476
 477         return ldb_val_dup(mem_ctx, val);
 478 }
 479
 480 /* Map an ldb value back into the local partition. */
 481 struct ldb_val ldb_val_map_remote(struct ldb_module *module, void *mem_ctx,
 482                                   const struct ldb_map_attribute *map, const struct ldb_val *val)
 483 {
 484         if (map && (map->type == MAP_CONVERT) && (map->u.convert.convert_remote)) {
 485                 return map->u.convert.convert_remote(module, mem_ctx, val);
 486         }
 487
 488         return ldb_val_dup(mem_ctx, val);
 489 }
 490
 491
 492 /* Mapping DNs
 493  * =========== */
 494
 495 /* Check whether a DN is below the local baseDN. */
 496 bool ldb_dn_check_local(struct ldb_module *module, struct ldb_dn *dn)
 497 {
 498         const struct ldb_map_context *data = map_get_context(module);
 499
 500         if (!data->local_base_dn) {
 501                 return true;
 502         }
 503
 504         return ldb_dn_compare_base(data->local_base_dn, dn) == 0;
 505 }
 506
 507 /* Map a DN into the remote partition. */
 508 struct ldb_dn *ldb_dn_map_local(struct ldb_module *module, void *mem_ctx, struct ldb_dn *dn)
 509 {
 510         const struct ldb_map_context *data = map_get_context(module);
 511         struct ldb_dn *newdn;
 512         const struct ldb_map_attribute *map;
 513         enum ldb_map_attr_type map_type;
 514         const char *name;
 515         struct ldb_val value;
 516         int i, ret;
 517
 518         if (dn == NULL) {
 519                 return NULL;
 520         }
 521
 522         newdn = ldb_dn_copy(mem_ctx, dn);
 523         if (newdn == NULL) {
 524                 map_oom(module);
 525                 return NULL;
 526         }
 527
 528         /* For each RDN, map the component name and possibly the value */
 529         for (i = 0; i < ldb_dn_get_comp_num(newdn); i++) {
 530                 map = map_attr_find_local(data, ldb_dn_get_component_name(dn, i));
 531
 532                 /* Unknown attribute - leave this RDN as is and hope the best... */
 533                 if (map == NULL) {
 534                         map_type = MAP_KEEP;
 535                 } else {
 536                         map_type = map->type;
 537                 }
 538
 539                 switch (map_type) {
 540                 case MAP_IGNORE:
 541                 case MAP_GENERATE:
 542                         ldb_debug(module->ldb, LDB_DEBUG_ERROR, "ldb_map: "
 543                                   "MAP_IGNORE/MAP_GENERATE attribute '%s' "
 544                                   "used in DN!\n", ldb_dn_get_component_name(dn, i));
 545                         goto failed;
 546
 547                 case MAP_CONVERT:
 548                         if (map->u.convert.convert_local == NULL) {
 549                                 ldb_debug(module->ldb, LDB_DEBUG_ERROR, "ldb_map: "
 550                                           "'convert_local' not set for attribute '%s' "
 551                                           "used in DN!\n", ldb_dn_get_component_name(dn, i));
 552                                 goto failed;
 553                         }
 554                         /* fall through */
 555                 case MAP_KEEP:
 556                 case MAP_RENAME:
 557                         name = map_attr_map_local(newdn, map, ldb_dn_get_component_name(dn, i));
 558                         if (name == NULL) goto failed;
 559
 560                         value = ldb_val_map_local(module, newdn, map, ldb_dn_get_component_val(dn, i));
 561                         if (value.data == NULL) goto failed;
 562
 563                         ret = ldb_dn_set_component(newdn, i, name, value);
 564                         if (ret != LDB_SUCCESS) {
 565                                 goto failed;
 566                         }
 567
 568                         break;
 569                 }
 570         }
 571
 572         return newdn;
 573
 574 failed:
 575         talloc_free(newdn);
 576         return NULL;
 577 }
 578
 579 /* Map a DN into the local partition. */
 580 struct ldb_dn *ldb_dn_map_remote(struct ldb_module *module, void *mem_ctx, struct ldb_dn *dn)
 581 {
 582         const struct ldb_map_context *data = map_get_context(module);
 583         struct ldb_dn *newdn;
 584         const struct ldb_map_attribute *map;
 585         enum ldb_map_attr_type map_type;
 586         const char *name;
 587         struct ldb_val value;
 588         int i, ret;
 589
 590         if (dn == NULL) {
 591                 return NULL;
 592         }
 593
 594         newdn = ldb_dn_copy(mem_ctx, dn);
 595         if (newdn == NULL) {
 596                 map_oom(module);
 597                 return NULL;
 598         }
 599
 600         /* For each RDN, map the component name and possibly the value */
 601         for (i = 0; i < ldb_dn_get_comp_num(newdn); i++) {
 602                 map = map_attr_find_remote(data, ldb_dn_get_component_name(dn, i));
 603
 604                 /* Unknown attribute - leave this RDN as is and hope the best... */
 605                 if (map == NULL) {
 606                         map_type = MAP_KEEP;
 607                 } else {
 608                         map_type = map->type;
 609                 }
 610
 611                 switch (map_type) {
 612                 case MAP_IGNORE:
 613                 case MAP_GENERATE:
 614                         ldb_debug(module->ldb, LDB_DEBUG_ERROR, "ldb_map: "
 615                                   "MAP_IGNORE/MAP_GENERATE attribute '%s' "
 616                                   "used in DN!\n", ldb_dn_get_component_name(dn, i));
 617                         goto failed;
 618
 619                 case MAP_CONVERT:
 620                         if (map->u.convert.convert_remote == NULL) {
 621                                 ldb_debug(module->ldb, LDB_DEBUG_ERROR, "ldb_map: "
 622                                           "'convert_remote' not set for attribute '%s' "
 623                                           "used in DN!\n", ldb_dn_get_component_name(dn, i));
 624                                 goto failed;
 625                         }
 626                         /* fall through */
 627                 case MAP_KEEP:
 628                 case MAP_RENAME:
 629                         name = map_attr_map_remote(newdn, map, ldb_dn_get_component_name(dn, i));
 630                         if (name == NULL) goto failed;
 631
 632                         value = ldb_val_map_remote(module, newdn, map, ldb_dn_get_component_val(dn, i));
 633                         if (value.data == NULL) goto failed;
 634
 635                         ret = ldb_dn_set_component(newdn, i, name, value);
 636                         if (ret != LDB_SUCCESS) {
 637                                 goto failed;
 638                         }
 639
 640                         break;
 641                 }
 642         }
 643
 644         return newdn;
 645
 646 failed:
 647         talloc_free(newdn);
 648         return NULL;
 649 }
 650
 651 /* Map a DN and its base into the local partition. */
 652 /* TODO: This should not be required with GUIDs. */
 653 struct ldb_dn *ldb_dn_map_rebase_remote(struct ldb_module *module, void *mem_ctx, struct ldb_dn *dn)
 654 {
 655         const struct ldb_map_context *data = map_get_context(module);
 656         struct ldb_dn *dn1, *dn2;
 657
 658         dn1 = ldb_dn_rebase_local(mem_ctx, data, dn);
 659         dn2 = ldb_dn_map_remote(module, mem_ctx, dn1);
 660
 661         talloc_free(dn1);
 662         return dn2;
 663 }
 664
 665
 666 /* Converting DNs and objectClasses (as ldb values)
 667  * ================================================ */
 668
 669 /* Map a DN contained in an ldb value into the remote partition. */
 670 static struct ldb_val ldb_dn_convert_local(struct ldb_module *module, void *mem_ctx, const struct ldb_val *val)
 671 {
 672         struct ldb_dn *dn, *newdn;
 673         struct ldb_val newval;
 674
 675         dn = ldb_dn_new(mem_ctx, module->ldb, (char *)val->data);
 676         if (! ldb_dn_validate(dn)) {
 677                 newval.length = 0;
 678                 newval.data = NULL;
 679                 talloc_free(dn);
 680                 return newval;
 681         }
 682         newdn = ldb_dn_map_local(module, mem_ctx, dn);
 683         talloc_free(dn);
 684
 685         newval.length = 0;
 686         newval.data = (uint8_t *)ldb_dn_alloc_linearized(mem_ctx, newdn);
 687         if (newval.data) {
 688                 newval.length = strlen((char *)newval.data);
 689         }
 690         talloc_free(newdn);
 691
 692         return newval;
 693 }
 694
 695 /* Map a DN contained in an ldb value into the local partition. */
 696 static struct ldb_val ldb_dn_convert_remote(struct ldb_module *module, void *mem_ctx, const struct ldb_val *val)
 697 {
 698         struct ldb_dn *dn, *newdn;
 699         struct ldb_val newval;
 700
 701         dn = ldb_dn_new(mem_ctx, module->ldb, (char *)val->data);
 702         if (! ldb_dn_validate(dn)) {
 703                 newval.length = 0;
 704                 newval.data = NULL;
 705                 talloc_free(dn);
 706                 return newval;
 707         }
 708         newdn = ldb_dn_map_remote(module, mem_ctx, dn);
 709         talloc_free(dn);
 710
 711         newval.length = 0;
 712         newval.data = (uint8_t *)ldb_dn_alloc_linearized(mem_ctx, newdn);
 713         if (newval.data) {
 714                 newval.length = strlen((char *)newval.data);
 715         }
 716         talloc_free(newdn);
 717
 718         return newval;
 719 }
 720
 721 /* Map an objectClass into the remote partition. */
 722 static struct ldb_val map_objectclass_convert_local(struct ldb_module *module, void *mem_ctx, const struct ldb_val *val)
 723 {
 724         const struct ldb_map_context *data = map_get_context(module);
 725         const char *name = (char *)val->data;
 726         const struct ldb_map_objectclass *map = map_objectclass_find_local(data, name);
 727         struct ldb_val newval;
 728
 729         if (map) {
 730                 newval.data = (uint8_t*)talloc_strdup(mem_ctx, map->remote_name);
 731                 newval.length = strlen((char *)newval.data);
 732                 return newval;
 733         }
 734
 735         return ldb_val_dup(mem_ctx, val);
 736 }
 737
 738 /* Generate a remote message with a mapped objectClass. */
 739 static void map_objectclass_generate_remote(struct ldb_module *module, const char *local_attr, const struct ldb_message *old, struct ldb_message *remote, struct ldb_message *local)
 740 {
 741         struct ldb_message_element *el, *oc;
 742         struct ldb_val val;
 743         bool found_extensibleObject = false;
 744         int i;
 745
 746         /* Find old local objectClass */
 747         oc = ldb_msg_find_element(old, "objectClass");
 748         if (oc == NULL) {
 749                 return;
 750         }
 751
 752         /* Prepare new element */
 753         el = talloc_zero(remote, struct ldb_message_element);
 754         if (el == NULL) {
 755                 ldb_oom(module->ldb);
 756                 return;                 /* TODO: fail? */
 757         }
 758
 759         /* Copy local objectClass element, reverse space for an extra value */
 760         el->num_values = oc->num_values + 1;
 761         el->values = talloc_array(el, struct ldb_val, el->num_values);
 762         if (el->values == NULL) {
 763                 talloc_free(el);
 764                 ldb_oom(module->ldb);
 765                 return;                 /* TODO: fail? */
 766         }
 767
 768         /* Copy local element name "objectClass" */
 769         el->name = talloc_strdup(el, local_attr);
 770
 771         /* Convert all local objectClasses */
 772         for (i = 0; i < el->num_values - 1; i++) {
 773                 el->values[i] = map_objectclass_convert_local(module, el->values, &oc->values[i]);
 774                 if (ldb_attr_cmp((char *)el->values[i].data, "extensibleObject") == 0) {
 775                         found_extensibleObject = true;
 776                 }
 777         }
 778
 779         if (!found_extensibleObject) {
 780                 val.data = (uint8_t *)talloc_strdup(el->values, "extensibleObject");
 781                 val.length = strlen((char *)val.data);
 782
 783                 /* Append additional objectClass "extensibleObject" */
 784                 el->values[i] = val;
 785         } else {
 786                 el->num_values--;
 787         }
 788
 789         /* Add new objectClass to remote message */
 790         ldb_msg_add(remote, el, 0);
 791 }
 792
 793 /* Map an objectClass into the local partition. */
 794 static struct ldb_val map_objectclass_convert_remote(struct ldb_module *module, void *mem_ctx, const struct ldb_val *val)
 795 {
 796         const struct ldb_map_context *data = map_get_context(module);
 797         const char *name = (char *)val->data;
 798         const struct ldb_map_objectclass *map = map_objectclass_find_remote(data, name);
 799         struct ldb_val newval;
 800
 801         if (map) {
 802                 newval.data = (uint8_t*)talloc_strdup(mem_ctx, map->local_name);
 803                 newval.length = strlen((char *)newval.data);
 804                 return newval;
 805         }
 806
 807         return ldb_val_dup(mem_ctx, val);
 808 }
 809
 810 /* Generate a local message with a mapped objectClass. */
 811 static struct ldb_message_element *map_objectclass_generate_local(struct ldb_module *module, void *mem_ctx, const char *local_attr, const struct ldb_message *remote)
 812 {
 813         struct ldb_message_element *el, *oc;
 814         struct ldb_val val;
 815         int i;
 816
 817         /* Find old remote objectClass */
 818         oc = ldb_msg_find_element(remote, "objectClass");
 819         if (oc == NULL) {
 820                 return NULL;
 821         }
 822
 823         /* Prepare new element */
 824         el = talloc_zero(mem_ctx, struct ldb_message_element);
 825         if (el == NULL) {
 826                 ldb_oom(module->ldb);
 827                 return NULL;
 828         }
 829
 830         /* Copy remote objectClass element */
 831         el->num_values = oc->num_values;
 832         el->values = talloc_array(el, struct ldb_val, el->num_values);
 833         if (el->values == NULL) {
 834                 talloc_free(el);
 835                 ldb_oom(module->ldb);
 836                 return NULL;
 837         }
 838
 839         /* Copy remote element name "objectClass" */
 840         el->name = talloc_strdup(el, local_attr);
 841
 842         /* Convert all remote objectClasses */
 843         for (i = 0; i < el->num_values; i++) {
 844                 el->values[i] = map_objectclass_convert_remote(module, el->values, &oc->values[i]);
 845         }
 846
 847         val.data = (uint8_t *)talloc_strdup(el->values, "extensibleObject");
 848         val.length = strlen((char *)val.data);
 849
 850         /* Remove last value if it was "extensibleObject" */
 851         if (ldb_val_equal_exact(&val, &el->values[i-1])) {
 852                 el->num_values--;
 853                 el->values = talloc_realloc(el, el->values, struct ldb_val, el->num_values);
 854                 if (el->values == NULL) {
 855                         talloc_free(el);
 856                         ldb_oom(module->ldb);
 857                         return NULL;
 858                 }
 859         }
 860
 861         return el;
 862 }
 863
 864 /* Mappings for searches on objectClass= assuming a one-to-one
 865  * mapping.  Needed because this is a generate operator for the
 866  * add/modify code */
 867 static int map_objectclass_convert_operator(struct ldb_module *module, void *mem_ctx,
 868                                             struct ldb_parse_tree **new, const struct ldb_parse_tree *tree)
 869 {
 870
 871         static const struct ldb_map_attribute objectclass_map = {
 872                 .local_name = "objectClass",
 873                 .type = MAP_CONVERT,
 874                 .u = {
 875                         .convert = {
 876                                  .remote_name = "objectClass",
 877                                  .convert_local = map_objectclass_convert_local,
 878                                  .convert_remote = map_objectclass_convert_remote,
 879                          },
 880                 },
 881         };
 882
 883         return map_subtree_collect_remote_simple(module, mem_ctx, new, tree, &objectclass_map);
 884 }
 885
 886 /* Auxiliary request construction
 887  * ============================== */
 888
 889 /* Store the DN of a single search result in context. */
 890 static int map_search_self_callback(struct ldb_context *ldb, void *context, struct ldb_reply *ares)
 891 {
 892         struct map_context *ac;
 893
 894         if (context == NULL || ares == NULL) {
 895                 ldb_set_errstring(ldb, talloc_asprintf(ldb, "NULL Context or Result in callback"));
 896                 return LDB_ERR_OPERATIONS_ERROR;
 897         }
 898
 899         ac = talloc_get_type(context, struct map_context);
 900
 901         /* We are interested only in the single reply */
 902         if (ares->type != LDB_REPLY_ENTRY) {
 903                 talloc_free(ares);
 904                 return LDB_SUCCESS;
 905         }
 906
 907         /* We have already found a remote DN */
 908         if (ac->local_dn) {
 909                 ldb_set_errstring(ldb, talloc_asprintf(ldb, "Too many results to base search"));
 910                 talloc_free(ares);
 911                 return LDB_ERR_OPERATIONS_ERROR;
 912         }
 913
 914         /* Store local DN */
 915         ac->local_dn = ares->message->dn;
 916
 917         return LDB_SUCCESS;
 918 }
 919
 920 /* Build a request to search a record by its DN. */
 921 struct ldb_request *map_search_base_req(struct map_context *ac, struct ldb_dn *dn, const char * const *attrs, const struct ldb_parse_tree *tree, void *context, ldb_search_callback callback)
 922 {
 923         struct ldb_request *req;
 924
 925         req = talloc_zero(ac, struct ldb_request);
 926         if (req == NULL) {
 927                 map_oom(ac->module);
 928                 return NULL;
 929         }
 930
 931         req->operation = LDB_SEARCH;
 932         req->op.search.base = dn;
 933         req->op.search.scope = LDB_SCOPE_BASE;
 934         req->op.search.attrs = attrs;
 935
 936         if (tree) {
 937                 req->op.search.tree = tree;
 938         } else {
 939                 req->op.search.tree = ldb_parse_tree(req, NULL);
 940                 if (req->op.search.tree == NULL) {
 941                         talloc_free(req);
 942                         return NULL;
 943                 }
 944         }
 945
 946         req->controls = NULL;
 947         req->context = context;
 948         req->callback = callback;
 949         ldb_set_timeout_from_prev_req(ac->module->ldb, ac->orig_req, req);
 950
 951         return req;
 952 }
 953
 954 /* Build a request to search the local record by its DN. */
 955 struct ldb_request *map_search_self_req(struct map_context *ac, struct ldb_dn *dn)
 956 {
 957         /* attrs[] is returned from this function in
 958          * ac->search_req->op.search.attrs, so it must be static, as
 959          * otherwise the compiler can put it on the stack */
 960         static const char * const attrs[] = { IS_MAPPED, NULL };
 961         struct ldb_parse_tree *tree;
 962
 963         /* Limit search to records with 'IS_MAPPED' present */
 964         /* TODO: `tree = ldb_parse_tree(ac, IS_MAPPED);' won't do. */
 965         tree = talloc_zero(ac, struct ldb_parse_tree);
 966         if (tree == NULL) {
 967                 map_oom(ac->module);
 968                 return NULL;
 969         }
 970
 971         tree->operation = LDB_OP_PRESENT;
 972         tree->u.present.attr = talloc_strdup(tree, IS_MAPPED);
 973
 974         return map_search_base_req(ac, dn, attrs, tree, ac, map_search_self_callback);
 975 }
 976
 977 /* Build a request to update the 'IS_MAPPED' attribute */
 978 struct ldb_request *map_build_fixup_req(struct map_context *ac, struct ldb_dn *olddn, struct ldb_dn *newdn)
 979 {
 980         struct ldb_request *req;
 981         struct ldb_message *msg;
 982         const char *dn;
 983
 984         /* Prepare request */
 985         req = talloc_zero(ac, struct ldb_request);
 986         if (req == NULL) {
 987                 map_oom(ac->module);
 988                 return NULL;
 989         }
 990
 991         /* Prepare message */
 992         msg = ldb_msg_new(req);
 993         if (msg == NULL) {
 994                 map_oom(ac->module);
 995                 goto failed;
 996         }
 997
 998         /* Update local 'IS_MAPPED' to the new remote DN */
 999         msg->dn = ldb_dn_copy(msg, olddn);
1000         dn = ldb_dn_alloc_linearized(msg, newdn);
1001         if ( ! dn || ! ldb_dn_validate(msg->dn)) {
1002                 goto failed;
1003         }
1004         if (ldb_msg_add_empty(msg, IS_MAPPED, LDB_FLAG_MOD_REPLACE, NULL) != 0) {
1005                 goto failed;
1006         }
1007         if (ldb_msg_add_string(msg, IS_MAPPED, dn) != 0) {
1008                 goto failed;
1009         }
1010
1011         req->operation = LDB_MODIFY;
1012         req->op.mod.message = msg;
1013         req->controls = NULL;
1014         req->handle = NULL;
1015         req->context = NULL;
1016         req->callback = NULL;
1017
1018         return req;
1019
1020 failed:
1021         talloc_free(req);
1022         return NULL;
1023 }
1024
1025
1026 /* Asynchronous call structure
1027  * =========================== */
1028
1029 /* Figure out which request is currently pending. */
1030 static struct ldb_request *map_get_req(struct map_context *ac)
1031 {
1032         switch (ac->step) {
1033         case MAP_SEARCH_SELF_MODIFY:
1034         case MAP_SEARCH_SELF_DELETE:
1035         case MAP_SEARCH_SELF_RENAME:
1036                 return ac->search_req;
1037
1038         case MAP_ADD_REMOTE:
1039         case MAP_MODIFY_REMOTE:
1040         case MAP_DELETE_REMOTE:
1041         case MAP_RENAME_REMOTE:
1042                 return ac->remote_req;
1043
1044         case MAP_RENAME_FIXUP:
1045                 return ac->down_req;
1046
1047         case MAP_ADD_LOCAL:
1048         case MAP_MODIFY_LOCAL:
1049         case MAP_DELETE_LOCAL:
1050         case MAP_RENAME_LOCAL:
1051                 return ac->local_req;
1052
1053         case MAP_SEARCH_REMOTE:
1054                 /* Can't happen */
1055                 break;
1056         }
1057
1058         return NULL;            /* unreachable; silences a warning */
1059 }
1060
1061 typedef int (*map_next_function)(struct ldb_handle *handle);
1062
1063 /* Figure out the next request to run. */
1064 static map_next_function map_get_next(struct map_context *ac)
1065 {
1066         switch (ac->step) {
1067         case MAP_SEARCH_REMOTE:
1068                 return NULL;
1069
1070         case MAP_ADD_LOCAL:
1071                 return map_add_do_remote;
1072         case MAP_ADD_REMOTE:
1073                 return NULL;
1074
1075         case MAP_SEARCH_SELF_MODIFY:
1076                 return map_modify_do_local;
1077         case MAP_MODIFY_LOCAL:
1078                 return map_modify_do_remote;
1079         case MAP_MODIFY_REMOTE:
1080                 return NULL;
1081
1082         case MAP_SEARCH_SELF_DELETE:
1083                 return map_delete_do_local;
1084         case MAP_DELETE_LOCAL:
1085                 return map_delete_do_remote;
1086         case MAP_DELETE_REMOTE:
1087                 return NULL;
1088
1089         case MAP_SEARCH_SELF_RENAME:
1090                 return map_rename_do_local;
1091         case MAP_RENAME_LOCAL:
1092                 return map_rename_do_fixup;
1093         case MAP_RENAME_FIXUP:
1094                 return map_rename_do_remote;
1095         case MAP_RENAME_REMOTE:
1096                 return NULL;
1097         }
1098
1099         return NULL;            /* unreachable; silences a warning */
1100 }
1101
1102 /* Wait for the current pending request to finish and continue with the next. */
1103 static int map_wait_next(struct ldb_handle *handle)
1104 {
1105         struct map_context *ac;
1106         struct ldb_request *req;
1107         map_next_function next;
1108         int ret;
1109
1110         if (handle == NULL || handle->private_data == NULL) {
1111                 return LDB_ERR_OPERATIONS_ERROR;
1112         }
1113
1114         if (handle->state == LDB_ASYNC_DONE) {
1115                 return handle->status;
1116         }
1117
1118         handle->state = LDB_ASYNC_PENDING;
1119         handle->status = LDB_SUCCESS;
1120
1121         ac = talloc_get_type(handle->private_data, struct map_context);
1122
1123         if (ac->step == MAP_SEARCH_REMOTE) {
1124                 int i;
1125                 for (i = 0; i < ac->num_searches; i++) {
1126                         req = ac->search_reqs[i];
1127                         ret = ldb_wait(req->handle, LDB_WAIT_NONE);
1128
1129                         if (ret != LDB_SUCCESS) {
1130                                 handle->status = ret;
1131                                 goto done;
1132                         }
1133                         if (req->handle->status != LDB_SUCCESS) {
1134                                 handle->status = req->handle->status;
1135                                 goto done;
1136                         }
1137                         if (req->handle->state != LDB_ASYNC_DONE) {
1138                                 return LDB_SUCCESS;
1139                         }
1140                 }
1141         } else {
1142
1143                 req = map_get_req(ac);
1144
1145                 ret = ldb_wait(req->handle, LDB_WAIT_NONE);
1146
1147                 if (ret != LDB_SUCCESS) {
1148                         handle->status = ret;
1149                         goto done;
1150                 }
1151                 if (req->handle->status != LDB_SUCCESS) {
1152                         handle->status = req->handle->status;
1153                         goto done;
1154                 }
1155                 if (req->handle->state != LDB_ASYNC_DONE) {
1156                         return LDB_SUCCESS;
1157                 }
1158
1159                 next = map_get_next(ac);
1160                 if (next) {
1161                         return next(handle);
1162                 }
1163         }
1164
1165         ret = LDB_SUCCESS;
1166
1167 done:
1168         handle->state = LDB_ASYNC_DONE;
1169         return ret;
1170 }
1171
1172 /* Wait for all current pending requests to finish. */
1173 static int map_wait_all(struct ldb_handle *handle)
1174 {
1175         int ret;
1176
1177         while (handle->state != LDB_ASYNC_DONE) {
1178                 ret = map_wait_next(handle);
1179                 if (ret != LDB_SUCCESS) {
1180                         return ret;
1181                 }
1182         }
1183
1184         return handle->status;
1185 }
1186
1187 /* Wait for pending requests to finish. */
1188 static int map_wait(struct ldb_handle *handle, enum ldb_wait_type type)
1189 {
1190         if (type == LDB_WAIT_ALL) {
1191                 return map_wait_all(handle);
1192         } else {
1193                 return map_wait_next(handle);
1194         }
1195 }
1196
1197
1198 /* Module initialization
1199  * ===================== */
1200
1201 /* Provided module operations */
1202 static const struct ldb_module_ops map_ops = {
1203         .name           = "ldb_map",
1204         .add            = map_add,
1205         .modify         = map_modify,
1206         .del            = map_delete,
1207         .rename         = map_rename,
1208         .search         = map_search,
1209         .wait           = map_wait,
1210 };
1211
1212 /* Builtin mappings for DNs and objectClasses */
1213 static const struct ldb_map_attribute builtin_attribute_maps[] = {
1214         {
1215                 .local_name = "dn",
1216                 .type = MAP_CONVERT,
1217                 .u = {
1218                         .convert = {
1219                                  .remote_name = "dn",
1220                                  .convert_local = ldb_dn_convert_local,
1221                                  .convert_remote = ldb_dn_convert_remote,
1222                          },
1223                 },
1224         },
1225         {
1226                 .local_name = "objectClass",
1227                 .type = MAP_GENERATE,
1228                 .convert_operator = map_objectclass_convert_operator,
1229                 .u = {
1230                         .generate = {
1231                                  .remote_names = { "objectClass", NULL },
1232                                  .generate_local = map_objectclass_generate_local,
1233                                  .generate_remote = map_objectclass_generate_remote,
1234                          },
1235                 },
1236         },
1237         {
1238                 .local_name = NULL,
1239         }
1240 };
1241
1242 /* Find the special 'MAP_DN_NAME' record and store local and remote
1243  * base DNs in private data. */
1244 static int map_init_dns(struct ldb_module *module, struct ldb_map_context *data, const char *name)
1245 {
1246         static const char * const attrs[] = { MAP_DN_FROM, MAP_DN_TO, NULL };
1247         struct ldb_dn *dn;
1248         struct ldb_message *msg;
1249         struct ldb_result *res;
1250         int ret;
1251
1252         if (!name) {
1253                 data->local_base_dn = NULL;
1254                 data->remote_base_dn = NULL;
1255                 return LDB_SUCCESS;
1256         }
1257
1258         dn = ldb_dn_new_fmt(data, module->ldb, "%s=%s", MAP_DN_NAME, name);
1259         if ( ! ldb_dn_validate(dn)) {
1260                 ldb_debug(module->ldb, LDB_DEBUG_ERROR, "ldb_map: "
1261                           "Failed to construct '%s' DN!\n", MAP_DN_NAME);
1262                 return LDB_ERR_OPERATIONS_ERROR;
1263         }
1264
1265         ret = ldb_search(module->ldb, dn, LDB_SCOPE_BASE, NULL, attrs, &res);
1266         talloc_free(dn);
1267         if (ret != LDB_SUCCESS) {
1268                 return ret;
1269         }
1270         if (res->count == 0) {
1271                 ldb_debug(module->ldb, LDB_DEBUG_ERROR, "ldb_map: "
1272                           "No results for '%s=%s'!\n", MAP_DN_NAME, name);
1273                 talloc_free(res);
1274                 return LDB_ERR_CONSTRAINT_VIOLATION;
1275         }
1276         if (res->count > 1) {
1277                 ldb_debug(module->ldb, LDB_DEBUG_ERROR, "ldb_map: "
1278                           "Too many results for '%s=%s'!\n", MAP_DN_NAME, name);
1279                 talloc_free(res);
1280                 return LDB_ERR_CONSTRAINT_VIOLATION;
1281         }
1282
1283         msg = res->msgs[0];
1284         data->local_base_dn = ldb_msg_find_attr_as_dn(module->ldb, data, msg, MAP_DN_FROM);
1285         data->remote_base_dn = ldb_msg_find_attr_as_dn(module->ldb, data, msg, MAP_DN_TO);
1286         talloc_free(res);
1287
1288         return LDB_SUCCESS;
1289 }
1290
1291 /* Store attribute maps and objectClass maps in private data. */
1292 static int map_init_maps(struct ldb_module *module, struct ldb_map_context *data,
1293                          const struct ldb_map_attribute *attrs,
1294                          const struct ldb_map_objectclass *ocls,
1295                          const char * const *wildcard_attributes)
1296 {
1297         int i, j, last;
1298         last = 0;
1299
1300         /* Count specified attribute maps */
1301         for (i = 0; attrs[i].local_name; i++) /* noop */ ;
1302         /* Count built-in attribute maps */
1303         for (j = 0; builtin_attribute_maps[j].local_name; j++) /* noop */ ;
1304
1305         /* Store list of attribute maps */
1306         data->attribute_maps = talloc_array(data, struct ldb_map_attribute, i+j+1);
1307         if (data->attribute_maps == NULL) {
1308                 map_oom(module);
1309                 return LDB_ERR_OPERATIONS_ERROR;
1310         }
1311
1312         /* Specified ones go first */
1313         for (i = 0; attrs[i].local_name; i++) {
1314                 data->attribute_maps[last] = attrs[i];
1315                 last++;
1316         }
1317
1318         /* Built-in ones go last */
1319         for (i = 0; builtin_attribute_maps[i].local_name; i++) {
1320                 data->attribute_maps[last] = builtin_attribute_maps[i];
1321                 last++;
1322         }
1323
1324         /* Ensure 'local_name == NULL' for the last entry */
1325         memset(&data->attribute_maps[last], 0, sizeof(struct ldb_map_attribute));
1326
1327         /* Store list of objectClass maps */
1328         data->objectclass_maps = ocls;
1329
1330         data->wildcard_attributes = wildcard_attributes;
1331
1332         return LDB_SUCCESS;
1333 }
1334
1335 /* Copy the list of provided module operations. */
1336 _PUBLIC_ struct ldb_module_ops ldb_map_get_ops(void)
1337 {
1338         return map_ops;
1339 }
1340
1341 /* Initialize global private data. */
1342 _PUBLIC_ int ldb_map_init(struct ldb_module *module, const struct ldb_map_attribute *attrs,
1343                  const struct ldb_map_objectclass *ocls,
1344                  const char * const *wildcard_attributes,
1345                  const char *name)
1346 {
1347         struct map_private *data;
1348         int ret;
1349
1350         /* Prepare private data */
1351         data = talloc_zero(module, struct map_private);
1352         if (data == NULL) {
1353                 map_oom(module);
1354                 return LDB_ERR_OPERATIONS_ERROR;
1355         }
1356
1357         module->private_data = data;
1358
1359         data->context = talloc_zero(data, struct ldb_map_context);
1360         if (!data->context) {
1361                 map_oom(module);
1362                 return LDB_ERR_OPERATIONS_ERROR;
1363         }
1364
1365         /* Store local and remote baseDNs */
1366         ret = map_init_dns(module, data->context, name);
1367         if (ret != LDB_SUCCESS) {
1368                 talloc_free(data);
1369                 return ret;
1370         }
1371
1372         /* Store list of attribute and objectClass maps */
1373         ret = map_init_maps(module, data->context, attrs, ocls, wildcard_attributes);
1374         if (ret != LDB_SUCCESS) {
1375                 talloc_free(data);
1376                 return ret;
1377         }
1378
1379         return LDB_SUCCESS;
1380 }
1381
1382 /* Usage note for initialization of this module:
1383  *
1384  * ldb_map is meant to be used from a different module that sets up
1385  * the mappings and gets registered in ldb.
1386  *
1387  * 'ldb_map_init' initializes the private data of this module and
1388  * stores the attribute and objectClass maps in there.  It also looks
1389  * up the '@MAP' special DN so requests can be redirected to the
1390  * remote partition.
1391  *
1392  * This function should be called from the 'init_context' op of the
1393  * module using ldb_map.
1394  *
1395  * 'ldb_map_get_ops' returns a copy of ldb_maps module operations.
1396  *
1397  * It should be called from the initialize function of the using
1398  * module, which should then override the 'init_context' op with a
1399  * function making the appropriate calls to 'ldb_map_init'.
1400  */