4 Copyright (C) Simo Sorce 2008
6 ** NOTE! The following LGPL license applies to the ldb
7 ** library. This does NOT imply that all of Samba is released
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.
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.
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/>.
27 * Component: ldb module header
29 * Description: defines ldb modules structures and helpers
33 #ifndef _LDB_MODULE_H_
34 #define _LDB_MODULE_H_
38 #if defined(_SAMBA_BUILD_) && defined(USING_SYSTEM_LDB)
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)
44 * See https://bugzilla.samba.org/show_bug.cgi?id=12859
46 #ifndef EXPECTED_SYSTEM_LDB_VERSION_MAJOR
47 #define EXPECTED_SYSTEM_LDB_VERSION_MAJOR 1
49 #ifndef EXPECTED_SYSTEM_LDB_VERSION_MINOR
50 #define EXPECTED_SYSTEM_LDB_VERSION_MINOR 1
52 #ifndef EXPECTED_SYSTEM_LDB_VERSION_MINOR
53 #define EXPECTED_SYSTEM_LDB_VERSION_MINOR 29
57 * Only Samba versions which expect ldb >= 1.4.0
58 * reopen the ldb after each fork().
60 * See https://bugzilla.samba.org/show_bug.cgi?id=13519
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
67 #ifndef __LDB_FORK_COMPATIBLE__
68 #error "Samba < 4.9 is not compatible with this version of ldb due to assumptions around fork() behaviour"
71 #endif /* defined(_SAMBA_BUILD_) && defined(USING_SYSTEM_LDB) */
77 internal flag bits on message elements. Must be within LDB_FLAG_INTERNAL_MASK
79 #define LDB_FLAG_INTERNAL_DISABLE_VALIDATION 0x10
81 /* disable any single value checking on this attribute */
82 #define LDB_FLAG_INTERNAL_DISABLE_SINGLE_VALUE_CHECK 0x20
84 /* attribute has failed access check and must not be exposed */
85 #define LDB_FLAG_INTERNAL_INACCESSIBLE_ATTRIBUTE 0x40
87 /* force single value checking on this attribute */
88 #define LDB_FLAG_INTERNAL_FORCE_SINGLE_VALUE_CHECK 0x80
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.
97 #define LDB_FLAG_INTERNAL_FORCE_UNIQUE_INDEX 0x100
100 * indicates that this element's values are shared with another element (for
101 * example, in a shallow copy of an ldb_message) and should not be freed
103 #define LDB_FLAG_INTERNAL_SHARED_VALUES 0x200
106 * this attribute has been access checked. We know the user has the right to
107 * view it. Used internally in Samba aclread module.
109 #define LDB_FLAG_INTERNAL_ACCESS_CHECKED 0x400
111 /* an extended match rule that always fails to match */
112 #define SAMBA_LDAP_MATCH_ALWAYS_FALSE "1.3.6.1.4.1.7165.4.5.1"
114 /* The const char * const * pointer to a list of secret (password)
115 * attributes, not to be printed in trace messages */
116 #define LDB_SECRET_ATTRIBUTE_LIST_OPAQUE "LDB_SECRET_ATTRIBUTE_LIST"
119 * The scheme to be used for referral entries, i.e. ldap or ldaps
121 #define LDAP_REFERRAL_SCHEME_OPAQUE "LDAP_REFERRAL_SCHEME"
124 these function pointers define the operations that a ldb module can intercept
126 struct ldb_module_ops
{
128 int (*init_context
) (struct ldb_module
*);
129 int (*search
)(struct ldb_module
*, struct ldb_request
*); /* search */
130 int (*add
)(struct ldb_module
*, struct ldb_request
*); /* add */
131 int (*modify
)(struct ldb_module
*, struct ldb_request
*); /* modify */
132 int (*del
)(struct ldb_module
*, struct ldb_request
*); /* delete */
133 int (*rename
)(struct ldb_module
*, struct ldb_request
*); /* rename */
134 int (*request
)(struct ldb_module
*, struct ldb_request
*); /* match any other operation */
135 int (*extended
)(struct ldb_module
*, struct ldb_request
*); /* extended operations */
136 int (*start_transaction
)(struct ldb_module
*);
137 int (*prepare_commit
)(struct ldb_module
*);
138 int (*end_transaction
)(struct ldb_module
*);
139 int (*del_transaction
)(struct ldb_module
*);
140 int (*sequence_number
)(struct ldb_module
*, struct ldb_request
*);
141 int (*read_lock
)(struct ldb_module
*);
142 int (*read_unlock
)(struct ldb_module
*);
147 /* The following definitions come from lib/ldb/common/ldb_debug.c */
148 void ldb_debug(struct ldb_context
*ldb
, enum ldb_debug_level level
, const char *fmt
, ...) PRINTF_ATTRIBUTE(3, 4);
149 void ldb_debug_set(struct ldb_context
*ldb
, enum ldb_debug_level level
,
150 const char *fmt
, ...) PRINTF_ATTRIBUTE(3, 4);
151 void ldb_debug_add(struct ldb_context
*ldb
, const char *fmt
, ...) PRINTF_ATTRIBUTE(2, 3);
152 void ldb_debug_end(struct ldb_context
*ldb
, enum ldb_debug_level level
);
153 void ldb_vdebug(struct ldb_context
*ldb
, enum ldb_debug_level level
, const char *fmt
, va_list ap
) PRINTF_ATTRIBUTE(3, 0);
155 #define ldb_error(ldb, ecode, reason) ldb_error_at(ldb, ecode, reason, __FILE__, __LINE__)
156 #define ldb_module_error(module, ecode, reason) ldb_error_at(ldb_module_get_ctx(module), ecode, reason, __FILE__, __LINE__)
158 #define ldb_oom(ldb) ldb_error(ldb, LDB_ERR_OPERATIONS_ERROR, "ldb out of memory")
159 #define ldb_module_oom(module) ldb_oom(ldb_module_get_ctx(module))
160 #define ldb_operr(ldb) ldb_error(ldb, LDB_ERR_OPERATIONS_ERROR, "operations error")
161 #define ldb_module_operr(module) ldb_error(ldb_module_get_ctx(module), LDB_ERR_OPERATIONS_ERROR, "operations error")
163 /* The following definitions come from lib/ldb/common/ldb.c */
165 void ldb_request_set_state(struct ldb_request
*req
, int state
);
166 int ldb_request_get_status(struct ldb_request
*req
);
168 unsigned int ldb_get_create_perms(struct ldb_context
*ldb
);
170 const struct ldb_schema_syntax
*ldb_standard_syntax_by_name(struct ldb_context
*ldb
,
173 /* The following definitions come from lib/ldb/common/ldb_attributes.c */
175 int ldb_schema_attribute_add_with_syntax(struct ldb_context
*ldb
,
178 const struct ldb_schema_syntax
*syntax
);
179 int ldb_schema_attribute_add(struct ldb_context
*ldb
,
183 void ldb_schema_attribute_remove(struct ldb_context
*ldb
, const char *name
);
185 /* we allow external code to override the name -> schema_attribute function */
186 typedef const struct ldb_schema_attribute
*(*ldb_attribute_handler_override_fn_t
)(struct ldb_context
*, void *, const char *);
189 Allow the caller to define a callback for the attribute handler
191 \param ldb The ldb context
192 \param override The callback to be used for attribute lookups
193 \param private_data Private data for the callback
196 void ldb_schema_attribute_set_override_handler(struct ldb_context
*ldb
,
197 ldb_attribute_handler_override_fn_t override
,
201 Allow the caller to define that the callback for the attribute handler
202 also overrides the index list
204 \param ldb The ldb context
205 \param one_level_indexes Indicates that the index for SCOPE_ONELEVEL
206 should also be maintained
209 void ldb_schema_set_override_indexlist(struct ldb_context
*ldb
,
210 bool one_level_indexes
);
214 \param ldb The ldb context
215 \param GUID_index_attribute The globally attribute (eg objectGUID)
217 \param GUID_index_attribute The DN component matching the
218 globally attribute on each entry (eg GUID)
220 The caller must ensure the supplied strings do not go out of
221 scope (they are typically constant memory).
224 void ldb_schema_set_override_GUID_index(struct ldb_context
*ldb
,
225 const char *GUID_index_attribute
,
226 const char *GUID_index_dn_component
);
228 /* A useful function to build comparison functions with */
229 int ldb_any_comparison(struct ldb_context
*ldb
, void *mem_ctx
,
230 ldb_attr_handler_t canonicalise_fn
,
231 const struct ldb_val
*v1
,
232 const struct ldb_val
*v2
);
234 /* The following definitions come from lib/ldb/common/ldb_controls.c */
235 int ldb_save_controls(struct ldb_control
*exclude
, struct ldb_request
*req
, struct ldb_control
***saver
);
236 /* Returns a list of controls, except the one specified. Included
237 * controls become a child of returned list if they were children of
239 struct ldb_control
**ldb_controls_except_specified(struct ldb_control
**controls_in
,
241 struct ldb_control
*exclude
);
242 int ldb_check_critical_controls(struct ldb_control
**controls
);
244 /* The following definitions come from lib/ldb/common/ldb_ldif.c */
245 int ldb_should_b64_encode(struct ldb_context
*ldb
, const struct ldb_val
*val
);
247 /* The following definitions come from lib/ldb/common/ldb_match.c */
248 int ldb_match_msg(struct ldb_context
*ldb
,
249 const struct ldb_message
*msg
,
250 const struct ldb_parse_tree
*tree
,
252 enum ldb_scope scope
);
254 int ldb_match_msg_error(struct ldb_context
*ldb
,
255 const struct ldb_message
*msg
,
256 const struct ldb_parse_tree
*tree
,
258 enum ldb_scope scope
,
261 int ldb_match_msg_objectclass(const struct ldb_message
*msg
,
262 const char *objectclass
);
264 int ldb_register_extended_match_rules(struct ldb_context
*ldb
);
266 /* The following definitions come from lib/ldb/common/ldb_modules.c */
268 struct ldb_module
*ldb_module_new(TALLOC_CTX
*memctx
,
269 struct ldb_context
*ldb
,
270 const char *module_name
,
271 const struct ldb_module_ops
*ops
);
273 const char * ldb_module_get_name(struct ldb_module
*module
);
274 struct ldb_context
*ldb_module_get_ctx(struct ldb_module
*module
);
275 void *ldb_module_get_private(struct ldb_module
*module
);
276 void ldb_module_set_private(struct ldb_module
*module
, void *private_data
);
277 const struct ldb_module_ops
*ldb_module_get_ops(struct ldb_module
*module
);
279 int ldb_next_request(struct ldb_module
*module
, struct ldb_request
*request
);
280 int ldb_next_start_trans(struct ldb_module
*module
);
281 int ldb_next_end_trans(struct ldb_module
*module
);
282 int ldb_next_del_trans(struct ldb_module
*module
);
283 int ldb_next_prepare_commit(struct ldb_module
*module
);
284 int ldb_next_init(struct ldb_module
*module
);
285 int ldb_next_read_lock(struct ldb_module
*module
);
286 int ldb_next_read_unlock(struct ldb_module
*module
);
288 void ldb_set_errstring(struct ldb_context
*ldb
, const char *err_string
);
289 void ldb_asprintf_errstring(struct ldb_context
*ldb
, const char *format
, ...) PRINTF_ATTRIBUTE(2,3);
290 void ldb_reset_err_string(struct ldb_context
*ldb
);
291 int ldb_error_at(struct ldb_context
*ldb
, int ecode
, const char *reason
, const char *file
, int line
);
293 const char *ldb_default_modules_dir(void);
295 int ldb_register_module(const struct ldb_module_ops
*);
297 typedef int (*ldb_connect_fn
)(struct ldb_context
*ldb
, const char *url
,
298 unsigned int flags
, const char *options
[],
299 struct ldb_module
**module
);
302 Require that LDB use a private event context for each request
304 A private event context may need to be created to avoid nested event
305 loops during ldb_tdb with the locks held. This indicates that a
306 backend is in use that requires this to hold locks safely.
308 \param handle The ldb handle to set the flag on
310 void ldb_set_require_private_event_context(struct ldb_context
*ldb
);
312 struct ldb_backend_ops
{
314 ldb_connect_fn connect_fn
;
317 const char *ldb_default_modules_dir(void);
319 int ldb_register_backend(const char *url_prefix
, ldb_connect_fn
, bool);
321 struct ldb_handle
*ldb_handle_new(TALLOC_CTX
*mem_ctx
, struct ldb_context
*ldb
);
324 Obtains the private event context for the handle,
326 A private event context may have been created to avoid nested event
327 loops during ldb_tdb with the locks held. Otherwise return the
330 \param handle The ldb handle to obtain the event context for
331 \return the tevent event context for this handle (private or global)
333 struct tevent_context
*ldb_handle_get_event_context(struct ldb_handle
*handle
);
335 int ldb_module_send_entry(struct ldb_request
*req
,
336 struct ldb_message
*msg
,
337 struct ldb_control
**ctrls
);
339 int ldb_module_send_referral(struct ldb_request
*req
,
342 int ldb_module_done(struct ldb_request
*req
,
343 struct ldb_control
**ctrls
,
344 struct ldb_extended
*response
,
347 int ldb_mod_register_control(struct ldb_module
*module
, const char *oid
);
349 void ldb_set_default_dns(struct ldb_context
*ldb
);
351 Add a ldb_control to a ldb_reply
353 \param ares the reply struct where to add the control
354 \param oid the object identifier of the control as string
355 \param critical whether the control should be critical or not
356 \param data a talloc pointer to the control specific data
358 \return result code (LDB_SUCCESS on success, or a failure code)
360 int ldb_reply_add_control(struct ldb_reply
*ares
, const char *oid
, bool critical
, void *data
);
363 mark a request as untrusted.
365 This tells the rootdse module to remove unregistered controls
367 \param req the request to mark as untrusted
369 void ldb_req_mark_untrusted(struct ldb_request
*req
);
372 mark a request as trusted.
374 This tells the rootdse module to allow unregistered controls
376 \param req the request to mark as trusted
378 void ldb_req_mark_trusted(struct ldb_request
*req
);
381 return true is a request is untrusted
383 This indicates the request came across a trust boundary
384 for example over LDAP
386 \param req the request check
387 \return is req trusted
389 bool ldb_req_is_untrusted(struct ldb_request
*req
);
392 set custom flags. Those flags are set by applications using ldb,
393 they are application dependent and the same bit can have different
394 meaning in different application.
396 void ldb_req_set_custom_flags(struct ldb_request
*req
, uint32_t flags
);
399 get custom flags. Those flags are set by applications using ldb,
400 they are application dependent and the same bit can have different
401 meaning in different application.
403 uint32_t ldb_req_get_custom_flags(struct ldb_request
*req
);
405 /* load all modules from the given directory */
406 int ldb_modules_load(const char *modules_path
, const char *version
);
408 /* init functions prototype */
409 typedef int (*ldb_module_init_fn
)(const char *);
412 general ldb hook function
414 enum ldb_module_hook_type
{ LDB_MODULE_HOOK_CMDLINE_OPTIONS
= 1,
415 LDB_MODULE_HOOK_CMDLINE_PRECONNECT
= 2,
416 LDB_MODULE_HOOK_CMDLINE_POSTCONNECT
= 3 };
418 typedef int (*ldb_hook_fn
)(struct ldb_context
*, enum ldb_module_hook_type
);
421 register a ldb hook function
423 int ldb_register_hook(ldb_hook_fn hook_fn
);
426 call ldb hooks of a given type
428 int ldb_modules_hook(struct ldb_context
*ldb
, enum ldb_module_hook_type t
);
430 #define LDB_MODULE_CHECK_VERSION(version) do { \
431 if (strcmp(version, LDB_VERSION) != 0) { \
432 fprintf(stderr, "ldb: module version mismatch in %s : ldb_version=%s module_version=%s\n", \
433 __FILE__, version, LDB_VERSION); \
434 return LDB_ERR_UNAVAILABLE; \
439 return a string representation of the calling chain for the given
442 char *ldb_module_call_chain(struct ldb_request
*req
, TALLOC_CTX
*mem_ctx
);
445 return the next module in the chain
447 struct ldb_module
*ldb_module_next(struct ldb_module
*module
);
450 set the next module in the module chain
452 void ldb_module_set_next(struct ldb_module
*module
, struct ldb_module
*next
);
455 load a list of modules
457 int ldb_module_load_list(struct ldb_context
*ldb
, const char **module_list
,
458 struct ldb_module
*backend
, struct ldb_module
**out
);
461 get the popt_options pointer in the ldb structure. This allows a ldb
462 module to change the command line parsing
464 struct poptOption
**ldb_module_popt_options(struct ldb_context
*ldb
);
466 /* modules are called in inverse order on the stack.
467 Lets place them as an admin would think the right order is.
468 Modules order is important */
469 const char **ldb_modules_list_from_string(struct ldb_context
*ldb
, TALLOC_CTX
*mem_ctx
, const char *string
);
472 return the current ldb flags LDB_FLG_*
474 uint32_t ldb_module_flags(struct ldb_context
*ldb
);
476 int ldb_module_connect_backend(struct ldb_context
*ldb
,
478 const char *options
[],
479 struct ldb_module
**backend_module
);
482 initialise a chain of modules
484 int ldb_module_init_chain(struct ldb_context
*ldb
, struct ldb_module
*module
);
487 * prototype for the init function defined by dynamically loaded modules
489 int ldb_init_module(const char *version
);
491 /* replace the components of a DN with those from another DN, without
492 * touching the extended components
494 * return true if successful and false if not
495 * if false is returned the dn may be marked invalid
497 bool ldb_dn_replace_components(struct ldb_dn
*dn
, struct ldb_dn
*new_dn
);
499 /* Get the attribute (if any) associated with the top node of a parse tree. */
500 const char *ldb_parse_tree_get_attr(const struct ldb_parse_tree
*tree
);
503 walk a parse tree, calling the provided callback on each node
505 int ldb_parse_tree_walk(struct ldb_parse_tree
*tree
,
506 int (*callback
)(struct ldb_parse_tree
*tree
, void *),
507 void *private_context
);
509 /* compare two message elements with ordering - used by modify */
510 bool ldb_msg_element_equal_ordered(const struct ldb_message_element
*el1
,
511 const struct ldb_message_element
*el2
);
514 struct ldb_extended_match_rule
517 int (*callback
)(struct ldb_context
*, const char *oid
,
518 const struct ldb_message
*, const char *,
519 const struct ldb_val
*, bool *);
522 int ldb_register_extended_match_rule(struct ldb_context
*ldb
,
523 const struct ldb_extended_match_rule
*rule
);
525 void ldb_msg_element_mark_inaccessible(struct ldb_message_element
*el
);
526 bool ldb_msg_element_is_inaccessible(const struct ldb_message_element
*el
);
527 void ldb_msg_remove_inaccessible(struct ldb_message
*msg
);
529 typedef int (*ldb_redact_fn
)(struct ldb_module
*, struct ldb_request
*, struct ldb_message
*);
530 int ldb_register_redact_callback(struct ldb_context
*ldb
,
531 ldb_redact_fn redact_fn
,
532 struct ldb_module
*module
);
535 * these pack/unpack functions are exposed in the library for use by
536 * ldb tools like ldbdump and for use in tests,
537 * but are not part of the public API
539 int ldb_pack_data(struct ldb_context
*ldb
,
540 const struct ldb_message
*message
,
541 struct ldb_val
*data
,
542 uint32_t pack_format_version
);
544 * Unpack a ldb message from a linear buffer in ldb_val
546 int ldb_unpack_data(struct ldb_context
*ldb
,
547 const struct ldb_val
*data
,
548 struct ldb_message
*message
);
551 * filter the specified list of attributes from msg,
552 * adding requested attributes, and perhaps all for *,
553 * but not the DN to filtered_msg.
555 int ldb_filter_attrs(struct ldb_context
*ldb
,
556 const struct ldb_message
*msg
,
557 const char *const *attrs
,
558 struct ldb_message
*filtered_msg
);
561 * filter the specified list of attributes from msg,
562 * adding requested attributes, and perhaps all for *.
563 * Unlike ldb_filter_attrs(), the DN will not be added
566 int ldb_filter_attrs_in_place(struct ldb_message
*msg
,
567 const char *const *attrs
);
569 /* Have an unpacked ldb message take talloc ownership of its elements. */
570 int ldb_msg_elements_take_ownership(struct ldb_message
*msg
);
573 * Unpack a ldb message from a linear buffer in ldb_val
575 * If LDB_UNPACK_DATA_FLAG_NO_VALUES_ALLOC is specified, then values
576 * array are not allocated individually (for single-valued
577 * attributes), instead they point into a single buffer per message.
579 * Likewise if LDB_UNPACK_DATA_FLAG_NO_DN is specified, the DN is omitted.
581 * If LDB_UNPACK_DATA_FLAG_NO_ATTRS is specified, then no attributes
582 * are unpacked or returned.
585 int ldb_unpack_data_flags(struct ldb_context
*ldb
,
586 const struct ldb_val
*data
,
587 struct ldb_message
*message
,
590 int ldb_unpack_get_format(const struct ldb_val
*data
,
591 uint32_t *pack_format_version
);
593 /* currently unused (was NO_DATA_ALLOC) 0x0001 */
594 #define LDB_UNPACK_DATA_FLAG_NO_DN 0x0002
595 #define LDB_UNPACK_DATA_FLAG_NO_VALUES_ALLOC 0x0004
596 #define LDB_UNPACK_DATA_FLAG_NO_ATTRS 0x0008
597 #define LDB_UNPACK_DATA_FLAG_READ_LOCKED 0x0010
599 enum ldb_pack_format
{
601 /* Old packing format (based on a somewhat arbitrary date) */
602 LDB_PACKING_FORMAT_NODN
= 0x26011966,
604 /* In-use packing formats */
606 LDB_PACKING_FORMAT_V2
610 Forces a specific ldb handle to use the global event context.
612 This allows a nested event loop to operate, so any open
613 transaction also needs to be aborted.
615 Any events on this event context will be lost.
617 This is used in Samba when sending an IRPC to another part of the
618 same process instead of making a local DB modification.
620 \param handle The ldb handle to force to use the global context
623 void ldb_handle_use_global_event_context(struct ldb_handle
*handle
);
626 * Get the options passed to ldb_connect.
628 * This allows the options to be inspected by elements in the module stack
631 const char **ldb_options_get(struct ldb_context
*ldb
);