4 Copyright (C) Andrew Tridgell 2004
5 Copyright (C) Simo Sorce 2005-2006
7 ** NOTE! The following LGPL license applies to the ldb
8 ** library. This does NOT imply that all of Samba is released
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 2 of the License, or (at your option) any later version.
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.
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
29 * Component: ldb core API
31 * Description: core API routines interfacing to ldb backends
33 * Author: Andrew Tridgell
37 #include "ldb/include/includes.h"
40 initialise a ldb context
41 The mem_ctx is optional
43 struct ldb_context
*ldb_init(void *mem_ctx
)
45 struct ldb_context
*ldb
= talloc_zero(mem_ctx
, struct ldb_context
);
48 ret
= ldb_setup_wellknown_attributes(ldb
);
54 ldb_set_utf8_default(ldb
);
59 static struct ldb_backend
{
61 ldb_connect_fn connect_fn
;
62 struct ldb_backend
*prev
, *next
;
63 } *ldb_backends
= NULL
;
65 register a new ldb backend
67 int ldb_register_backend(const char *url_prefix
, ldb_connect_fn connectfn
)
69 struct ldb_backend
*backend
= talloc(talloc_autofree_context(), struct ldb_backend
);
71 /* Maybe check for duplicity here later on? */
73 backend
->name
= talloc_strdup(backend
, url_prefix
);
74 backend
->connect_fn
= connectfn
;
75 DLIST_ADD(ldb_backends
, backend
);
80 static ldb_connect_fn
ldb_find_backend(const char *url
)
82 struct ldb_backend
*backend
;
84 for (backend
= ldb_backends
; backend
; backend
= backend
->next
) {
85 if (strncmp(backend
->name
, url
, strlen(backend
->name
)) == 0) {
86 return backend
->connect_fn
;
94 Return the ldb module form of a database. The URL can either be one of the following forms
98 flags is made up of LDB_FLG_*
100 the options are passed uninterpreted to the backend, and are
103 This allows modules to get at only the backend module, for example where a module
104 may wish to direct certain requests at a particular backend.
106 int ldb_connect_backend(struct ldb_context
*ldb
, const char *url
, const char *options
[],
107 struct ldb_module
**backend_module
)
113 if (strchr(url
, ':') != NULL
) {
114 backend
= talloc_strndup(ldb
, url
, strchr(url
, ':')-url
);
117 backend
= talloc_strdup(ldb
, "tdb");
120 fn
= ldb_find_backend(backend
);
123 if (ldb_try_load_dso(ldb
, backend
) == 0) {
124 fn
= ldb_find_backend(backend
);
128 talloc_free(backend
);
131 ldb_debug(ldb
, LDB_DEBUG_FATAL
, "Unable to find backend for '%s'\n", url
);
132 return LDB_ERR_OTHER
;
135 ret
= fn(ldb
, url
, ldb
->flags
, options
, backend_module
);
137 if (ret
!= LDB_SUCCESS
) {
138 ldb_debug(ldb
, LDB_DEBUG_ERROR
, "Failed to connect to '%s'\n", url
);
145 try to autodetect a basedn if none specified. This fixes one of my
146 pet hates about ldapsearch, which is that you have to get a long,
147 complex basedn right to make any use of it.
149 static const struct ldb_dn
*ldb_set_default_basedn(struct ldb_context
*ldb
)
153 static const char *attrs
[] = { "defaultNamingContext", NULL
};
154 struct ldb_result
*res
;
155 struct ldb_dn
*basedn
=NULL
;
157 basedn
= ldb_get_opaque(ldb
, "default_baseDN");
162 tmp_ctx
= talloc_new(ldb
);
163 ret
= ldb_search(ldb
, ldb_dn_new(tmp_ctx
), LDB_SCOPE_BASE
,
164 "(objectClass=*)", attrs
, &res
);
165 if (ret
== LDB_SUCCESS
) {
166 if (res
->count
== 1) {
167 basedn
= ldb_msg_find_attr_as_dn(ldb
, res
->msgs
[0], "defaultNamingContext");
168 ldb_set_opaque(ldb
, "default_baseDN", basedn
);
173 talloc_free(tmp_ctx
);
177 const struct ldb_dn
*ldb_get_default_basedn(struct ldb_context
*ldb
)
179 return ldb_get_opaque(ldb
, "default_baseDN");
183 connect to a database. The URL can either be one of the following forms
187 flags is made up of LDB_FLG_*
189 the options are passed uninterpreted to the backend, and are
192 int ldb_connect(struct ldb_context
*ldb
, const char *url
, unsigned int flags
, const char *options
[])
198 ret
= ldb_connect_backend(ldb
, url
, options
, &ldb
->modules
);
199 if (ret
!= LDB_SUCCESS
) {
203 if (ldb_load_modules(ldb
, options
) != LDB_SUCCESS
) {
204 ldb_debug(ldb
, LDB_DEBUG_FATAL
, "Unable to load modules for '%s'\n", url
);
205 return LDB_ERR_OTHER
;
208 /* TODO: get timeout from options if available there */
209 ldb
->default_timeout
= 300; /* set default to 5 minutes */
211 /* set the default base dn */
212 ldb_set_default_basedn(ldb
);
217 void ldb_set_errstring(struct ldb_context
*ldb
, const char *err_string
)
219 if (ldb
->err_string
) {
220 talloc_free(ldb
->err_string
);
222 ldb
->err_string
= talloc_strdup(ldb
, err_string
);
225 void ldb_asprintf_errstring(struct ldb_context
*ldb
, const char *format
, ...)
229 if (ldb
->err_string
) {
230 talloc_free(ldb
->err_string
);
233 va_start(ap
, format
);
234 ldb
->err_string
= talloc_vasprintf(ldb
, format
, ap
);
238 void ldb_reset_err_string(struct ldb_context
*ldb
)
240 if (ldb
->err_string
) {
241 talloc_free(ldb
->err_string
);
242 ldb
->err_string
= NULL
;
246 #define FIRST_OP(ldb, op) do { \
247 module = ldb->modules; \
248 while (module && module->ops->op == NULL) module = module->next; \
249 if (module == NULL) { \
250 ldb_asprintf_errstring(ldb, "unable to find module or backend to handle operation: " #op); \
251 return LDB_ERR_OPERATIONS_ERROR; \
258 static int ldb_transaction_start_internal(struct ldb_context
*ldb
)
260 struct ldb_module
*module
;
262 FIRST_OP(ldb
, start_transaction
);
264 ldb_reset_err_string(ldb
);
266 status
= module
->ops
->start_transaction(module
);
267 if (status
!= LDB_SUCCESS
) {
268 if (ldb
->err_string
== NULL
) {
269 /* no error string was setup by the backend */
270 ldb_asprintf_errstring(ldb
,
271 "ldb transaction start: %s (%d)",
272 ldb_strerror(status
),
282 static int ldb_transaction_commit_internal(struct ldb_context
*ldb
)
284 struct ldb_module
*module
;
286 FIRST_OP(ldb
, end_transaction
);
288 ldb_reset_err_string(ldb
);
290 status
= module
->ops
->end_transaction(module
);
291 if (status
!= LDB_SUCCESS
) {
292 if (ldb
->err_string
== NULL
) {
293 /* no error string was setup by the backend */
294 ldb_asprintf_errstring(ldb
,
295 "ldb transaction commit: %s (%d)",
296 ldb_strerror(status
),
306 static int ldb_transaction_cancel_internal(struct ldb_context
*ldb
)
308 struct ldb_module
*module
;
310 FIRST_OP(ldb
, del_transaction
);
312 status
= module
->ops
->del_transaction(module
);
313 if (status
!= LDB_SUCCESS
) {
314 if (ldb
->err_string
== NULL
) {
315 /* no error string was setup by the backend */
316 ldb_asprintf_errstring(ldb
,
317 "ldb transaction cancel: %s (%d)",
318 ldb_strerror(status
),
325 int ldb_transaction_start(struct ldb_context
*ldb
)
327 /* disable autotransactions */
328 ldb
->transaction_active
++;
330 return ldb_transaction_start_internal(ldb
);
333 int ldb_transaction_commit(struct ldb_context
*ldb
)
335 /* renable autotransactions (when we reach 0) */
336 if (ldb
->transaction_active
> 0)
337 ldb
->transaction_active
--;
339 return ldb_transaction_commit_internal(ldb
);
342 int ldb_transaction_cancel(struct ldb_context
*ldb
)
344 /* renable autotransactions (when we reach 0) */
345 if (ldb
->transaction_active
> 0)
346 ldb
->transaction_active
--;
348 return ldb_transaction_cancel_internal(ldb
);
351 static int ldb_autotransaction_start(struct ldb_context
*ldb
)
353 /* explicit transaction active, ignore autotransaction request */
354 if (ldb
->transaction_active
)
357 return ldb_transaction_start_internal(ldb
);
360 static int ldb_autotransaction_commit(struct ldb_context
*ldb
)
362 /* explicit transaction active, ignore autotransaction request */
363 if (ldb
->transaction_active
)
366 return ldb_transaction_commit_internal(ldb
);
369 static int ldb_autotransaction_cancel(struct ldb_context
*ldb
)
371 /* explicit transaction active, ignore autotransaction request */
372 if (ldb
->transaction_active
)
375 return ldb_transaction_cancel_internal(ldb
);
378 /* autostarts a transacion if none active */
379 static int ldb_autotransaction_request(struct ldb_context
*ldb
, struct ldb_request
*req
)
383 ret
= ldb_autotransaction_start(ldb
);
384 if (ret
!= LDB_SUCCESS
) {
388 ret
= ldb_request(ldb
, req
);
389 if (ret
== LDB_SUCCESS
) {
390 ret
= ldb_wait(req
->handle
, LDB_WAIT_ALL
);
393 if (ret
== LDB_SUCCESS
) {
394 return ldb_autotransaction_commit(ldb
);
396 ldb_autotransaction_cancel(ldb
);
398 if (ldb
->err_string
== NULL
) {
399 /* no error string was setup by the backend */
400 ldb_asprintf_errstring(ldb
, "%s (%d)", ldb_strerror(ret
), ret
);
406 int ldb_wait(struct ldb_handle
*handle
, enum ldb_wait_type type
)
412 return handle
->module
->ops
->wait(handle
, type
);
415 /* set the specified timeout or, if timeout is 0 set the default timeout */
416 /* timeout == -1 means no timeout */
417 int ldb_set_timeout(struct ldb_context
*ldb
, struct ldb_request
*req
, int timeout
)
419 if (req
== NULL
) return LDB_ERR_OPERATIONS_ERROR
;
422 req
->timeout
= timeout
;
424 req
->timeout
= ldb
->default_timeout
;
426 req
->starttime
= time(NULL
);
431 /* calculates the new timeout based on the previous starttime and timeout */
432 int ldb_set_timeout_from_prev_req(struct ldb_context
*ldb
, struct ldb_request
*oldreq
, struct ldb_request
*newreq
)
436 if (newreq
== NULL
) return LDB_ERR_OPERATIONS_ERROR
;
441 return ldb_set_timeout(ldb
, newreq
, 0);
443 if ((now
- oldreq
->starttime
) > oldreq
->timeout
) {
444 return LDB_ERR_TIME_LIMIT_EXCEEDED
;
446 newreq
->starttime
= oldreq
->starttime
;
447 newreq
->timeout
= oldreq
->timeout
- (now
- oldreq
->starttime
);
454 NOTE: the request must be a talloc context.
455 returns LDB_ERR_* on errors.
457 int ldb_request(struct ldb_context
*ldb
, struct ldb_request
*req
)
459 struct ldb_module
*module
;
462 ldb_reset_err_string(ldb
);
464 /* call the first module in the chain */
465 switch (req
->operation
) {
467 FIRST_OP(ldb
, search
);
468 ret
= module
->ops
->search(module
, req
);
472 ret
= module
->ops
->add(module
, req
);
475 FIRST_OP(ldb
, modify
);
476 ret
= module
->ops
->modify(module
, req
);
480 ret
= module
->ops
->del(module
, req
);
483 FIRST_OP(ldb
, rename
);
484 ret
= module
->ops
->rename(module
, req
);
486 case LDB_SEQUENCE_NUMBER
:
487 FIRST_OP(ldb
, sequence_number
);
488 ret
= module
->ops
->sequence_number(module
, req
);
491 FIRST_OP(ldb
, request
);
492 ret
= module
->ops
->request(module
, req
);
500 search the database given a LDAP-like search expression
502 returns an LDB error code
504 Use talloc_free to free the ldb_message returned in 'res', if successful
507 static int ldb_search_callback(struct ldb_context
*ldb
, void *context
, struct ldb_reply
*ares
)
509 struct ldb_result
*res
;
513 ldb_set_errstring(ldb
, "NULL Context in callback");
514 return LDB_ERR_OPERATIONS_ERROR
;
517 res
= *((struct ldb_result
**)context
);
523 if (ares
->type
== LDB_REPLY_ENTRY
) {
524 res
->msgs
= talloc_realloc(res
, res
->msgs
, struct ldb_message
*, res
->count
+ 2);
529 res
->msgs
[res
->count
+ 1] = NULL
;
531 res
->msgs
[res
->count
] = talloc_move(res
->msgs
, ares
->message
);
535 if (ares
->type
== LDB_REPLY_REFERRAL
) {
537 for (n
= 0; res
->refs
[n
]; n
++) /*noop*/ ;
542 res
->refs
= talloc_realloc(res
, res
->refs
, char *, n
+ 2);
547 res
->refs
[n
] = talloc_move(res
->refs
, ares
->referral
);
548 res
->refs
[n
+ 1] = NULL
;
551 talloc_steal(res
, ares
->controls
);
558 *((struct ldb_result
**)context
) = NULL
;
559 return LDB_ERR_OPERATIONS_ERROR
;
563 note that ldb_search() will automatically replace a NULL 'base' value with the
564 defaultNamingContext from the rootDSE if available.
566 int ldb_search(struct ldb_context
*ldb
,
567 const struct ldb_dn
*base
,
568 enum ldb_scope scope
,
569 const char *expression
,
570 const char * const *attrs
,
571 struct ldb_result
**res
)
573 struct ldb_request
*req
;
578 req
= talloc(ldb
, struct ldb_request
);
580 ldb_set_errstring(ldb
, "Out of Memory");
581 return LDB_ERR_OPERATIONS_ERROR
;
585 base
= ldb_get_default_basedn(ldb
);
588 req
->operation
= LDB_SEARCH
;
589 req
->op
.search
.base
= base
;
590 req
->op
.search
.scope
= scope
;
592 req
->op
.search
.tree
= ldb_parse_tree(req
, expression
);
593 if (req
->op
.search
.tree
== NULL
) {
594 ldb_set_errstring(ldb
, "Unable to parse search expression");
596 return LDB_ERR_OPERATIONS_ERROR
;
599 *res
= talloc_zero(ldb
, struct ldb_result
);
602 return LDB_ERR_OPERATIONS_ERROR
;
605 req
->op
.search
.attrs
= attrs
;
606 req
->controls
= NULL
;
608 req
->callback
= ldb_search_callback
;
609 ldb_set_timeout(ldb
, req
, 0); /* use default timeout */
611 ret
= ldb_request(ldb
, req
);
613 if (ret
== LDB_SUCCESS
) {
614 ret
= ldb_wait(req
->handle
, LDB_WAIT_ALL
);
617 if (ret
!= LDB_SUCCESS
) {
628 add a record to the database. Will fail if a record with the given class and key
631 int ldb_add(struct ldb_context
*ldb
,
632 const struct ldb_message
*message
)
634 struct ldb_request
*req
;
637 ret
= ldb_msg_sanity_check(ldb
, message
);
638 if (ret
!= LDB_SUCCESS
) {
642 req
= talloc(ldb
, struct ldb_request
);
644 ldb_set_errstring(ldb
, "Out of Memory");
645 return LDB_ERR_OPERATIONS_ERROR
;
648 req
->operation
= LDB_ADD
;
649 req
->op
.add
.message
= message
;
650 req
->controls
= NULL
;
652 req
->callback
= NULL
;
653 ldb_set_timeout(ldb
, req
, 0); /* use default timeout */
655 /* do request and autostart a transaction */
656 ret
= ldb_autotransaction_request(ldb
, req
);
663 modify the specified attributes of a record
665 int ldb_modify(struct ldb_context
*ldb
,
666 const struct ldb_message
*message
)
668 struct ldb_request
*req
;
671 ret
= ldb_msg_sanity_check(ldb
, message
);
672 if (ret
!= LDB_SUCCESS
) return ret
;
674 req
= talloc(ldb
, struct ldb_request
);
676 ldb_set_errstring(ldb
, "Out of Memory!");
677 return LDB_ERR_OPERATIONS_ERROR
;
680 req
->operation
= LDB_MODIFY
;
681 req
->op
.add
.message
= message
;
682 req
->controls
= NULL
;
684 req
->callback
= NULL
;
685 ldb_set_timeout(ldb
, req
, 0); /* use default timeout */
687 /* do request and autostart a transaction */
688 ret
= ldb_autotransaction_request(ldb
, req
);
696 delete a record from the database
698 int ldb_delete(struct ldb_context
*ldb
, const struct ldb_dn
*dn
)
700 struct ldb_request
*req
;
703 req
= talloc(ldb
, struct ldb_request
);
705 ldb_set_errstring(ldb
, "Out of Memory!");
706 return LDB_ERR_OPERATIONS_ERROR
;
709 req
->operation
= LDB_DELETE
;
711 req
->controls
= NULL
;
713 req
->callback
= NULL
;
714 ldb_set_timeout(ldb
, req
, 0); /* use default timeout */
716 /* do request and autostart a transaction */
717 ret
= ldb_autotransaction_request(ldb
, req
);
724 rename a record in the database
726 int ldb_rename(struct ldb_context
*ldb
, const struct ldb_dn
*olddn
, const struct ldb_dn
*newdn
)
728 struct ldb_request
*req
;
731 req
= talloc(ldb
, struct ldb_request
);
733 ldb_set_errstring(ldb
, "Out of Memory!");
734 return LDB_ERR_OPERATIONS_ERROR
;
737 req
->operation
= LDB_RENAME
;
738 req
->op
.rename
.olddn
= olddn
;
739 req
->op
.rename
.newdn
= newdn
;
740 req
->controls
= NULL
;
742 req
->callback
= NULL
;
743 ldb_set_timeout(ldb
, req
, 0); /* use default timeout */
745 /* do request and autostart a transaction */
746 ret
= ldb_autotransaction_request(ldb
, req
);
754 return the global sequence number
756 int ldb_sequence_number(struct ldb_context
*ldb
, uint64_t *seq_num
)
758 struct ldb_request
*req
;
761 req
= talloc(ldb
, struct ldb_request
);
763 ldb_set_errstring(ldb
, "Out of Memory");
764 return LDB_ERR_OPERATIONS_ERROR
;
767 req
->operation
= LDB_SEQUENCE_NUMBER
;
768 req
->controls
= NULL
;
770 req
->callback
= NULL
;
771 ldb_set_timeout(ldb
, req
, 0); /* use default timeout */
773 /* do request and autostart a transaction */
774 ret
= ldb_request(ldb
, req
);
776 if (ret
== LDB_SUCCESS
) {
777 *seq_num
= req
->op
.seq_num
.seq_num
;
787 return extended error information
789 const char *ldb_errstring(struct ldb_context
*ldb
)
791 if (ldb
->err_string
) {
792 return ldb
->err_string
;
799 return a string explaining what a ldb error constant meancs
801 const char *ldb_strerror(int ldb_err
)
806 case LDB_ERR_OPERATIONS_ERROR
:
807 return "Operations error";
808 case LDB_ERR_PROTOCOL_ERROR
:
809 return "Protocol error";
810 case LDB_ERR_TIME_LIMIT_EXCEEDED
:
811 return "Time limit exceeded";
812 case LDB_ERR_SIZE_LIMIT_EXCEEDED
:
813 return "Size limit exceeded";
814 case LDB_ERR_COMPARE_FALSE
:
815 return "Compare false";
816 case LDB_ERR_COMPARE_TRUE
:
817 return "Compare true";
818 case LDB_ERR_AUTH_METHOD_NOT_SUPPORTED
:
819 return "Auth method not supported";
820 case LDB_ERR_STRONG_AUTH_REQUIRED
:
821 return "Strong auth required";
823 case LDB_ERR_REFERRAL
:
824 return "Referral error";
825 case LDB_ERR_ADMIN_LIMIT_EXCEEDED
:
826 return "Admin limit exceeded";
827 case LDB_ERR_UNSUPPORTED_CRITICAL_EXTENSION
:
828 return "Unsupported critical extension";
829 case LDB_ERR_CONFIDENTIALITY_REQUIRED
:
830 return "Confidentiality required";
831 case LDB_ERR_SASL_BIND_IN_PROGRESS
:
832 return "SASL bind in progress";
833 case LDB_ERR_NO_SUCH_ATTRIBUTE
:
834 return "No such attribute";
835 case LDB_ERR_UNDEFINED_ATTRIBUTE_TYPE
:
836 return "Undefined attribute type";
837 case LDB_ERR_INAPPROPRIATE_MATCHING
:
838 return "Inappropriate matching";
839 case LDB_ERR_CONSTRAINT_VIOLATION
:
840 return "Constraint violation";
841 case LDB_ERR_ATTRIBUTE_OR_VALUE_EXISTS
:
842 return "Attribute or value exists";
843 case LDB_ERR_INVALID_ATTRIBUTE_SYNTAX
:
844 return "Invalid attribute syntax";
846 case LDB_ERR_NO_SUCH_OBJECT
:
847 return "No such object";
848 case LDB_ERR_ALIAS_PROBLEM
:
849 return "Alias problem";
850 case LDB_ERR_INVALID_DN_SYNTAX
:
851 return "Invalid DN syntax";
853 case LDB_ERR_ALIAS_DEREFERENCING_PROBLEM
:
854 return "Alias dereferencing problem";
856 case LDB_ERR_INAPPROPRIATE_AUTHENTICATION
:
857 return "Inappropriate authentication";
858 case LDB_ERR_INVALID_CREDENTIALS
:
859 return "Invalid credentials";
860 case LDB_ERR_INSUFFICIENT_ACCESS_RIGHTS
:
861 return "insufficient access rights";
864 case LDB_ERR_UNAVAILABLE
:
865 return "Unavailable";
866 case LDB_ERR_UNWILLING_TO_PERFORM
:
867 return "Unwilling to perform";
868 case LDB_ERR_LOOP_DETECT
:
869 return "Loop detect";
871 case LDB_ERR_NAMING_VIOLATION
:
872 return "Naming violation";
873 case LDB_ERR_OBJECT_CLASS_VIOLATION
:
874 return "Object class violation";
875 case LDB_ERR_NOT_ALLOWED_ON_NON_LEAF
:
876 return "Not allowed on non-leaf";
877 case LDB_ERR_NOT_ALLOWED_ON_RDN
:
878 return "Not allowed on RDN";
879 case LDB_ERR_ENTRY_ALREADY_EXISTS
:
880 return "Entry already exists";
881 case LDB_ERR_OBJECT_CLASS_MODS_PROHIBITED
:
882 return "Object class mods prohibited";
883 /* 70 RESERVED FOR CLDAP */
884 case LDB_ERR_AFFECTS_MULTIPLE_DSAS
:
885 return "Affects multiple DSAs";
891 return "Unknown error";
895 set backend specific opaque parameters
897 int ldb_set_opaque(struct ldb_context
*ldb
, const char *name
, void *value
)
899 struct ldb_opaque
*o
;
901 /* allow updating an existing value */
902 for (o
=ldb
->opaque
;o
;o
=o
->next
) {
903 if (strcmp(o
->name
, name
) == 0) {
909 o
= talloc(ldb
, struct ldb_opaque
);
912 return LDB_ERR_OTHER
;
914 o
->next
= ldb
->opaque
;
922 get a previously set opaque value
924 void *ldb_get_opaque(struct ldb_context
*ldb
, const char *name
)
926 struct ldb_opaque
*o
;
927 for (o
=ldb
->opaque
;o
;o
=o
->next
) {
928 if (strcmp(o
->name
, name
) == 0) {