Line data Source code
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 : struct ldb_context;
39 : struct ldb_module;
40 :
41 : /**
42 : internal flag bits on message elements. Must be within LDB_FLAG_INTERNAL_MASK
43 : */
44 : #define LDB_FLAG_INTERNAL_DISABLE_VALIDATION 0x10
45 :
46 : /* disable any single value checking on this attribute */
47 : #define LDB_FLAG_INTERNAL_DISABLE_SINGLE_VALUE_CHECK 0x20
48 :
49 : /* attribute has failed access check and must not be exposed */
50 : #define LDB_FLAG_INTERNAL_INACCESSIBLE_ATTRIBUTE 0x40
51 :
52 : /* force single value checking on this attribute */
53 : #define LDB_FLAG_INTERNAL_FORCE_SINGLE_VALUE_CHECK 0x80
54 :
55 : /* an extended match rule that always fails to match */
56 : #define SAMBA_LDAP_MATCH_ALWAYS_FALSE "1.3.6.1.4.1.7165.4.5.1"
57 :
58 : /* The const char * const * pointer to a list of secret (password)
59 : * attributes, not to be printed in trace messages */
60 : #define LDB_SECRET_ATTRIBUTE_LIST_OPAQUE "LDB_SECRET_ATTRIBUTE_LIST"
61 :
62 : /*
63 : these function pointers define the operations that a ldb module can intercept
64 : */
65 : struct ldb_module_ops {
66 : const char *name;
67 : int (*init_context) (struct ldb_module *);
68 : int (*search)(struct ldb_module *, struct ldb_request *); /* search */
69 : int (*add)(struct ldb_module *, struct ldb_request *); /* add */
70 : int (*modify)(struct ldb_module *, struct ldb_request *); /* modify */
71 : int (*del)(struct ldb_module *, struct ldb_request *); /* delete */
72 : int (*rename)(struct ldb_module *, struct ldb_request *); /* rename */
73 : int (*request)(struct ldb_module *, struct ldb_request *); /* match any other operation */
74 : int (*extended)(struct ldb_module *, struct ldb_request *); /* extended operations */
75 : int (*start_transaction)(struct ldb_module *);
76 : int (*prepare_commit)(struct ldb_module *);
77 : int (*end_transaction)(struct ldb_module *);
78 : int (*del_transaction)(struct ldb_module *);
79 : int (*sequence_number)(struct ldb_module *, struct ldb_request *);
80 : void *private_data;
81 : };
82 :
83 :
84 : /* The following definitions come from lib/ldb/common/ldb_debug.c */
85 : void ldb_debug(struct ldb_context *ldb, enum ldb_debug_level level, const char *fmt, ...) PRINTF_ATTRIBUTE(3, 4);
86 : void ldb_debug_set(struct ldb_context *ldb, enum ldb_debug_level level,
87 : const char *fmt, ...) PRINTF_ATTRIBUTE(3, 4);
88 : void ldb_debug_add(struct ldb_context *ldb, const char *fmt, ...) PRINTF_ATTRIBUTE(2, 3);
89 : void ldb_debug_end(struct ldb_context *ldb, enum ldb_debug_level level);
90 : void ldb_vdebug(struct ldb_context *ldb, enum ldb_debug_level level, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3, 0);
91 :
92 : #define ldb_error(ldb, ecode, reason) ldb_error_at(ldb, ecode, reason, __FILE__, __LINE__)
93 : #define ldb_module_error(module, ecode, reason) ldb_error_at(ldb_module_get_ctx(module), ecode, reason, __FILE__, __LINE__)
94 :
95 : #define ldb_oom(ldb) ldb_error(ldb, LDB_ERR_OPERATIONS_ERROR, "ldb out of memory")
96 : #define ldb_module_oom(module) ldb_oom(ldb_module_get_ctx(module))
97 : #define ldb_operr(ldb) ldb_error(ldb, LDB_ERR_OPERATIONS_ERROR, "operations error")
98 : #define ldb_module_operr(module) ldb_error(ldb_module_get_ctx(module), LDB_ERR_OPERATIONS_ERROR, "operations error")
99 :
100 : /* The following definitions come from lib/ldb/common/ldb.c */
101 :
102 : void ldb_request_set_state(struct ldb_request *req, int state);
103 : int ldb_request_get_status(struct ldb_request *req);
104 :
105 : unsigned int ldb_get_create_perms(struct ldb_context *ldb);
106 :
107 : const struct ldb_schema_syntax *ldb_standard_syntax_by_name(struct ldb_context *ldb,
108 : const char *syntax);
109 :
110 : /* The following definitions come from lib/ldb/common/ldb_attributes.c */
111 :
112 : int ldb_schema_attribute_add_with_syntax(struct ldb_context *ldb,
113 : const char *name,
114 : unsigned flags,
115 : const struct ldb_schema_syntax *syntax);
116 : int ldb_schema_attribute_add(struct ldb_context *ldb,
117 : const char *name,
118 : unsigned flags,
119 : const char *syntax);
120 : void ldb_schema_attribute_remove(struct ldb_context *ldb, const char *name);
121 :
122 : /* we allow external code to override the name -> schema_attribute function */
123 : typedef const struct ldb_schema_attribute *(*ldb_attribute_handler_override_fn_t)(struct ldb_context *, void *, const char *);
124 :
125 : void ldb_schema_attribute_set_override_handler(struct ldb_context *ldb,
126 : ldb_attribute_handler_override_fn_t override,
127 : void *private_data);
128 :
129 : /* A useful function to build comparison functions with */
130 : int ldb_any_comparison(struct ldb_context *ldb, void *mem_ctx,
131 : ldb_attr_handler_t canonicalise_fn,
132 : const struct ldb_val *v1,
133 : const struct ldb_val *v2);
134 :
135 : /* The following definitions come from lib/ldb/common/ldb_controls.c */
136 : int ldb_save_controls(struct ldb_control *exclude, struct ldb_request *req, struct ldb_control ***saver);
137 : /* Returns a list of controls, except the one specified. Included
138 : * controls become a child of returned list if they were children of
139 : * controls_in */
140 : struct ldb_control **ldb_controls_except_specified(struct ldb_control **controls_in,
141 : TALLOC_CTX *mem_ctx,
142 : struct ldb_control *exclude);
143 : int ldb_check_critical_controls(struct ldb_control **controls);
144 :
145 : /* The following definitions come from lib/ldb/common/ldb_ldif.c */
146 : int ldb_should_b64_encode(struct ldb_context *ldb, const struct ldb_val *val);
147 :
148 : /* The following definitions come from lib/ldb/common/ldb_match.c */
149 : int ldb_match_msg(struct ldb_context *ldb,
150 : const struct ldb_message *msg,
151 : const struct ldb_parse_tree *tree,
152 : struct ldb_dn *base,
153 : enum ldb_scope scope);
154 :
155 : int ldb_match_msg_error(struct ldb_context *ldb,
156 : const struct ldb_message *msg,
157 : const struct ldb_parse_tree *tree,
158 : struct ldb_dn *base,
159 : enum ldb_scope scope,
160 : bool *matched);
161 :
162 : int ldb_match_msg_objectclass(const struct ldb_message *msg,
163 : const char *objectclass);
164 :
165 : int ldb_register_extended_match_rules(struct ldb_context *ldb);
166 :
167 : /* The following definitions come from lib/ldb/common/ldb_modules.c */
168 :
169 : struct ldb_module *ldb_module_new(TALLOC_CTX *memctx,
170 : struct ldb_context *ldb,
171 : const char *module_name,
172 : const struct ldb_module_ops *ops);
173 :
174 : const char * ldb_module_get_name(struct ldb_module *module);
175 : struct ldb_context *ldb_module_get_ctx(struct ldb_module *module);
176 : void *ldb_module_get_private(struct ldb_module *module);
177 : void ldb_module_set_private(struct ldb_module *module, void *private_data);
178 : const struct ldb_module_ops *ldb_module_get_ops(struct ldb_module *module);
179 :
180 : int ldb_next_request(struct ldb_module *module, struct ldb_request *request);
181 : int ldb_next_start_trans(struct ldb_module *module);
182 : int ldb_next_end_trans(struct ldb_module *module);
183 : int ldb_next_del_trans(struct ldb_module *module);
184 : int ldb_next_prepare_commit(struct ldb_module *module);
185 : int ldb_next_init(struct ldb_module *module);
186 :
187 : void ldb_set_errstring(struct ldb_context *ldb, const char *err_string);
188 : void ldb_asprintf_errstring(struct ldb_context *ldb, const char *format, ...) PRINTF_ATTRIBUTE(2,3);
189 : void ldb_reset_err_string(struct ldb_context *ldb);
190 : int ldb_error_at(struct ldb_context *ldb, int ecode, const char *reason, const char *file, int line);
191 :
192 : const char *ldb_default_modules_dir(void);
193 :
194 : int ldb_register_module(const struct ldb_module_ops *);
195 :
196 : typedef int (*ldb_connect_fn)(struct ldb_context *ldb, const char *url,
197 : unsigned int flags, const char *options[],
198 : struct ldb_module **module);
199 :
200 : struct ldb_backend_ops {
201 : const char *name;
202 : ldb_connect_fn connect_fn;
203 : };
204 :
205 : const char *ldb_default_modules_dir(void);
206 :
207 : int ldb_register_backend(const char *url_prefix, ldb_connect_fn, bool);
208 :
209 : struct ldb_handle *ldb_handle_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb);
210 :
211 : int ldb_module_send_entry(struct ldb_request *req,
212 : struct ldb_message *msg,
213 : struct ldb_control **ctrls);
214 :
215 : int ldb_module_send_referral(struct ldb_request *req,
216 : char *ref);
217 :
218 : int ldb_module_done(struct ldb_request *req,
219 : struct ldb_control **ctrls,
220 : struct ldb_extended *response,
221 : int error);
222 :
223 : int ldb_mod_register_control(struct ldb_module *module, const char *oid);
224 :
225 : void ldb_set_default_dns(struct ldb_context *ldb);
226 : /**
227 : Add a ldb_control to a ldb_reply
228 :
229 : \param ares the reply struct where to add the control
230 : \param oid the object identifier of the control as string
231 : \param critical whether the control should be critical or not
232 : \param data a talloc pointer to the control specific data
233 :
234 : \return result code (LDB_SUCCESS on success, or a failure code)
235 : */
236 : int ldb_reply_add_control(struct ldb_reply *ares, const char *oid, bool critical, void *data);
237 :
238 : /**
239 : mark a request as untrusted. This tells the rootdse module to remove
240 : unregistered controls
241 : */
242 : void ldb_req_mark_untrusted(struct ldb_request *req);
243 :
244 : /**
245 : mark a request as trusted.
246 : */
247 : void ldb_req_mark_trusted(struct ldb_request *req);
248 :
249 : /**
250 : return true is a request is untrusted
251 : */
252 : bool ldb_req_is_untrusted(struct ldb_request *req);
253 :
254 : /**
255 : set custom flags. Those flags are set by applications using ldb,
256 : they are application dependent and the same bit can have different
257 : meaning in different application.
258 : */
259 : void ldb_req_set_custom_flags(struct ldb_request *req, uint32_t flags);
260 :
261 : /**
262 : get custom flags. Those flags are set by applications using ldb,
263 : they are application dependent and the same bit can have different
264 : meaning in different application.
265 : */
266 : uint32_t ldb_req_get_custom_flags(struct ldb_request *req);
267 :
268 : /* load all modules from the given directory */
269 : int ldb_modules_load(const char *modules_path, const char *version);
270 :
271 : /* init functions prototype */
272 : typedef int (*ldb_module_init_fn)(const char *);
273 :
274 : /*
275 : general ldb hook function
276 : */
277 : enum ldb_module_hook_type { LDB_MODULE_HOOK_CMDLINE_OPTIONS = 1,
278 : LDB_MODULE_HOOK_CMDLINE_PRECONNECT = 2,
279 : LDB_MODULE_HOOK_CMDLINE_POSTCONNECT = 3 };
280 :
281 : typedef int (*ldb_hook_fn)(struct ldb_context *, enum ldb_module_hook_type );
282 :
283 : /*
284 : register a ldb hook function
285 : */
286 : int ldb_register_hook(ldb_hook_fn hook_fn);
287 :
288 : /*
289 : call ldb hooks of a given type
290 : */
291 : int ldb_modules_hook(struct ldb_context *ldb, enum ldb_module_hook_type t);
292 :
293 : #define LDB_MODULE_CHECK_VERSION(version) do { \
294 : if (strcmp(version, LDB_VERSION) != 0) { \
295 : fprintf(stderr, "ldb: module version mismatch in %s : ldb_version=%s module_version=%s\n", \
296 : __FILE__, version, LDB_VERSION); \
297 : return LDB_ERR_UNAVAILABLE; \
298 : }} while (0)
299 :
300 :
301 : /*
302 : return a string representation of the calling chain for the given
303 : ldb request
304 : */
305 : char *ldb_module_call_chain(struct ldb_request *req, TALLOC_CTX *mem_ctx);
306 :
307 : /*
308 : return the next module in the chain
309 : */
310 : struct ldb_module *ldb_module_next(struct ldb_module *module);
311 :
312 : /*
313 : set the next module in the module chain
314 : */
315 : void ldb_module_set_next(struct ldb_module *module, struct ldb_module *next);
316 :
317 : /*
318 : load a list of modules
319 : */
320 : int ldb_module_load_list(struct ldb_context *ldb, const char **module_list,
321 : struct ldb_module *backend, struct ldb_module **out);
322 :
323 : /*
324 : get the popt_options pointer in the ldb structure. This allows a ldb
325 : module to change the command line parsing
326 : */
327 : struct poptOption **ldb_module_popt_options(struct ldb_context *ldb);
328 :
329 : /* modules are called in inverse order on the stack.
330 : Lets place them as an admin would think the right order is.
331 : Modules order is important */
332 : const char **ldb_modules_list_from_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *string);
333 :
334 : /*
335 : return the current ldb flags LDB_FLG_*
336 : */
337 : uint32_t ldb_module_flags(struct ldb_context *ldb);
338 :
339 : int ldb_module_connect_backend(struct ldb_context *ldb,
340 : const char *url,
341 : const char *options[],
342 : struct ldb_module **backend_module);
343 :
344 : /*
345 : initialise a chain of modules
346 : */
347 : int ldb_module_init_chain(struct ldb_context *ldb, struct ldb_module *module);
348 :
349 : /*
350 : * prototype for the init function defined by dynamically loaded modules
351 : */
352 22 : int ldb_init_module(const char *version);
353 :
354 : /* replace the components of a DN with those from another DN, without
355 : * touching the extended components
356 : *
357 : * return true if successful and false if not
358 : * if false is returned the dn may be marked invalid
359 : */
360 : bool ldb_dn_replace_components(struct ldb_dn *dn, struct ldb_dn *new_dn);
361 :
362 : /*
363 : walk a parse tree, calling the provided callback on each node
364 : */
365 : int ldb_parse_tree_walk(struct ldb_parse_tree *tree,
366 : int (*callback)(struct ldb_parse_tree *tree, void *),
367 : void *private_context);
368 :
369 : /* compare two message elements with ordering - used by modify */
370 : bool ldb_msg_element_equal_ordered(const struct ldb_message_element *el1,
371 : const struct ldb_message_element *el2);
372 :
373 :
374 : struct ldb_extended_match_rule
375 : {
376 : const char *oid;
377 : int (*callback)(struct ldb_context *, const char *oid,
378 : const struct ldb_message *, const char *,
379 : const struct ldb_val *, bool *);
380 : };
381 :
382 : int ldb_register_extended_match_rule(struct ldb_context *ldb,
383 : const struct ldb_extended_match_rule *rule);
384 :
385 : #endif
|
