1 /* 2 ldb database library 3 4 Copyright (C) Simo Sorce 2008 5 6 ** NOTE! The following LGPL license applies to the ldb 7 ** library. This does NOT imply that all of Samba is released 8 ** under the LGPL 9 10 This library is free software; you can redistribute it and/or 11 modify it under the terms of the GNU Lesser General Public 12 License as published by the Free Software Foundation; either 13 version 3 of the License, or (at your option) any later version. 14 15 This library is distributed in the hope that it will be useful, 16 but WITHOUT ANY WARRANTY; without even the implied warranty of 17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 18 Lesser General Public License for more details. 19 20 You should have received a copy of the GNU Lesser General Public 21 License along with this library; if not, see <http://www.gnu.org/licenses/>. 22 */ 23 24 /* 25 * Name: ldb 26 * 27 * Component: ldb module header 28 * 29 * Description: defines ldb modules structures and helpers 30 * 31 */ 32 33 #ifndef _LDB_MODULE_H_ 34 #define _LDB_MODULE_H_ 35 36 #include <ldb.h> 37 38 #if defined(_SAMBA_BUILD_) && defined(USING_SYSTEM_LDB) 39 40 /* 41 * Versions before 1.2.0 doesn't define these values 42 * so we assime 1.1.29 (which was used in Samba 4.6) 43 * 44 * See https://bugzilla.samba.org/show_bug.cgi?id=12859 45 */ 46 #ifndef EXPECTED_SYSTEM_LDB_VERSION_MAJOR 47 #define EXPECTED_SYSTEM_LDB_VERSION_MAJOR 1 48 #endif 49 #ifndef EXPECTED_SYSTEM_LDB_VERSION_MINOR 50 #define EXPECTED_SYSTEM_LDB_VERSION_MINOR 1 51 #endif 52 #ifndef EXPECTED_SYSTEM_LDB_VERSION_MINOR 53 #define EXPECTED_SYSTEM_LDB_VERSION_MINOR 29 54 #endif 55 56 /* 57 * Only Samba versions which expect ldb >= 1.4.0 58 * reopen the ldb after each fork(). 59 * 60 * See https://bugzilla.samba.org/show_bug.cgi?id=13519 61 */ 62 #if EXPECTED_SYSTEM_LDB_VERSION_MAJOR > 1 63 #define __LDB_FORK_COMPATIBLE__ 1 64 #elif EXPECTED_SYSTEM_LDB_VERSION_MINOR > 3 65 #define __LDB_FORK_COMPATIBLE__ 1 66 #endif 67 #ifndef __LDB_FORK_COMPATIBLE__ 68 #error "Samba < 4.9 is not compatible with this version of ldb due to assumptions around fork() behaviour" 69 #endif 70 71 #endif /* defined(_SAMBA_BUILD_) && defined(USING_SYSTEM_LDB) */ 72 73 struct ldb_context; 74 struct ldb_module; 75 76 /** 77 internal flag bits on message elements. Must be within LDB_FLAG_INTERNAL_MASK 78 */ 79 #define LDB_FLAG_INTERNAL_DISABLE_VALIDATION 0x10 80 81 /* disable any single value checking on this attribute */ 82 #define LDB_FLAG_INTERNAL_DISABLE_SINGLE_VALUE_CHECK 0x20 83 84 /* attribute has failed access check and must not be exposed */ 85 #define LDB_FLAG_INTERNAL_INACCESSIBLE_ATTRIBUTE 0x40 86 87 /* force single value checking on this attribute */ 88 #define LDB_FLAG_INTERNAL_FORCE_SINGLE_VALUE_CHECK 0x80 89 90 /* 91 * ensure that this value is unique on an index 92 * (despite the index not otherwise being configured as UNIQUE). 93 * For example, all words starting with 'a' must be unique, but duplicates of 94 * words starting with b are allowed. This is specifically for Samba's 95 * objectSid index which is unique in the primary domain only. 96 */ 97 #define LDB_FLAG_INTERNAL_FORCE_UNIQUE_INDEX 0x100 98 99 /* an extended match rule that always fails to match */ 100 #define SAMBA_LDAP_MATCH_ALWAYS_FALSE "1.3.6.1.4.1.7165.4.5.1" 101 102 /* The const char * const * pointer to a list of secret (password) 103 * attributes, not to be printed in trace messages */ 104 #define LDB_SECRET_ATTRIBUTE_LIST_OPAQUE "LDB_SECRET_ATTRIBUTE_LIST" 105 106 /* 107 * The scheme to be used for referral entries, i.e. ldap or ldaps 108 */ 109 #define LDAP_REFERRAL_SCHEME_OPAQUE "LDAP_REFERRAL_SCHEME" 110 111 /* 112 these function pointers define the operations that a ldb module can intercept 113 */ 114 struct ldb_module_ops { 115 const char *name; 116 int (*init_context) (struct ldb_module *); 117 int (*search)(struct ldb_module *, struct ldb_request *); /* search */ 118 int (*add)(struct ldb_module *, struct ldb_request *); /* add */ 119 int (*modify)(struct ldb_module *, struct ldb_request *); /* modify */ 120 int (*del)(struct ldb_module *, struct ldb_request *); /* delete */ 121 int (*rename)(struct ldb_module *, struct ldb_request *); /* rename */ 122 int (*request)(struct ldb_module *, struct ldb_request *); /* match any other operation */ 123 int (*extended)(struct ldb_module *, struct ldb_request *); /* extended operations */ 124 int (*start_transaction)(struct ldb_module *); 125 int (*prepare_commit)(struct ldb_module *); 126 int (*end_transaction)(struct ldb_module *); 127 int (*del_transaction)(struct ldb_module *); 128 int (*sequence_number)(struct ldb_module *, struct ldb_request *); 129 int (*read_lock)(struct ldb_module *); 130 int (*read_unlock)(struct ldb_module *); 131 void *private_data; 132 }; 133 134 135 /* The following definitions come from lib/ldb/common/ldb_debug.c */ 136 void ldb_debug(struct ldb_context *ldb, enum ldb_debug_level level, const char *fmt, ...) PRINTF_ATTRIBUTE(3, 4); 137 void ldb_debug_set(struct ldb_context *ldb, enum ldb_debug_level level, 138 const char *fmt, ...) PRINTF_ATTRIBUTE(3, 4); 139 void ldb_debug_add(struct ldb_context *ldb, const char *fmt, ...) PRINTF_ATTRIBUTE(2, 3); 140 void ldb_debug_end(struct ldb_context *ldb, enum ldb_debug_level level); 141 void ldb_vdebug(struct ldb_context *ldb, enum ldb_debug_level level, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3, 0); 142 143 #define ldb_error(ldb, ecode, reason) ldb_error_at(ldb, ecode, reason, __FILE__, __LINE__) 144 #define ldb_module_error(module, ecode, reason) ldb_error_at(ldb_module_get_ctx(module), ecode, reason, __FILE__, __LINE__) 145 146 #define ldb_oom(ldb) ldb_error(ldb, LDB_ERR_OPERATIONS_ERROR, "ldb out of memory") 147 #define ldb_module_oom(module) ldb_oom(ldb_module_get_ctx(module)) 148 #define ldb_operr(ldb) ldb_error(ldb, LDB_ERR_OPERATIONS_ERROR, "operations error") 149 #define ldb_module_operr(module) ldb_error(ldb_module_get_ctx(module), LDB_ERR_OPERATIONS_ERROR, "operations error") 150 151 /* The following definitions come from lib/ldb/common/ldb.c */ 152 153 void ldb_request_set_state(struct ldb_request *req, int state); 154 int ldb_request_get_status(struct ldb_request *req); 155 156 unsigned int ldb_get_create_perms(struct ldb_context *ldb); 157 158 const struct ldb_schema_syntax *ldb_standard_syntax_by_name(struct ldb_context *ldb, 159 const char *syntax); 160 161 /* The following definitions come from lib/ldb/common/ldb_attributes.c */ 162 163 int ldb_schema_attribute_add_with_syntax(struct ldb_context *ldb, 164 const char *name, 165 unsigned flags, 166 const struct ldb_schema_syntax *syntax); 167 int ldb_schema_attribute_add(struct ldb_context *ldb, 168 const char *name, 169 unsigned flags, 170 const char *syntax); 171 void ldb_schema_attribute_remove(struct ldb_context *ldb, const char *name); 172 173 /* we allow external code to override the name -> schema_attribute function */ 174 typedef const struct ldb_schema_attribute *(*ldb_attribute_handler_override_fn_t)(struct ldb_context *, void *, const char *); 175 176 /** 177 Allow the caller to define a callback for the attribute handler 178 179 \param ldb The ldb context 180 \param override The callback to be used for attribute lookups 181 \param private_data Private data for the callback 182 183 */ 184 void ldb_schema_attribute_set_override_handler(struct ldb_context *ldb, 185 ldb_attribute_handler_override_fn_t override, 186 void *private_data); 187 188 /** 189 Allow the caller to define that the callback for the attribute handler 190 also overrides the index list 191 192 \param ldb The ldb context 193 \param one_level_indexes Indicates that the index for SCOPE_ONELEVEL 194 should also be maintained 195 196 */ 197 void ldb_schema_set_override_indexlist(struct ldb_context *ldb, 198 bool one_level_indexes); 199 200 /** 201 202 \param ldb The ldb context 203 \param GUID_index_attribute The globally attribute (eg objectGUID) 204 on each entry 205 \param GUID_index_attribute The DN component matching the 206 globally attribute on each entry (eg GUID) 207 208 The caller must ensure the supplied strings do not go out of 209 scope (they are typically constant memory). 210 211 */ 212 void ldb_schema_set_override_GUID_index(struct ldb_context *ldb, 213 const char *GUID_index_attribute, 214 const char *GUID_index_dn_component); 215 216 /* A useful function to build comparison functions with */ 217 int ldb_any_comparison(struct ldb_context *ldb, void *mem_ctx, 218 ldb_attr_handler_t canonicalise_fn, 219 const struct ldb_val *v1, 220 const struct ldb_val *v2); 221 222 /* The following definitions come from lib/ldb/common/ldb_controls.c */ 223 int ldb_save_controls(struct ldb_control *exclude, struct ldb_request *req, struct ldb_control ***saver); 224 /* Returns a list of controls, except the one specified. Included 225 * controls become a child of returned list if they were children of 226 * controls_in */ 227 struct ldb_control **ldb_controls_except_specified(struct ldb_control **controls_in, 228 TALLOC_CTX *mem_ctx, 229 struct ldb_control *exclude); 230 int ldb_check_critical_controls(struct ldb_control **controls); 231 232 /* The following definitions come from lib/ldb/common/ldb_ldif.c */ 233 int ldb_should_b64_encode(struct ldb_context *ldb, const struct ldb_val *val); 234 235 /* The following definitions come from lib/ldb/common/ldb_match.c */ 236 int ldb_match_msg(struct ldb_context *ldb, 237 const struct ldb_message *msg, 238 const struct ldb_parse_tree *tree, 239 struct ldb_dn *base, 240 enum ldb_scope scope); 241 242 int ldb_match_msg_error(struct ldb_context *ldb, 243 const struct ldb_message *msg, 244 const struct ldb_parse_tree *tree, 245 struct ldb_dn *base, 246 enum ldb_scope scope, 247 bool *matched); 248 249 int ldb_match_msg_objectclass(const struct ldb_message *msg, 250 const char *objectclass); 251 252 int ldb_register_extended_match_rules(struct ldb_context *ldb); 253 254 /* The following definitions come from lib/ldb/common/ldb_modules.c */ 255 256 struct ldb_module *ldb_module_new(TALLOC_CTX *memctx, 257 struct ldb_context *ldb, 258 const char *module_name, 259 const struct ldb_module_ops *ops); 260 261 const char * ldb_module_get_name(struct ldb_module *module); 262 struct ldb_context *ldb_module_get_ctx(struct ldb_module *module); 263 void *ldb_module_get_private(struct ldb_module *module); 264 void ldb_module_set_private(struct ldb_module *module, void *private_data); 265 const struct ldb_module_ops *ldb_module_get_ops(struct ldb_module *module); 266 267 int ldb_next_request(struct ldb_module *module, struct ldb_request *request); 268 int ldb_next_start_trans(struct ldb_module *module); 269 int ldb_next_end_trans(struct ldb_module *module); 270 int ldb_next_del_trans(struct ldb_module *module); 271 int ldb_next_prepare_commit(struct ldb_module *module); 272 int ldb_next_init(struct ldb_module *module); 273 int ldb_next_read_lock(struct ldb_module *module); 274 int ldb_next_read_unlock(struct ldb_module *module); 275 276 void ldb_set_errstring(struct ldb_context *ldb, const char *err_string); 277 void ldb_asprintf_errstring(struct ldb_context *ldb, const char *format, ...) PRINTF_ATTRIBUTE(2,3); 278 void ldb_reset_err_string(struct ldb_context *ldb); 279 int ldb_error_at(struct ldb_context *ldb, int ecode, const char *reason, const char *file, int line); 280 281 const char *ldb_default_modules_dir(void); 282 283 int ldb_register_module(const struct ldb_module_ops *); 284 285 typedef int (*ldb_connect_fn)(struct ldb_context *ldb, const char *url, 286 unsigned int flags, const char *options[], 287 struct ldb_module **module); 288 289 /** 290 Require that LDB use a private event context for each request 291 292 A private event context may need to be created to avoid nested event 293 loops during ldb_tdb with the locks held. This indicates that a 294 backend is in use that requires this to hold locks safely. 295 296 \param handle The ldb handle to set the flag on 297 */ 298 void ldb_set_require_private_event_context(struct ldb_context *ldb); 299 300 struct ldb_backend_ops { 301 const char *name; 302 ldb_connect_fn connect_fn; 303 }; 304 305 const char *ldb_default_modules_dir(void); 306 307 int ldb_register_backend(const char *url_prefix, ldb_connect_fn, bool); 308 309 struct ldb_handle *ldb_handle_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb); 310 311 /** 312 Obtains the private event context for the handle, 313 314 A private event context may have been created to avoid nested event 315 loops during ldb_tdb with the locks held. Otherwise return the 316 global one. 317 318 \param handle The ldb handle to obtain the event context for 319 \return the tevent event context for this handle (private or global) 320 */ 321 struct tevent_context *ldb_handle_get_event_context(struct ldb_handle *handle); 322 323 int ldb_module_send_entry(struct ldb_request *req, 324 struct ldb_message *msg, 325 struct ldb_control **ctrls); 326 327 int ldb_module_send_referral(struct ldb_request *req, 328 char *ref); 329 330 int ldb_module_done(struct ldb_request *req, 331 struct ldb_control **ctrls, 332 struct ldb_extended *response, 333 int error); 334 335 int ldb_mod_register_control(struct ldb_module *module, const char *oid); 336 337 void ldb_set_default_dns(struct ldb_context *ldb); 338 /** 339 Add a ldb_control to a ldb_reply 340 341 \param ares the reply struct where to add the control 342 \param oid the object identifier of the control as string 343 \param critical whether the control should be critical or not 344 \param data a talloc pointer to the control specific data 345 346 \return result code (LDB_SUCCESS on success, or a failure code) 347 */ 348 int ldb_reply_add_control(struct ldb_reply *ares, const char *oid, bool critical, void *data); 349 350 /** 351 mark a request as untrusted. 352 353 This tells the rootdse module to remove unregistered controls 354 355 \param req the request to mark as untrusted 356 */ 357 void ldb_req_mark_untrusted(struct ldb_request *req); 358 359 /** 360 mark a request as trusted. 361 362 This tells the rootdse module to allow unregistered controls 363 364 \param req the request to mark as trusted 365 */ 366 void ldb_req_mark_trusted(struct ldb_request *req); 367 368 /** 369 return true is a request is untrusted 370 371 This indicates the request came across a trust boundary 372 for example over LDAP 373 374 \param req the request check 375 \return is req trusted 376 */ 377 bool ldb_req_is_untrusted(struct ldb_request *req); 378 379 /** 380 set custom flags. Those flags are set by applications using ldb, 381 they are application dependent and the same bit can have different 382 meaning in different application. 383 */ 384 void ldb_req_set_custom_flags(struct ldb_request *req, uint32_t flags); 385 386 /** 387 get custom flags. Those flags are set by applications using ldb, 388 they are application dependent and the same bit can have different 389 meaning in different application. 390 */ 391 uint32_t ldb_req_get_custom_flags(struct ldb_request *req); 392 393 /* load all modules from the given directory */ 394 int ldb_modules_load(const char *modules_path, const char *version); 395 396 /* init functions prototype */ 397 typedef int (*ldb_module_init_fn)(const char *); 398 399 /* 400 general ldb hook function 401 */ 402 enum ldb_module_hook_type { LDB_MODULE_HOOK_CMDLINE_OPTIONS = 1, 403 LDB_MODULE_HOOK_CMDLINE_PRECONNECT = 2, 404 LDB_MODULE_HOOK_CMDLINE_POSTCONNECT = 3 }; 405 406 typedef int (*ldb_hook_fn)(struct ldb_context *, enum ldb_module_hook_type ); 407 408 /* 409 register a ldb hook function 410 */ 411 int ldb_register_hook(ldb_hook_fn hook_fn); 412 413 /* 414 call ldb hooks of a given type 415 */ 416 int ldb_modules_hook(struct ldb_context *ldb, enum ldb_module_hook_type t); 417 418 #define LDB_MODULE_CHECK_VERSION(version) do { \ 419 if (strcmp(version, LDB_VERSION) != 0) { \ 420 fprintf(stderr, "ldb: module version mismatch in %s : ldb_version=%s module_version=%s\n", \ 421 __FILE__, version, LDB_VERSION); \ 422 return LDB_ERR_UNAVAILABLE; \ 423 }} while (0) 424 425 426 /* 427 return a string representation of the calling chain for the given 428 ldb request 429 */ 430 char *ldb_module_call_chain(struct ldb_request *req, TALLOC_CTX *mem_ctx); 431 432 /* 433 return the next module in the chain 434 */ 435 struct ldb_module *ldb_module_next(struct ldb_module *module); 436 437 /* 438 set the next module in the module chain 439 */ 440 void ldb_module_set_next(struct ldb_module *module, struct ldb_module *next); 441 442 /* 443 load a list of modules 444 */ 445 int ldb_module_load_list(struct ldb_context *ldb, const char **module_list, 446 struct ldb_module *backend, struct ldb_module **out); 447 448 /* 449 get the popt_options pointer in the ldb structure. This allows a ldb 450 module to change the command line parsing 451 */ 452 struct poptOption **ldb_module_popt_options(struct ldb_context *ldb); 453 454 /* modules are called in inverse order on the stack. 455 Lets place them as an admin would think the right order is. 456 Modules order is important */ 457 const char **ldb_modules_list_from_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *string); 458 459 /* 460 return the current ldb flags LDB_FLG_* 461 */ 462 uint32_t ldb_module_flags(struct ldb_context *ldb); 463 464 int ldb_module_connect_backend(struct ldb_context *ldb, 465 const char *url, 466 const char *options[], 467 struct ldb_module **backend_module); 468 469 /* 470 initialise a chain of modules 471 */ 472 int ldb_module_init_chain(struct ldb_context *ldb, struct ldb_module *module); 473 474 /* 475 * prototype for the init function defined by dynamically loaded modules 476 */ 477 int ldb_init_module(const char *version); 478 479 /* replace the components of a DN with those from another DN, without 480 * touching the extended components 481 * 482 * return true if successful and false if not 483 * if false is returned the dn may be marked invalid 484 */ 485 bool ldb_dn_replace_components(struct ldb_dn *dn, struct ldb_dn *new_dn); 486 487 /* 488 walk a parse tree, calling the provided callback on each node 489 */ 490 int ldb_parse_tree_walk(struct ldb_parse_tree *tree, 491 int (*callback)(struct ldb_parse_tree *tree, void *), 492 void *private_context); 493 494 /* compare two message elements with ordering - used by modify */ 495 bool ldb_msg_element_equal_ordered(const struct ldb_message_element *el1, 496 const struct ldb_message_element *el2); 497 498 499 struct ldb_extended_match_rule 500 { 501 const char *oid; 502 int (*callback)(struct ldb_context *, const char *oid, 503 const struct ldb_message *, const char *, 504 const struct ldb_val *, bool *); 505 }; 506 507 int ldb_register_extended_match_rule(struct ldb_context *ldb, 508 const struct ldb_extended_match_rule *rule); 509 510 /* 511 * these pack/unpack functions are exposed in the library for use by 512 * ldb tools like ldbdump and for use in tests, 513 * but are not part of the public API 514 */ 515 int ldb_pack_data(struct ldb_context *ldb, 516 const struct ldb_message *message, 517 struct ldb_val *data); 518 /* 519 * Unpack a ldb message from a linear buffer in ldb_val 520 * 521 * Providing a list of attributes to this function allows selective unpacking. 522 * Giving a NULL list (or a list_size of 0) unpacks all the attributes. 523 */ 524 int ldb_unpack_data_only_attr_list(struct ldb_context *ldb, 525 const struct ldb_val *data, 526 struct ldb_message *message, 527 const char* const * list, 528 unsigned int list_size, 529 unsigned int *nb_attributes_indb); 530 int ldb_unpack_data(struct ldb_context *ldb, 531 const struct ldb_val *data, 532 struct ldb_message *message); 533 /* 534 * Unpack a ldb message from a linear buffer in ldb_val 535 * 536 * Providing a list of attributes to this function allows selective unpacking. 537 * Giving a NULL list (or a list_size of 0) unpacks all the attributes. 538 * 539 * Flags allow control of allocation, so that if 540 * LDB_UNPACK_DATA_FLAG_NO_DATA_ALLOC is specified, then data in values are 541 * not allocated, instead they point into the supplier constant buffer. 542 * 543 * If LDB_UNPACK_DATA_FLAG_NO_VALUES_ALLOC is specified, then values 544 * array are not allocated individually (for single-valued 545 * attributes), instead they point into a single buffer per message. 546 * 547 * LDB_UNPACK_DATA_FLAG_NO_VALUES_ALLOC is only valid when 548 * LDB_UNPACK_DATA_FLAG_NO_DATA_ALLOC is also specified. 549 * 550 * Likewise if LDB_UNPACK_DATA_FLAG_NO_DN is specified, the DN is omitted. 551 * 552 * If LDB_UNPACK_DATA_FLAG_NO_ATTRS is specified, then no attributes 553 * are unpacked or returned. 554 * 555 */ 556 int ldb_unpack_data_only_attr_list_flags(struct ldb_context *ldb, 557 const struct ldb_val *data, 558 struct ldb_message *message, 559 const char * const *list, 560 unsigned int list_size, 561 unsigned int flags, 562 unsigned int *nb_elements_in_db); 563 564 int ldb_unpack_get_format(const struct ldb_val *data, 565 uint32_t *pack_format_version); 566 567 #define LDB_UNPACK_DATA_FLAG_NO_DATA_ALLOC 0x0001 568 #define LDB_UNPACK_DATA_FLAG_NO_DN 0x0002 569 #define LDB_UNPACK_DATA_FLAG_NO_VALUES_ALLOC 0x0004 570 #define LDB_UNPACK_DATA_FLAG_NO_ATTRS 0x0008 571 572 /* In-use packing formats */ 573 #define LDB_PACKING_FORMAT 0x26011967 574 575 /* Old packing formats */ 576 #define LDB_PACKING_FORMAT_NODN 0x26011966 577 578 /** 579 Forces a specific ldb handle to use the global event context. 580 581 This allows a nested event loop to operate, so any open 582 transaction also needs to be aborted. 583 584 Any events on this event context will be lost. 585 586 This is used in Samba when sending an IRPC to another part of the 587 same process instead of making a local DB modification. 588 589 \param handle The ldb handle to force to use the global context 590 591 */ 592 void ldb_handle_use_global_event_context(struct ldb_handle *handle); 593 594 #endif 595