1 /* 2 ldb database library 3 4 Copyright (C) Andrew Tridgell 2004 5 Copyright (C) Stefan Metzmacher 2004 6 Copyright (C) Simo Sorce 2005-2006 7 8 ** NOTE! The following LGPL license applies to the ldb 9 ** library. This does NOT imply that all of Samba is released 10 ** under the LGPL 11 12 This library is free software; you can redistribute it and/or 13 modify it under the terms of the GNU Lesser General Public 14 License as published by the Free Software Foundation; either 15 version 3 of the License, or (at your option) any later version. 16 17 This library is distributed in the hope that it will be useful, 18 but WITHOUT ANY WARRANTY; without even the implied warranty of 19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 20 Lesser General Public License for more details. 21 22 You should have received a copy of the GNU Lesser General Public 23 License along with this library; if not, see <http://www.gnu.org/licenses/>. 24 */ 25 26 /* 27 * Name: ldb 28 * 29 * Component: ldb header 30 * 31 * Description: defines for base ldb API 32 * 33 * Author: Andrew Tridgell 34 * Author: Stefan Metzmacher 35 */ 36 37 /** 38 \file ldb.h Samba's ldb database 39 40 This header file provides the main API for ldb. 41 */ 42 43 #ifndef _LDB_H_ 44 45 /*! \cond DOXYGEN_IGNORE */ 46 #define _LDB_H_ 1 47 /*! \endcond */ 48 49 #include <stdbool.h> 50 #include <talloc.h> 51 #include <tevent.h> 52 #include <ldb_version.h> 53 #include <ldb_errors.h> 54 55 /* 56 major restrictions as compared to normal LDAP: 57 58 - each record must have a unique key field 59 - the key must be representable as a NULL terminated C string and may not 60 contain a comma or braces 61 62 major restrictions as compared to tdb: 63 64 - no explicit locking calls, but we have transactions when using ldb_tdb 65 66 */ 67 68 #ifndef ldb_val 69 /** 70 Result value 71 72 An individual lump of data in a result comes in this format. The 73 pointer will usually be to a UTF-8 string if the application is 74 sensible, but it can be to anything you like, including binary data 75 blobs of arbitrary size. 76 77 \note the data is null (0x00) terminated, but the length does not 78 include the terminator. 79 */ 80 struct ldb_val { 81 uint8_t *data; /*!< result data */ 82 size_t length; /*!< length of data */ 83 }; 84 #endif 85 86 /*! \cond DOXYGEN_IGNORE */ 87 #ifndef PRINTF_ATTRIBUTE 88 #define PRINTF_ATTRIBUTE(a,b) 89 #endif 90 91 #ifndef _DEPRECATED_ 92 #if (__GNUC__ >= 3) && (__GNUC_MINOR__ >= 1 ) 93 #define _DEPRECATED_ __attribute__ ((deprecated)) 94 #else 95 #define _DEPRECATED_ 96 #endif 97 #endif 98 /*! \endcond */ 99 100 /* opaque ldb_dn structures, see ldb_dn.c for internals */ 101 struct ldb_dn_component; 102 struct ldb_dn; 103 104 /** 105 There are a number of flags that are used with ldap_modify() in 106 ldb_message_element.flags fields. The LDB_FLAG_MOD_ADD, 107 LDB_FLAG_MOD_DELETE and LDB_FLAG_MOD_REPLACE are better thought of as 108 an enumeration, not flags, and are used in ldap_modify() calls to 109 specify whether attributes are being added, deleted or modified 110 respectively. 111 */ 112 #define LDB_FLAG_MOD_MASK 0x3 113 114 /** 115 use this to extract the mod type (enum) from the operation 116 */ 117 #define LDB_FLAG_MOD_TYPE(flags) ((flags) & LDB_FLAG_MOD_MASK) 118 119 /** 120 Value used in ldap_modify() to indicate that attributes are 121 being added. 122 123 \sa LDB_FLAG_MOD_MASK 124 */ 125 #define LDB_FLAG_MOD_ADD 1 126 127 /** 128 Value used in ldap_modify() to indicate that attributes are 129 being replaced. 130 131 \sa LDB_FLAG_MOD_MASK 132 */ 133 #define LDB_FLAG_MOD_REPLACE 2 134 135 /** 136 Value used in ldap_modify() to indicate that attributes are 137 being deleted. 138 139 \sa LDB_FLAG_MOD_MASK 140 */ 141 #define LDB_FLAG_MOD_DELETE 3 142 143 /** 144 Flag value used in ldb_ldif_write_trace() to enforce binary encoded 145 attribute values per attribute. 146 147 This is a genuine flag, being outside LDB_FLAG_MOD_MASK and also 148 outside LDB_FLAG_INTERNAL_MASK 149 */ 150 #define LDB_FLAG_FORCE_NO_BASE64_LDIF 4 151 152 /** 153 flag bits on an element usable only by the internal implementation 154 */ 155 #define LDB_FLAG_INTERNAL_MASK 0xFFFFFFF0 156 157 /** 158 OID for logic AND comaprison. 159 160 This is the well known object ID for a logical AND comparitor. 161 */ 162 #define LDB_OID_COMPARATOR_AND "1.2.840.113556.1.4.803" 163 164 /** 165 OID for logic OR comparison. 166 167 This is the well known object ID for a logical OR comparitor. 168 */ 169 #define LDB_OID_COMPARATOR_OR "1.2.840.113556.1.4.804" 170 171 /** 172 results are given back as arrays of ldb_message_element 173 */ 174 struct ldb_message_element { 175 unsigned int flags; 176 const char *name; 177 unsigned int num_values; 178 struct ldb_val *values; 179 }; 180 181 182 /** 183 a ldb_message represents all or part of a record. It can contain an arbitrary 184 number of elements. 185 */ 186 struct ldb_message { 187 struct ldb_dn *dn; 188 unsigned int num_elements; 189 struct ldb_message_element *elements; 190 }; 191 192 enum ldb_changetype { 193 LDB_CHANGETYPE_NONE=0, 194 LDB_CHANGETYPE_ADD, 195 LDB_CHANGETYPE_DELETE, 196 LDB_CHANGETYPE_MODIFY, 197 LDB_CHANGETYPE_MODRDN 198 }; 199 200 /** 201 LDIF record 202 203 This structure contains a LDIF record, as returned from ldif_read() 204 and equivalent functions. 205 */ 206 struct ldb_ldif { 207 enum ldb_changetype changetype; /*!< The type of change */ 208 struct ldb_message *msg; /*!< The changes */ 209 }; 210 211 enum ldb_scope {LDB_SCOPE_DEFAULT=-1, 212 LDB_SCOPE_BASE=0, 213 LDB_SCOPE_ONELEVEL=1, 214 LDB_SCOPE_SUBTREE=2}; 215 216 struct ldb_context; 217 struct tevent_context; 218 219 /* debugging uses one of the following levels */ 220 enum ldb_debug_level {LDB_DEBUG_FATAL, LDB_DEBUG_ERROR, 221 LDB_DEBUG_WARNING, LDB_DEBUG_TRACE}; 222 223 /* alias for something that's not a fatal error but we really want to log */ 224 #define LDB_DEBUG_ALWAYS_LOG LDB_DEBUG_FATAL 225 226 /** 227 the user can optionally supply a debug function. The function 228 is based on the vfprintf() style of interface, but with the addition 229 of a severity level 230 */ 231 struct ldb_debug_ops { 232 void (*debug)(void *context, enum ldb_debug_level level, 233 const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0); 234 void *context; 235 }; 236 237 /** 238 The user can optionally supply a custom utf8 functions, 239 to handle comparisons and casefolding. 240 */ 241 struct ldb_utf8_fns { 242 void *context; 243 char *(*casefold)(void *context, TALLOC_CTX *mem_ctx, const char *s, size_t n); 244 }; 245 246 /** 247 Flag value for database connection mode. 248 249 If LDB_FLG_RDONLY is used in ldb_connect, then the database will be 250 opened read-only, if possible. 251 */ 252 #define LDB_FLG_RDONLY 1 253 254 /** 255 Flag value for database connection mode. 256 257 If LDB_FLG_NOSYNC is used in ldb_connect, then the database will be 258 opened without synchronous operations, if possible. 259 */ 260 #define LDB_FLG_NOSYNC 2 261 262 /** 263 Flag value to specify autoreconnect mode. 264 265 If LDB_FLG_RECONNECT is used in ldb_connect, then the backend will 266 be opened in a way that makes it try to auto reconnect if the 267 connection is dropped (actually make sense only with ldap). 268 */ 269 #define LDB_FLG_RECONNECT 4 270 271 /** 272 Flag to tell backends not to use mmap 273 */ 274 #define LDB_FLG_NOMMAP 8 275 276 /** 277 Flag to tell ldif handlers not to force encoding of binary 278 structures in base64 279 */ 280 #define LDB_FLG_SHOW_BINARY 16 281 282 /** 283 Flags to enable ldb tracing 284 */ 285 #define LDB_FLG_ENABLE_TRACING 32 286 287 /** 288 Flags to tell LDB not to create a new database file: 289 290 Without this flag ldb_tdb (for example) will create a blank file 291 during an invocation of ldb_connect(), even when the caller only 292 wanted read operations, for example in ldbsearch. 293 */ 294 #define LDB_FLG_DONT_CREATE_DB 64 295 296 /* 297 structures for ldb_parse_tree handling code 298 */ 299 enum ldb_parse_op { LDB_OP_AND=1, LDB_OP_OR=2, LDB_OP_NOT=3, 300 LDB_OP_EQUALITY=4, LDB_OP_SUBSTRING=5, 301 LDB_OP_GREATER=6, LDB_OP_LESS=7, LDB_OP_PRESENT=8, 302 LDB_OP_APPROX=9, LDB_OP_EXTENDED=10 }; 303 304 struct ldb_parse_tree { 305 enum ldb_parse_op operation; 306 union { 307 struct { 308 struct ldb_parse_tree *child; 309 } isnot; 310 struct { 311 const char *attr; 312 struct ldb_val value; 313 } equality; 314 struct { 315 const char *attr; 316 int start_with_wildcard; 317 int end_with_wildcard; 318 struct ldb_val **chunks; 319 } substring; 320 struct { 321 const char *attr; 322 } present; 323 struct { 324 const char *attr; 325 struct ldb_val value; 326 } comparison; 327 struct { 328 const char *attr; 329 int dnAttributes; 330 const char *rule_id; 331 struct ldb_val value; 332 } extended; 333 struct { 334 unsigned int num_elements; 335 struct ldb_parse_tree **elements; 336 } list; 337 } u; 338 }; 339 340 struct ldb_parse_tree *ldb_parse_tree(TALLOC_CTX *mem_ctx, const char *s); 341 char *ldb_filter_from_tree(TALLOC_CTX *mem_ctx, const struct ldb_parse_tree *tree); 342 343 /** 344 Encode a binary blob 345 346 This function encodes a binary blob using the encoding rules in RFC 347 2254 (Section 4). This function also escapes any non-printable 348 characters. 349 350 \param mem_ctx the memory context to allocate the return string in. 351 \param val the (potentially) binary data to be encoded 352 353 \return the encoded data as a null terminated string 354 355 \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>. 356 */ 357 char *ldb_binary_encode(TALLOC_CTX *mem_ctx, struct ldb_val val); 358 359 /** 360 Encode a string 361 362 This function encodes a string using the encoding rules in RFC 2254 363 (Section 4). This function also escapes any non-printable 364 characters. 365 366 \param mem_ctx the memory context to allocate the return string in. 367 \param string the string to be encoded 368 369 \return the encoded data as a null terminated string 370 371 \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>. 372 */ 373 char *ldb_binary_encode_string(TALLOC_CTX *mem_ctx, const char *string); 374 375 /* 376 functions for controlling attribute handling 377 */ 378 typedef int (*ldb_attr_handler_t)(struct ldb_context *, TALLOC_CTX *mem_ctx, const struct ldb_val *, struct ldb_val *); 379 typedef int (*ldb_attr_comparison_t)(struct ldb_context *, TALLOC_CTX *mem_ctx, const struct ldb_val *, const struct ldb_val *); 380 struct ldb_schema_attribute; 381 typedef int (*ldb_attr_operator_t)(struct ldb_context *, enum ldb_parse_op operation, 382 const struct ldb_schema_attribute *a, 383 const struct ldb_val *, const struct ldb_val *, bool *matched); 384 385 /* 386 attribute handler structure 387 388 attr -> The attribute name 389 ldif_read_fn -> convert from ldif to binary format 390 ldif_write_fn -> convert from binary to ldif format 391 canonicalise_fn -> canonicalise a value, for use by indexing and dn construction 392 index_form_fn -> get lexicographically sorted format for index 393 comparison_fn -> compare two values 394 operator_fn -> override function for optimizing out unnecessary 395 calls to canonicalise_fn and comparison_fn 396 */ 397 398 struct ldb_schema_syntax { 399 const char *name; 400 ldb_attr_handler_t ldif_read_fn; 401 ldb_attr_handler_t ldif_write_fn; 402 ldb_attr_handler_t canonicalise_fn; 403 ldb_attr_handler_t index_format_fn; 404 ldb_attr_comparison_t comparison_fn; 405 ldb_attr_operator_t operator_fn; 406 }; 407 408 struct ldb_schema_attribute { 409 const char *name; 410 unsigned flags; 411 const struct ldb_schema_syntax *syntax; 412 }; 413 414 const struct ldb_schema_attribute *ldb_schema_attribute_by_name(struct ldb_context *ldb, 415 const char *name); 416 417 struct ldb_dn_extended_syntax { 418 const char *name; 419 ldb_attr_handler_t read_fn; 420 ldb_attr_handler_t write_clear_fn; 421 ldb_attr_handler_t write_hex_fn; 422 }; 423 424 const struct ldb_dn_extended_syntax *ldb_dn_extended_syntax_by_name(struct ldb_context *ldb, 425 const char *name); 426 427 /** 428 The attribute is not returned by default 429 */ 430 #define LDB_ATTR_FLAG_HIDDEN (1<<0) 431 432 /* the attribute handler name should be freed when released */ 433 #define LDB_ATTR_FLAG_ALLOCATED (1<<1) 434 435 /** 436 The attribute is supplied by the application and should not be removed 437 */ 438 #define LDB_ATTR_FLAG_FIXED (1<<2) 439 440 /* 441 when this is set, attempts to create two records which have the same 442 value for this attribute will return LDB_ERR_ENTRY_ALREADY_EXISTS 443 */ 444 #define LDB_ATTR_FLAG_UNIQUE_INDEX (1<<3) 445 446 /* 447 when this is set, attempts to create two attribute values for this attribute on a single DN will return LDB_ERR_CONSTRAINT_VIOLATION 448 */ 449 #define LDB_ATTR_FLAG_SINGLE_VALUE (1<<4) 450 451 /* 452 * The values should always be base64 encoded 453 */ 454 #define LDB_ATTR_FLAG_FORCE_BASE64_LDIF (1<<5) 455 456 /* 457 * The attribute was loaded from a DB, rather than via the C API 458 */ 459 #define LDB_ATTR_FLAG_FROM_DB (1<<6) 460 461 /* 462 * The attribute is indexed 463 */ 464 #define LDB_ATTR_FLAG_INDEXED (1<<7) 465 466 /** 467 LDAP attribute syntax for a DN 468 469 This is the well-known LDAP attribute syntax for a DN. 470 471 See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 472 */ 473 #define LDB_SYNTAX_DN "1.3.6.1.4.1.1466.115.121.1.12" 474 475 /** 476 LDAP attribute syntax for a Directory String 477 478 This is the well-known LDAP attribute syntax for a Directory String. 479 480 \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 481 */ 482 #define LDB_SYNTAX_DIRECTORY_STRING "1.3.6.1.4.1.1466.115.121.1.15" 483 484 /** 485 LDAP attribute syntax for an integer 486 487 This is the well-known LDAP attribute syntax for an integer. 488 489 See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 490 */ 491 #define LDB_SYNTAX_INTEGER "1.3.6.1.4.1.1466.115.121.1.27" 492 493 /** 494 Custom attribute syntax for an integer whose index is lexicographically 495 ordered by attribute value in the database. 496 */ 497 #define LDB_SYNTAX_ORDERED_INTEGER "LDB_SYNTAX_ORDERED_INTEGER" 498 499 /** 500 LDAP attribute syntax for a boolean 501 502 This is the well-known LDAP attribute syntax for a boolean. 503 504 See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 505 */ 506 #define LDB_SYNTAX_BOOLEAN "1.3.6.1.4.1.1466.115.121.1.7" 507 508 /** 509 LDAP attribute syntax for an octet string 510 511 This is the well-known LDAP attribute syntax for an octet string. 512 513 See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 514 */ 515 #define LDB_SYNTAX_OCTET_STRING "1.3.6.1.4.1.1466.115.121.1.40" 516 517 /** 518 LDAP attribute syntax for UTC time. 519 520 This is the well-known LDAP attribute syntax for a UTC time. 521 522 See <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>, Section 4.3.2 523 */ 524 #define LDB_SYNTAX_UTC_TIME "1.3.6.1.4.1.1466.115.121.1.53" 525 #define LDB_SYNTAX_GENERALIZED_TIME "1.3.6.1.4.1.1466.115.121.1.24" 526 527 #define LDB_SYNTAX_OBJECTCLASS "LDB_SYNTAX_OBJECTCLASS" 528 529 /* sorting helpers */ 530 typedef int (*ldb_qsort_cmp_fn_t) (void *v1, void *v2, void *opaque); 531 532 /* Individual controls */ 533 534 /** 535 OID for getting and manipulating attributes from the ldb 536 without interception in the operational module. 537 It can be used to access attribute that used to be stored in the sam 538 and that are now calculated. 539 */ 540 #define LDB_CONTROL_BYPASS_OPERATIONAL_OID "1.3.6.1.4.1.7165.4.3.13" 541 #define LDB_CONTROL_BYPASS_OPERATIONAL_NAME "bypassoperational" 542 543 /** 544 OID for recalculate RDN (rdn attribute and 'name') control. This control forces 545 the rdn_name module to the recalculate the rdn and name attributes as if the 546 object was just created. 547 */ 548 #define LDB_CONTROL_RECALCULATE_RDN_OID "1.3.6.1.4.1.7165.4.3.30" 549 550 /** 551 OID for recalculate SD control. This control force the 552 dsdb code to recalculate the SD of the object as if the 553 object was just created. 554 555 */ 556 #define LDB_CONTROL_RECALCULATE_SD_OID "1.3.6.1.4.1.7165.4.3.5" 557 #define LDB_CONTROL_RECALCULATE_SD_NAME "recalculate_sd" 558 559 /** 560 REVEAL_INTERNALS is used to reveal internal attributes and DN 561 components which are not normally shown to the user 562 */ 563 #define LDB_CONTROL_REVEAL_INTERNALS "1.3.6.1.4.1.7165.4.3.6" 564 #define LDB_CONTROL_REVEAL_INTERNALS_NAME "reveal_internals" 565 566 /** 567 LDB_CONTROL_AS_SYSTEM is used to skip access checks on operations 568 that are performed by the system, but with a user's credentials, e.g. 569 updating prefix map 570 */ 571 #define LDB_CONTROL_AS_SYSTEM_OID "1.3.6.1.4.1.7165.4.3.7" 572 573 /** 574 LDB_CONTROL_PROVISION_OID is used to skip some constraint checks. It's is 575 mainly thought to be used for the provisioning. 576 */ 577 #define LDB_CONTROL_PROVISION_OID "1.3.6.1.4.1.7165.4.3.16" 578 #define LDB_CONTROL_PROVISION_NAME "provision" 579 580 /* AD controls */ 581 582 /** 583 OID for the paged results control. This control is included in the 584 searchRequest and searchResultDone messages as part of the controls 585 field of the LDAPMessage, as defined in Section 4.1.12 of 586 LDAP v3. 587 588 \sa <a href="http://www.ietf.org/rfc/rfc2696.txt">RFC 2696</a>. 589 */ 590 #define LDB_CONTROL_PAGED_RESULTS_OID "1.2.840.113556.1.4.319" 591 #define LDB_CONTROL_PAGED_RESULTS_NAME "paged_results" 592 593 /** 594 OID for specifying the returned elements of the ntSecurityDescriptor 595 596 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_sd_flags_oid.asp">Microsoft documentation of this OID</a> 597 */ 598 #define LDB_CONTROL_SD_FLAGS_OID "1.2.840.113556.1.4.801" 599 #define LDB_CONTROL_SD_FLAGS_NAME "sd_flags" 600 601 /** 602 OID for specifying an advanced scope for the search (one partition) 603 604 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_domain_scope_oid.asp">Microsoft documentation of this OID</a> 605 */ 606 #define LDB_CONTROL_DOMAIN_SCOPE_OID "1.2.840.113556.1.4.1339" 607 #define LDB_CONTROL_DOMAIN_SCOPE_NAME "domain_scope" 608 609 /** 610 OID for specifying an advanced scope for a search 611 612 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_search_options_oid.asp">Microsoft documentation of this OID</a> 613 */ 614 #define LDB_CONTROL_SEARCH_OPTIONS_OID "1.2.840.113556.1.4.1340" 615 #define LDB_CONTROL_SEARCH_OPTIONS_NAME "search_options" 616 617 /** 618 OID for notification 619 620 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_notification_oid.asp">Microsoft documentation of this OID</a> 621 */ 622 #define LDB_CONTROL_NOTIFICATION_OID "1.2.840.113556.1.4.528" 623 #define LDB_CONTROL_NOTIFICATION_NAME "notification" 624 625 /** 626 OID for performing subtree deletes 627 628 \sa <a href="http://msdn.microsoft.com/en-us/library/aa366991(v=VS.85).aspx">Microsoft documentation of this OID</a> 629 */ 630 #define LDB_CONTROL_TREE_DELETE_OID "1.2.840.113556.1.4.805" 631 #define LDB_CONTROL_TREE_DELETE_NAME "tree_delete" 632 633 /** 634 OID for getting deleted objects 635 636 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_show_deleted_oid.asp">Microsoft documentation of this OID</a> 637 */ 638 #define LDB_CONTROL_SHOW_DELETED_OID "1.2.840.113556.1.4.417" 639 #define LDB_CONTROL_SHOW_DELETED_NAME "show_deleted" 640 641 /** 642 OID for getting recycled objects 643 644 \sa <a href="http://msdn.microsoft.com/en-us/library/dd304621(PROT.13).aspx">Microsoft documentation of this OID</a> 645 */ 646 #define LDB_CONTROL_SHOW_RECYCLED_OID "1.2.840.113556.1.4.2064" 647 #define LDB_CONTROL_SHOW_RECYCLED_NAME "show_recycled" 648 649 /** 650 OID for getting deactivated linked attributes 651 652 \sa <a href="http://msdn.microsoft.com/en-us/library/dd302781(PROT.13).aspx">Microsoft documentation of this OID</a> 653 */ 654 #define LDB_CONTROL_SHOW_DEACTIVATED_LINK_OID "1.2.840.113556.1.4.2065" 655 #define LDB_CONTROL_SHOW_DEACTIVATED_LINK_NAME "show_deactivated_link" 656 657 /** 658 OID for extended DN 659 660 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_extended_dn_oid.asp">Microsoft documentation of this OID</a> 661 */ 662 #define LDB_CONTROL_EXTENDED_DN_OID "1.2.840.113556.1.4.529" 663 #define LDB_CONTROL_EXTENDED_DN_NAME "extended_dn" 664 665 /** 666 OID for LDAP server sort result extension. 667 668 This control is included in the searchRequest message as part of 669 the controls field of the LDAPMessage, as defined in Section 4.1.12 670 of LDAP v3. The controlType is set to 671 "1.2.840.113556.1.4.473". The criticality MAY be either TRUE or 672 FALSE (where absent is also equivalent to FALSE) at the client's 673 option. 674 675 \sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>. 676 */ 677 #define LDB_CONTROL_SERVER_SORT_OID "1.2.840.113556.1.4.473" 678 #define LDB_CONTROL_SERVER_SORT_NAME "server_sort" 679 680 /** 681 OID for LDAP server sort result response extension. 682 683 This control is included in the searchResultDone message as part of 684 the controls field of the LDAPMessage, as defined in Section 4.1.12 of 685 LDAP v3. 686 687 \sa <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>. 688 */ 689 #define LDB_CONTROL_SORT_RESP_OID "1.2.840.113556.1.4.474" 690 #define LDB_CONTROL_SORT_RESP_NAME "server_sort_resp" 691 692 /** 693 OID for LDAP Attribute Scoped Query extension. 694 695 This control is included in SearchRequest or SearchResponse 696 messages as part of the controls field of the LDAPMessage. 697 */ 698 #define LDB_CONTROL_ASQ_OID "1.2.840.113556.1.4.1504" 699 #define LDB_CONTROL_ASQ_NAME "asq" 700 701 /** 702 OID for LDAP Directory Sync extension. 703 704 This control is included in SearchRequest or SearchResponse 705 messages as part of the controls field of the LDAPMessage. 706 */ 707 #define LDB_CONTROL_DIRSYNC_OID "1.2.840.113556.1.4.841" 708 #define LDB_CONTROL_DIRSYNC_NAME "dirsync" 709 #define LDB_CONTROL_DIRSYNC_EX_OID "1.2.840.113556.1.4.2090" 710 #define LDB_CONTROL_DIRSYNC_EX_NAME "dirsync_ex" 711 712 713 /** 714 OID for LDAP Virtual List View Request extension. 715 716 This control is included in SearchRequest messages 717 as part of the controls field of the LDAPMessage. 718 */ 719 #define LDB_CONTROL_VLV_REQ_OID "2.16.840.1.113730.3.4.9" 720 #define LDB_CONTROL_VLV_REQ_NAME "vlv" 721 722 /** 723 OID for LDAP Virtual List View Response extension. 724 725 This control is included in SearchResponse messages 726 as part of the controls field of the LDAPMessage. 727 */ 728 #define LDB_CONTROL_VLV_RESP_OID "2.16.840.1.113730.3.4.10" 729 #define LDB_CONTROL_VLV_RESP_NAME "vlv_resp" 730 731 /** 732 OID to let modifies don't give an error when adding an existing 733 attribute with the same value or deleting an nonexisting one attribute 734 735 \sa <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ldap/ldap/ldap_server_permissive_modify_oid.asp">Microsoft documentation of this OID</a> 736 */ 737 #define LDB_CONTROL_PERMISSIVE_MODIFY_OID "1.2.840.113556.1.4.1413" 738 #define LDB_CONTROL_PERMISSIVE_MODIFY_NAME "permissive_modify" 739 740 /** 741 OID to allow the server to be more 'fast and loose' with the data being added. 742 743 \sa <a href="http://msdn.microsoft.com/en-us/library/aa366982(v=VS.85).aspx">Microsoft documentation of this OID</a> 744 */ 745 #define LDB_CONTROL_SERVER_LAZY_COMMIT "1.2.840.113556.1.4.619" 746 747 /** 748 Control for RODC join -see [MS-ADTS] section 3.1.1.3.4.1.23 749 750 \sa <a href="">Microsoft documentation of this OID</a> 751 */ 752 #define LDB_CONTROL_RODC_DCPROMO_OID "1.2.840.113556.1.4.1341" 753 #define LDB_CONTROL_RODC_DCPROMO_NAME "rodc_join" 754 755 /* Other standardised controls */ 756 757 /** 758 OID for the allowing client to request temporary relaxed 759 enforcement of constraints of the x.500 model. 760 761 Mainly used for the OpenLDAP backend. 762 763 \sa <a href="http://opends.dev.java.net/public/standards/draft-zeilenga-ldap-managedit.txt">draft managedit</a>. 764 */ 765 #define LDB_CONTROL_RELAX_OID "1.3.6.1.4.1.4203.666.5.12" 766 #define LDB_CONTROL_RELAX_NAME "relax" 767 768 /** 769 OID for the allowing some kind of relax check for attributes with DNs 770 771 772 \sa 3.1.1.3.4.1.16 in [MS-ADTS].pdf 773 */ 774 #define LDB_CONTROL_VERIFY_NAME_OID "1.2.840.113556.1.4.1338" 775 #define LDB_CONTROL_VERIFY_NAME_NAME "verify_name" 776 777 /* Extended operations */ 778 779 /** 780 OID for LDAP Extended Operation SEQUENCE_NUMBER 781 782 This extended operation is used to retrieve the extended sequence number. 783 */ 784 #define LDB_EXTENDED_SEQUENCE_NUMBER "1.3.6.1.4.1.7165.4.4.3" 785 786 /** 787 OID for LDAP Extended Operation PASSWORD_CHANGE. 788 789 This Extended operation is used to allow user password changes by the user 790 itself. 791 */ 792 #define LDB_EXTENDED_PASSWORD_CHANGE_OID "1.3.6.1.4.1.4203.1.11.1" 793 794 795 /** 796 OID for LDAP Extended Operation FAST_BIND 797 798 This Extended operations is used to perform a fast bind. 799 */ 800 #define LDB_EXTENDED_FAST_BIND_OID "1.2.840.113556.1.4.1781" 801 802 /** 803 OID for LDAP Extended Operation START_TLS. 804 805 This Extended operation is used to start a new TLS channel on top of a clear 806 text channel. 807 */ 808 #define LDB_EXTENDED_START_TLS_OID "1.3.6.1.4.1.1466.20037" 809 810 /** 811 OID for LDAP Extended Operation DYNAMIC_REFRESH. 812 813 This Extended operation is used to create and maintain objects which exist 814 only a specific time, e.g. when a certain client or a certain person is 815 logged in. Data refreshes have to be periodically sent in a specific 816 interval. Otherwise the entry is going to be removed. 817 */ 818 #define LDB_EXTENDED_DYNAMIC_OID "1.3.6.1.4.1.1466.101.119.1" 819 820 struct ldb_sd_flags_control { 821 /* 822 * request the owner 0x00000001 823 * request the group 0x00000002 824 * request the DACL 0x00000004 825 * request the SACL 0x00000008 826 */ 827 unsigned secinfo_flags; 828 }; 829 830 /* 831 * DOMAIN_SCOPE 0x00000001 832 * this limits the search to one partition, 833 * and no referrals will be returned. 834 * (Note this doesn't limit the entries by there 835 * objectSid belonging to a domain! Builtin and Foreign Sids 836 * are still returned) 837 * 838 * PHANTOM_ROOT 0x00000002 839 * this search on the whole tree on a domain controller 840 * over multiple partitions without referrals. 841 * (This is the default behavior on the Global Catalog Port) 842 */ 843 844 #define LDB_SEARCH_OPTION_DOMAIN_SCOPE 0x00000001 845 #define LDB_SEARCH_OPTION_PHANTOM_ROOT 0x00000002 846 847 struct ldb_search_options_control { 848 unsigned search_options; 849 }; 850 851 struct ldb_paged_control { 852 int size; 853 int cookie_len; 854 char *cookie; 855 }; 856 857 struct ldb_extended_dn_control { 858 int type; 859 }; 860 861 struct ldb_server_sort_control { 862 const char *attributeName; 863 const char *orderingRule; 864 int reverse; 865 }; 866 867 struct ldb_sort_resp_control { 868 int result; 869 char *attr_desc; 870 }; 871 872 struct ldb_asq_control { 873 int request; 874 char *source_attribute; 875 int src_attr_len; 876 int result; 877 }; 878 879 struct ldb_dirsync_control { 880 int flags; 881 int max_attributes; 882 int cookie_len; 883 char *cookie; 884 }; 885 886 struct ldb_vlv_req_control { 887 int beforeCount; 888 int afterCount; 889 int type; 890 union { 891 struct { 892 int offset; 893 int contentCount; 894 } byOffset; 895 struct { 896 int value_len; 897 char *value; 898 } gtOrEq; 899 } match; 900 int ctxid_len; 901 uint8_t *contextId; 902 }; 903 904 struct ldb_vlv_resp_control { 905 int targetPosition; 906 int contentCount; 907 int vlv_result; 908 int ctxid_len; 909 uint8_t *contextId; 910 }; 911 912 struct ldb_verify_name_control { 913 int flags; 914 size_t gc_len; 915 char *gc; 916 }; 917 918 struct ldb_control { 919 const char *oid; 920 int critical; 921 void *data; 922 }; 923 924 enum ldb_request_type { 925 LDB_SEARCH, 926 LDB_ADD, 927 LDB_MODIFY, 928 LDB_DELETE, 929 LDB_RENAME, 930 LDB_EXTENDED, 931 LDB_REQ_REGISTER_CONTROL, 932 LDB_REQ_REGISTER_PARTITION 933 }; 934 935 enum ldb_reply_type { 936 LDB_REPLY_ENTRY, 937 LDB_REPLY_REFERRAL, 938 LDB_REPLY_DONE 939 }; 940 941 enum ldb_wait_type { 942 LDB_WAIT_ALL, 943 LDB_WAIT_NONE 944 }; 945 946 enum ldb_state { 947 LDB_ASYNC_INIT, 948 LDB_ASYNC_PENDING, 949 LDB_ASYNC_DONE 950 }; 951 952 struct ldb_extended { 953 const char *oid; 954 void *data; /* NULL or a valid talloc pointer! talloc_get_type() will be used on it */ 955 }; 956 957 enum ldb_sequence_type { 958 LDB_SEQ_HIGHEST_SEQ, 959 LDB_SEQ_HIGHEST_TIMESTAMP, 960 LDB_SEQ_NEXT 961 }; 962 963 #define LDB_SEQ_GLOBAL_SEQUENCE 0x01 964 #define LDB_SEQ_TIMESTAMP_SEQUENCE 0x02 965 966 struct ldb_seqnum_request { 967 enum ldb_sequence_type type; 968 }; 969 970 struct ldb_seqnum_result { 971 uint64_t seq_num; 972 uint32_t flags; 973 }; 974 975 struct ldb_result { 976 unsigned int count; 977 struct ldb_message **msgs; 978 struct ldb_extended *extended; 979 struct ldb_control **controls; 980 char **refs; 981 }; 982 983 struct ldb_reply { 984 int error; 985 enum ldb_reply_type type; 986 struct ldb_message *message; 987 struct ldb_extended *response; 988 struct ldb_control **controls; 989 char *referral; 990 }; 991 992 struct ldb_request; 993 struct ldb_handle; 994 995 struct ldb_search { 996 struct ldb_dn *base; 997 enum ldb_scope scope; 998 struct ldb_parse_tree *tree; 999 const char * const *attrs; 1000 struct ldb_result *res; 1001 }; 1002 1003 struct ldb_add { 1004 const struct ldb_message *message; 1005 }; 1006 1007 struct ldb_modify { 1008 const struct ldb_message *message; 1009 }; 1010 1011 struct ldb_delete { 1012 struct ldb_dn *dn; 1013 }; 1014 1015 struct ldb_rename { 1016 struct ldb_dn *olddn; 1017 struct ldb_dn *newdn; 1018 }; 1019 1020 struct ldb_register_control { 1021 const char *oid; 1022 }; 1023 1024 struct ldb_register_partition { 1025 struct ldb_dn *dn; 1026 }; 1027 1028 typedef int (*ldb_request_callback_t)(struct ldb_request *, struct ldb_reply *); 1029 1030 struct ldb_request { 1031 1032 enum ldb_request_type operation; 1033 1034 union { 1035 struct ldb_search search; 1036 struct ldb_add add; 1037 struct ldb_modify mod; 1038 struct ldb_delete del; 1039 struct ldb_rename rename; 1040 struct ldb_extended extended; 1041 struct ldb_register_control reg_control; 1042 struct ldb_register_partition reg_partition; 1043 } op; 1044 1045 struct ldb_control **controls; 1046 1047 void *context; 1048 ldb_request_callback_t callback; 1049 1050 int timeout; 1051 time_t starttime; 1052 struct ldb_handle *handle; 1053 }; 1054 1055 int ldb_request(struct ldb_context *ldb, struct ldb_request *request); 1056 int ldb_request_done(struct ldb_request *req, int status); 1057 bool ldb_request_is_done(struct ldb_request *req); 1058 1059 int ldb_modules_wait(struct ldb_handle *handle); 1060 int ldb_wait(struct ldb_handle *handle, enum ldb_wait_type type); 1061 1062 int ldb_set_timeout(struct ldb_context *ldb, struct ldb_request *req, int timeout); 1063 int ldb_set_timeout_from_prev_req(struct ldb_context *ldb, struct ldb_request *oldreq, struct ldb_request *newreq); 1064 void ldb_set_create_perms(struct ldb_context *ldb, unsigned int perms); 1065 void ldb_set_modules_dir(struct ldb_context *ldb, const char *path); 1066 struct tevent_context; 1067 void ldb_set_event_context(struct ldb_context *ldb, struct tevent_context *ev); 1068 struct tevent_context * ldb_get_event_context(struct ldb_context *ldb); 1069 1070 /** 1071 Initialise ldbs' global information 1072 1073 This is required before any other LDB call 1074 1075 \return 0 if initialisation succeeded, -1 otherwise 1076 */ 1077 int ldb_global_init(void); 1078 1079 /** 1080 Initialise an ldb context 1081 1082 This is required before any other LDB call. 1083 1084 \param mem_ctx pointer to a talloc memory context. Pass NULL if there is 1085 no suitable context available. 1086 1087 \note The LDB modules will be loaded from directory specified by the environment 1088 variable LDB_MODULES_PATH. If the variable is not specified, the compiled-in default 1089 is used. 1090 1091 \return pointer to ldb_context that should be free'd (using talloc_free()) 1092 at the end of the program. 1093 */ 1094 struct ldb_context *ldb_init(TALLOC_CTX *mem_ctx, struct tevent_context *ev_ctx); 1095 1096 typedef void (*ldb_async_timeout_fn) (void *); 1097 typedef bool (*ldb_async_callback_fn) (void *); 1098 typedef int (*ldb_async_ctx_add_op_fn)(void *, time_t, void *, ldb_async_timeout_fn, ldb_async_callback_fn); 1099 typedef int (*ldb_async_ctx_wait_op_fn)(void *); 1100 1101 void ldb_async_ctx_set_private_data(struct ldb_context *ldb, 1102 void *private_data); 1103 void ldb_async_ctx_set_add_op(struct ldb_context *ldb, 1104 ldb_async_ctx_add_op_fn add_op); 1105 void ldb_async_ctx_set_wait_op(struct ldb_context *ldb, 1106 ldb_async_ctx_wait_op_fn wait_op); 1107 1108 /** 1109 Connect to a database. 1110 1111 This is typically called soon after ldb_init(), and is required prior to 1112 any search or database modification operations. 1113 1114 The URL can be one of the following forms: 1115 - tdb://path 1116 - ldapi://path 1117 - ldap://host 1118 - sqlite://path 1119 1120 \param ldb the context associated with the database (from ldb_init()) 1121 \param url the URL of the database to connect to, as noted above 1122 \param flags a combination of LDB_FLG_* to modify the connection behaviour 1123 \param options backend specific options - passed uninterpreted to the backend 1124 1125 \return result code (LDB_SUCCESS on success, or a failure code) 1126 1127 \note It is an error to connect to a database that does not exist in readonly mode 1128 (that is, with LDB_FLG_RDONLY). However in read-write mode, the database will be 1129 created if it does not exist. 1130 */ 1131 int ldb_connect(struct ldb_context *ldb, const char *url, unsigned int flags, const char *options[]); 1132 1133 /* 1134 return an automatic basedn from the rootDomainNamingContext of the rootDSE 1135 This value have been set in an opaque pointer at connection time 1136 */ 1137 struct ldb_dn *ldb_get_root_basedn(struct ldb_context *ldb); 1138 1139 /* 1140 return an automatic basedn from the configurationNamingContext of the rootDSE 1141 This value have been set in an opaque pointer at connection time 1142 */ 1143 struct ldb_dn *ldb_get_config_basedn(struct ldb_context *ldb); 1144 1145 /* 1146 return an automatic basedn from the schemaNamingContext of the rootDSE 1147 This value have been set in an opaque pointer at connection time 1148 */ 1149 struct ldb_dn *ldb_get_schema_basedn(struct ldb_context *ldb); 1150 1151 /* 1152 return an automatic baseDN from the defaultNamingContext of the rootDSE 1153 This value have been set in an opaque pointer at connection time 1154 */ 1155 struct ldb_dn *ldb_get_default_basedn(struct ldb_context *ldb); 1156 1157 /** 1158 The default async search callback function 1159 1160 \param req the request we are callback of 1161 \param ares a single reply from the async core 1162 1163 \return result code (LDB_SUCCESS on success, or a failure code) 1164 1165 \note this function expects req->context to always be an struct ldb_result pointer 1166 AND a talloc context, this function will steal on the context each message 1167 from the ares reply passed on by the async core so that in the end all the 1168 messages will be in the context (ldb_result) memory tree. 1169 Freeing the passed context (ldb_result tree) will free all the resources 1170 (the request need to be freed separately and the result doe not depend on the 1171 request that can be freed as sson as the search request is finished) 1172 */ 1173 1174 int ldb_search_default_callback(struct ldb_request *req, struct ldb_reply *ares); 1175 1176 /** 1177 The default async extended operation callback function 1178 1179 \param req the request we are callback of 1180 \param ares a single reply from the async core 1181 1182 \return result code (LDB_SUCCESS on success, or a failure code) 1183 */ 1184 int ldb_op_default_callback(struct ldb_request *req, struct ldb_reply *ares); 1185 1186 int ldb_modify_default_callback(struct ldb_request *req, struct ldb_reply *ares); 1187 1188 /** 1189 Helper function to build a search request 1190 1191 \param ret_req the request structure is returned here (talloced on mem_ctx) 1192 \param ldb the context associated with the database (from ldb_init()) 1193 \param mem_ctx a talloc memory context (used as parent of ret_req) 1194 \param base the Base Distinguished Name for the query (use ldb_dn_new() for an empty one) 1195 \param scope the search scope for the query 1196 \param expression the search expression to use for this query 1197 \param attrs the search attributes for the query (pass NULL if none required) 1198 \param controls an array of controls 1199 \param context the callback function context 1200 \param the callback function to handle the async replies 1201 \param the parent request if any 1202 1203 \return result code (LDB_SUCCESS on success, or a failure code) 1204 */ 1205 1206 int ldb_build_search_req(struct ldb_request **ret_req, 1207 struct ldb_context *ldb, 1208 TALLOC_CTX *mem_ctx, 1209 struct ldb_dn *base, 1210 enum ldb_scope scope, 1211 const char *expression, 1212 const char * const *attrs, 1213 struct ldb_control **controls, 1214 void *context, 1215 ldb_request_callback_t callback, 1216 struct ldb_request *parent); 1217 1218 int ldb_build_search_req_ex(struct ldb_request **ret_req, 1219 struct ldb_context *ldb, 1220 TALLOC_CTX *mem_ctx, 1221 struct ldb_dn *base, 1222 enum ldb_scope scope, 1223 struct ldb_parse_tree *tree, 1224 const char * const *attrs, 1225 struct ldb_control **controls, 1226 void *context, 1227 ldb_request_callback_t callback, 1228 struct ldb_request *parent); 1229 1230 /** 1231 Helper function to build an add request 1232 1233 \param ret_req the request structure is returned here (talloced on mem_ctx) 1234 \param ldb the context associated with the database (from ldb_init()) 1235 \param mem_ctx a talloc memory context (used as parent of ret_req) 1236 \param message contains the entry to be added 1237 \param controls an array of controls 1238 \param context the callback function context 1239 \param the callback function to handle the async replies 1240 \param the parent request if any 1241 1242 \return result code (LDB_SUCCESS on success, or a failure code) 1243 */ 1244 1245 int ldb_build_add_req(struct ldb_request **ret_req, 1246 struct ldb_context *ldb, 1247 TALLOC_CTX *mem_ctx, 1248 const struct ldb_message *message, 1249 struct ldb_control **controls, 1250 void *context, 1251 ldb_request_callback_t callback, 1252 struct ldb_request *parent); 1253 1254 /** 1255 Helper function to build a modify request 1256 1257 \param ret_req the request structure is returned here (talloced on mem_ctx) 1258 \param ldb the context associated with the database (from ldb_init()) 1259 \param mem_ctx a talloc memory context (used as parent of ret_req) 1260 \param message contains the entry to be modified 1261 \param controls an array of controls 1262 \param context the callback function context 1263 \param the callback function to handle the async replies 1264 \param the parent request if any 1265 1266 \return result code (LDB_SUCCESS on success, or a failure code) 1267 */ 1268 1269 int ldb_build_mod_req(struct ldb_request **ret_req, 1270 struct ldb_context *ldb, 1271 TALLOC_CTX *mem_ctx, 1272 const struct ldb_message *message, 1273 struct ldb_control **controls, 1274 void *context, 1275 ldb_request_callback_t callback, 1276 struct ldb_request *parent); 1277 1278 /** 1279 Helper function to build a delete request 1280 1281 \param ret_req the request structure is returned here (talloced on mem_ctx) 1282 \param ldb the context associated with the database (from ldb_init()) 1283 \param mem_ctx a talloc memory context (used as parent of ret_req) 1284 \param dn the DN to be deleted 1285 \param controls an array of controls 1286 \param context the callback function context 1287 \param the callback function to handle the async replies 1288 \param the parent request if any 1289 1290 \return result code (LDB_SUCCESS on success, or a failure code) 1291 */ 1292 1293 int ldb_build_del_req(struct ldb_request **ret_req, 1294 struct ldb_context *ldb, 1295 TALLOC_CTX *mem_ctx, 1296 struct ldb_dn *dn, 1297 struct ldb_control **controls, 1298 void *context, 1299 ldb_request_callback_t callback, 1300 struct ldb_request *parent); 1301 1302 /** 1303 Helper function to build a rename request 1304 1305 \param ret_req the request structure is returned here (talloced on mem_ctx) 1306 \param ldb the context associated with the database (from ldb_init()) 1307 \param mem_ctx a talloc memory context (used as parent of ret_req) 1308 \param olddn the old DN 1309 \param newdn the new DN 1310 \param controls an array of controls 1311 \param context the callback function context 1312 \param the callback function to handle the async replies 1313 \param the parent request if any 1314 1315 \return result code (LDB_SUCCESS on success, or a failure code) 1316 */ 1317 1318 int ldb_build_rename_req(struct ldb_request **ret_req, 1319 struct ldb_context *ldb, 1320 TALLOC_CTX *mem_ctx, 1321 struct ldb_dn *olddn, 1322 struct ldb_dn *newdn, 1323 struct ldb_control **controls, 1324 void *context, 1325 ldb_request_callback_t callback, 1326 struct ldb_request *parent); 1327 1328 /** 1329 Add a ldb_control to a ldb_request 1330 1331 \param req the request struct where to add the control 1332 \param oid the object identifier of the control as string 1333 \param critical whether the control should be critical or not 1334 \param data a talloc pointer to the control specific data 1335 1336 \return result code (LDB_SUCCESS on success, or a failure code) 1337 */ 1338 int ldb_request_add_control(struct ldb_request *req, const char *oid, bool critical, void *data); 1339 1340 /** 1341 replace a ldb_control in a ldb_request 1342 1343 \param req the request struct where to add the control 1344 \param oid the object identifier of the control as string 1345 \param critical whether the control should be critical or not 1346 \param data a talloc pointer to the control specific data 1347 1348 \return result code (LDB_SUCCESS on success, or a failure code) 1349 */ 1350 int ldb_request_replace_control(struct ldb_request *req, const char *oid, bool critical, void *data); 1351 1352 /** 1353 check if a control with the specified "oid" exist and return it 1354 \param req the request struct where to add the control 1355 \param oid the object identifier of the control as string 1356 1357 \return the control, NULL if not found 1358 */ 1359 struct ldb_control *ldb_request_get_control(struct ldb_request *req, const char *oid); 1360 1361 /** 1362 check if a control with the specified "oid" exist and return it 1363 \param rep the reply struct where to add the control 1364 \param oid the object identifier of the control as string 1365 1366 \return the control, NULL if not found 1367 */ 1368 struct ldb_control *ldb_reply_get_control(struct ldb_reply *rep, const char *oid); 1369 1370 /** 1371 Search the database 1372 1373 This function searches the database, and returns 1374 records that match an LDAP-like search expression 1375 1376 \param ldb the context associated with the database (from ldb_init()) 1377 \param mem_ctx the memory context to use for the request and the results 1378 \param result the return result 1379 \param base the Base Distinguished Name for the query (use ldb_dn_new() for an empty one) 1380 \param scope the search scope for the query 1381 \param attrs the search attributes for the query (pass NULL if none required) 1382 \param exp_fmt the search expression to use for this query (printf like) 1383 1384 \return result code (LDB_SUCCESS on success, or a failure code) 1385 1386 \note use talloc_free() to free the ldb_result returned 1387 */ 1388 int ldb_search(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, 1389 struct ldb_result **result, struct ldb_dn *base, 1390 enum ldb_scope scope, const char * const *attrs, 1391 const char *exp_fmt, ...) PRINTF_ATTRIBUTE(7,8); 1392 1393 /** 1394 Add a record to the database. 1395 1396 This function adds a record to the database. This function will fail 1397 if a record with the specified class and key already exists in the 1398 database. 1399 1400 \param ldb the context associated with the database (from 1401 ldb_init()) 1402 \param message the message containing the record to add. 1403 1404 \return result code (LDB_SUCCESS if the record was added, otherwise 1405 a failure code) 1406 */ 1407 int ldb_add(struct ldb_context *ldb, 1408 const struct ldb_message *message); 1409 1410 /** 1411 Modify the specified attributes of a record 1412 1413 This function modifies a record that is in the database. 1414 1415 \param ldb the context associated with the database (from 1416 ldb_init()) 1417 \param message the message containing the changes required. 1418 1419 \return result code (LDB_SUCCESS if the record was modified as 1420 requested, otherwise a failure code) 1421 */ 1422 int ldb_modify(struct ldb_context *ldb, 1423 const struct ldb_message *message); 1424 1425 /** 1426 Rename a record in the database 1427 1428 This function renames a record in the database. 1429 1430 \param ldb the context associated with the database (from 1431 ldb_init()) 1432 \param olddn the DN for the record to be renamed. 1433 \param newdn the new DN 1434 1435 \return result code (LDB_SUCCESS if the record was renamed as 1436 requested, otherwise a failure code) 1437 */ 1438 int ldb_rename(struct ldb_context *ldb, struct ldb_dn *olddn, struct ldb_dn *newdn); 1439 1440 /** 1441 Delete a record from the database 1442 1443 This function deletes a record from the database. 1444 1445 \param ldb the context associated with the database (from 1446 ldb_init()) 1447 \param dn the DN for the record to be deleted. 1448 1449 \return result code (LDB_SUCCESS if the record was deleted, 1450 otherwise a failure code) 1451 */ 1452 int ldb_delete(struct ldb_context *ldb, struct ldb_dn *dn); 1453 1454 /** 1455 The default async extended operation callback function 1456 1457 \param req the request we are callback of 1458 \param ares a single reply from the async core 1459 1460 \return result code (LDB_SUCCESS on success, or a failure code) 1461 1462 \note this function expects req->context to always be an struct ldb_result pointer 1463 AND a talloc context, this function will steal on the context each message 1464 from the ares reply passed on by the async core so that in the end all the 1465 messages will be in the context (ldb_result) memory tree. 1466 Freeing the passed context (ldb_result tree) will free all the resources 1467 (the request need to be freed separately and the result doe not depend on the 1468 request that can be freed as sson as the search request is finished) 1469 */ 1470 1471 int ldb_extended_default_callback(struct ldb_request *req, struct ldb_reply *ares); 1472 1473 1474 /** 1475 Helper function to build a extended request 1476 1477 \param ret_req the request structure is returned here (talloced on mem_ctx) 1478 \param ldb the context associated with the database (from ldb_init()) 1479 \param mem_ctx a talloc memory context (used as parent of ret_req) 1480 \param oid the OID of the extended operation. 1481 \param data a void pointer a the extended operation specific parameters, 1482 it needs to be NULL or a valid talloc pointer! talloc_get_type() will be used on it 1483 \param controls an array of controls 1484 \param context the callback function context 1485 \param the callback function to handle the async replies 1486 \param the parent request if any 1487 1488 \return result code (LDB_SUCCESS on success, or a failure code) 1489 */ 1490 int ldb_build_extended_req(struct ldb_request **ret_req, 1491 struct ldb_context *ldb, 1492 TALLOC_CTX *mem_ctx, 1493 const char *oid, 1494 void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */ 1495 struct ldb_control **controls, 1496 void *context, 1497 ldb_request_callback_t callback, 1498 struct ldb_request *parent); 1499 1500 /** 1501 call an extended operation 1502 1503 \param ldb the context associated with the database (from ldb_init()) 1504 \param oid the OID of the extended operation. 1505 \param data a void pointer a the extended operation specific parameters, 1506 it needs to be NULL or a valid talloc pointer! talloc_get_type() will be used on it 1507 \param res the result of the extended operation 1508 1509 \return result code (LDB_SUCCESS if the extended operation returned fine, 1510 otherwise a failure code) 1511 */ 1512 int ldb_extended(struct ldb_context *ldb, 1513 const char *oid, 1514 void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */ 1515 struct ldb_result **res); 1516 1517 /** 1518 Obtain current/next database sequence number 1519 */ 1520 int ldb_sequence_number(struct ldb_context *ldb, enum ldb_sequence_type type, uint64_t *seq_num); 1521 1522 /** 1523 start a transaction 1524 */ 1525 int ldb_transaction_start(struct ldb_context *ldb); 1526 1527 /** 1528 first phase of two phase commit 1529 */ 1530 int ldb_transaction_prepare_commit(struct ldb_context *ldb); 1531 1532 /** 1533 commit a transaction 1534 */ 1535 int ldb_transaction_commit(struct ldb_context *ldb); 1536 1537 /** 1538 cancel a transaction 1539 */ 1540 int ldb_transaction_cancel(struct ldb_context *ldb); 1541 1542 /* 1543 cancel a transaction with no error if no transaction is pending 1544 used when we fork() to clear any parent transactions 1545 */ 1546 int ldb_transaction_cancel_noerr(struct ldb_context *ldb); 1547 1548 1549 /** 1550 return extended error information from the last call 1551 */ 1552 const char *ldb_errstring(struct ldb_context *ldb); 1553 1554 /** 1555 return a string explaining what a ldb error constant means 1556 */ 1557 const char *ldb_strerror(int ldb_err); 1558 1559 /** 1560 setup the default utf8 functions 1561 FIXME: these functions do not yet handle utf8 1562 */ 1563 void ldb_set_utf8_default(struct ldb_context *ldb); 1564 1565 /** 1566 Casefold a string 1567 1568 \param ldb the ldb context 1569 \param mem_ctx the memory context to allocate the result string 1570 memory from. 1571 \param s the string that is to be folded 1572 \return a copy of the string, converted to upper case 1573 1574 \note The default function is not yet UTF8 aware. Provide your own 1575 set of functions through ldb_set_utf8_fns() 1576 */ 1577 char *ldb_casefold(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *s, size_t n); 1578 1579 /** 1580 Check the attribute name is valid according to rfc2251 1581 \param s the string to check 1582 1583 \return 1 if the name is ok 1584 */ 1585 int ldb_valid_attr_name(const char *s); 1586 1587 /* 1588 ldif manipulation functions 1589 */ 1590 1591 /** 1592 Write an LDIF message 1593 1594 This function writes an LDIF message using a caller supplied write 1595 function. 1596 1597 \param ldb the ldb context (from ldb_init()) 1598 \param fprintf_fn a function pointer for the write function. This must take 1599 a private data pointer, followed by a format string, and then a variable argument 1600 list. 1601 \param private_data pointer that will be provided back to the write 1602 function. This is useful for maintaining state or context. 1603 \param ldif the message to write out 1604 1605 \return the total number of bytes written, or an error code as returned 1606 from the write function. 1607 1608 \sa ldb_ldif_write_file for a more convenient way to write to a 1609 file stream. 1610 1611 \sa ldb_ldif_read for the reader equivalent to this function. 1612 */ 1613 int ldb_ldif_write(struct ldb_context *ldb, 1614 int (*fprintf_fn)(void *, const char *, ...) PRINTF_ATTRIBUTE(2,3), 1615 void *private_data, 1616 const struct ldb_ldif *ldif); 1617 1618 /** 1619 Clean up an LDIF message 1620 1621 This function cleans up a LDIF message read using ldb_ldif_read() 1622 or related functions (such as ldb_ldif_read_string() and 1623 ldb_ldif_read_file(). 1624 1625 \param ldb the ldb context (from ldb_init()) 1626 \param msg the message to clean up and free 1627 1628 */ 1629 void ldb_ldif_read_free(struct ldb_context *ldb, struct ldb_ldif *msg); 1630 1631 /** 1632 Read an LDIF message 1633 1634 This function creates an LDIF message using a caller supplied read 1635 function. 1636 1637 \param ldb the ldb context (from ldb_init()) 1638 \param fgetc_fn a function pointer for the read function. This must 1639 take a private data pointer, and must return a pointer to an 1640 integer corresponding to the next byte read (or EOF if there is no 1641 more data to be read). 1642 \param private_data pointer that will be provided back to the read 1643 function. This is udeful for maintaining state or context. 1644 1645 \return the LDIF message that has been read in 1646 1647 \note You must free the LDIF message when no longer required, using 1648 ldb_ldif_read_free(). 1649 1650 \sa ldb_ldif_read_file for a more convenient way to read from a 1651 file stream. 1652 1653 \sa ldb_ldif_read_string for a more convenient way to read from a 1654 string (char array). 1655 1656 \sa ldb_ldif_write for the writer equivalent to this function. 1657 */ 1658 struct ldb_ldif *ldb_ldif_read(struct ldb_context *ldb, 1659 int (*fgetc_fn)(void *), void *private_data); 1660 1661 /** 1662 Read an LDIF message from a file 1663 1664 This function reads the next LDIF message from the contents of a 1665 file stream. If you want to get all of the LDIF messages, you will 1666 need to repeatedly call this function, until it returns NULL. 1667 1668 \param ldb the ldb context (from ldb_init()) 1669 \param f the file stream to read from (typically from fdopen()) 1670 1671 \sa ldb_ldif_read_string for an equivalent function that will read 1672 from a string (char array). 1673 1674 \sa ldb_ldif_write_file for the writer equivalent to this function. 1675 1676 */ 1677 struct ldb_ldif *ldb_ldif_read_file(struct ldb_context *ldb, FILE *f); 1678 1679 /** 1680 Read an LDIF message from a string 1681 1682 This function reads the next LDIF message from the contents of a char 1683 array. If you want to get all of the LDIF messages, you will need 1684 to repeatedly call this function, until it returns NULL. 1685 1686 \param ldb the ldb context (from ldb_init()) 1687 \param s pointer to the char array to read from 1688 1689 \sa ldb_ldif_read_file for an equivalent function that will read 1690 from a file stream. 1691 1692 \sa ldb_ldif_write for a more general (arbitrary read function) 1693 version of this function. 1694 */ 1695 struct ldb_ldif *ldb_ldif_read_string(struct ldb_context *ldb, const char **s); 1696 1697 /** 1698 Parse a modrdn LDIF message from a struct ldb_message 1699 1700 \param ldb the ldb context (from ldb_init()) 1701 \param ldif the preparsed LDIF chunk (from ldb_ldif_read()) 1702 1703 \param mem_ctx the memory context that's used for return values 1704 1705 \param olddn the old dn as struct ldb_dn, if not needed pass NULL 1706 \param newrdn the new rdn as struct ldb_dn, if not needed pass NULL 1707 \param deleteoldrdn the deleteoldrdn value as bool, if not needed pass NULL 1708 \param newsuperior the newsuperior dn as struct ldb_dn, if not needed pass NULL 1709 *newsuperior can be NULL as it is optional in the LDIF 1710 \param newdn the full constructed new dn as struct ldb_dn, if not needed pass NULL 1711 1712 */ 1713 int ldb_ldif_parse_modrdn(struct ldb_context *ldb, 1714 const struct ldb_ldif *ldif, 1715 TALLOC_CTX *mem_ctx, 1716 struct ldb_dn **olddn, 1717 struct ldb_dn **newrdn, 1718 bool *deleteoldrdn, 1719 struct ldb_dn **newsuperior, 1720 struct ldb_dn **newdn); 1721 1722 /** 1723 Write an LDIF message to a file 1724 1725 \param ldb the ldb context (from ldb_init()) 1726 \param f the file stream to write to (typically from fdopen()) 1727 \param msg the message to write out 1728 1729 \return the total number of bytes written, or a negative error code 1730 1731 \sa ldb_ldif_read_file for the reader equivalent to this function. 1732 */ 1733 int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif *msg); 1734 1735 /** 1736 Write an LDIF message to a string 1737 1738 \param ldb the ldb context (from ldb_init()) 1739 \param mem_ctx the talloc context on which to attach the string) 1740 \param msg the message to write out 1741 1742 \return the string containing the LDIF, or NULL on error 1743 1744 \sa ldb_ldif_read_string for the reader equivalent to this function. 1745 */ 1746 char * ldb_ldif_write_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, 1747 const struct ldb_ldif *msg); 1748 1749 1750 /** 1751 Write an LDB message to a string 1752 1753 \param ldb the ldb context (from ldb_init()) 1754 \param mem_ctx the talloc context on which to attach the string) 1755 \param changetype LDB_CHANGETYPE_ADD or LDB_CHANGETYPE_MODIFY 1756 \param msg the message to write out 1757 1758 \return the string containing the LDIF, or NULL on error 1759 1760 \sa ldb_ldif_message_redacted_string for a safer version of this 1761 function 1762 */ 1763 char *ldb_ldif_message_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, 1764 enum ldb_changetype changetype, 1765 const struct ldb_message *msg); 1766 1767 /** 1768 Write an LDB message to a string 1769 1770 \param ldb the ldb context (from ldb_init()) 1771 \param mem_ctx the talloc context on which to attach the string) 1772 \param changetype LDB_CHANGETYPE_ADD or LDB_CHANGETYPE_MODIFY 1773 \param msg the message to write out 1774 1775 \return the string containing the LDIF, or NULL on error, but 1776 with secret attributes redacted 1777 1778 \note The secret attributes are specified in a 1779 'const char * const *' within the LDB_SECRET_ATTRIBUTE_LIST 1780 opaque set on the ldb 1781 1782 \sa ldb_ldif_message_string for an exact representiation of the 1783 message as LDIF 1784 */ 1785 char *ldb_ldif_message_redacted_string(struct ldb_context *ldb, 1786 TALLOC_CTX *mem_ctx, 1787 enum ldb_changetype changetype, 1788 const struct ldb_message *msg); 1789 1790 1791 /** 1792 Base64 encode a buffer 1793 1794 \param mem_ctx the memory context that the result is allocated 1795 from. 1796 \param buf pointer to the array that is to be encoded 1797 \param len the number of elements in the array to be encoded 1798 1799 \return pointer to an array containing the encoded data 1800 1801 \note The caller is responsible for freeing the result 1802 */ 1803 char *ldb_base64_encode(TALLOC_CTX *mem_ctx, const char *buf, int len); 1804 1805 /** 1806 Base64 decode a buffer 1807 1808 This function decodes a base64 encoded string in place. 1809 1810 \param s the string to decode. 1811 1812 \return the length of the returned (decoded) string. 1813 1814 \note the string is null terminated, but the null terminator is not 1815 included in the length. 1816 */ 1817 int ldb_base64_decode(char *s); 1818 1819 /* The following definitions come from lib/ldb/common/ldb_dn.c */ 1820 1821 /** 1822 Get the linear form of a DN (without any extended components) 1823 1824 \param dn The DN to linearize 1825 */ 1826 1827 const char *ldb_dn_get_linearized(struct ldb_dn *dn); 1828 1829 /** 1830 Allocate a copy of the linear form of a DN (without any extended components) onto the supplied memory context 1831 1832 \param dn The DN to linearize 1833 \param mem_ctx TALLOC context to return result on 1834 */ 1835 1836 char *ldb_dn_alloc_linearized(TALLOC_CTX *mem_ctx, struct ldb_dn *dn); 1837 1838 /** 1839 Get the linear form of a DN (with any extended components) 1840 1841 \param mem_ctx TALLOC context to return result on 1842 \param dn The DN to linearize 1843 \param mode Style of extended DN to return (0 is HEX representation of binary form, 1 is a string form) 1844 */ 1845 char *ldb_dn_get_extended_linearized(TALLOC_CTX *mem_ctx, struct ldb_dn *dn, int mode); 1846 const struct ldb_val *ldb_dn_get_extended_component(struct ldb_dn *dn, const char *name); 1847 int ldb_dn_set_extended_component(struct ldb_dn *dn, const char *name, const struct ldb_val *val); 1848 void ldb_dn_extended_filter(struct ldb_dn *dn, const char * const *accept_list); 1849 void ldb_dn_remove_extended_components(struct ldb_dn *dn); 1850 bool ldb_dn_has_extended(struct ldb_dn *dn); 1851 1852 int ldb_dn_extended_add_syntax(struct ldb_context *ldb, 1853 unsigned flags, 1854 const struct ldb_dn_extended_syntax *syntax); 1855 1856 /** 1857 Allocate a new DN from a string 1858 1859 \param mem_ctx TALLOC context to return resulting ldb_dn structure on 1860 \param dn The new DN 1861 1862 \note The DN will not be parsed at this time. Use ldb_dn_validate to tell if the DN is syntacticly correct 1863 */ 1864 1865 struct ldb_dn *ldb_dn_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *dn); 1866 /** 1867 Allocate a new DN from a printf style format string and arguments 1868 1869 \param mem_ctx TALLOC context to return resulting ldb_dn structure on 1870 \param new_fms The new DN as a format string (plus arguments) 1871 1872 \note The DN will not be parsed at this time. Use ldb_dn_validate to tell if the DN is syntacticly correct 1873 */ 1874 1875 struct ldb_dn *ldb_dn_new_fmt(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *new_fmt, ...) PRINTF_ATTRIBUTE(3,4); 1876 /** 1877 Allocate a new DN from a struct ldb_val (useful to avoid buffer overrun) 1878 1879 \param mem_ctx TALLOC context to return resulting ldb_dn structure on 1880 \param dn The new DN 1881 1882 \note The DN will not be parsed at this time. Use ldb_dn_validate to tell if the DN is syntacticly correct 1883 */ 1884 1885 struct ldb_dn *ldb_dn_from_ldb_val(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const struct ldb_val *strdn); 1886 1887 /** 1888 Determine if this DN is syntactically valid 1889 1890 \param dn The DN to validate 1891 */ 1892 1893 bool ldb_dn_validate(struct ldb_dn *dn); 1894 1895 char *ldb_dn_escape_value(TALLOC_CTX *mem_ctx, struct ldb_val value); 1896 const char *ldb_dn_get_casefold(struct ldb_dn *dn); 1897 char *ldb_dn_alloc_casefold(TALLOC_CTX *mem_ctx, struct ldb_dn *dn); 1898 1899 int ldb_dn_compare_base(struct ldb_dn *base, struct ldb_dn *dn); 1900 int ldb_dn_compare(struct ldb_dn *edn0, struct ldb_dn *edn1); 1901 1902 bool ldb_dn_add_base(struct ldb_dn *dn, struct ldb_dn *base); 1903 bool ldb_dn_add_base_fmt(struct ldb_dn *dn, const char *base_fmt, ...) PRINTF_ATTRIBUTE(2,3); 1904 bool ldb_dn_add_child(struct ldb_dn *dn, struct ldb_dn *child); 1905 bool ldb_dn_add_child_fmt(struct ldb_dn *dn, const char *child_fmt, ...) PRINTF_ATTRIBUTE(2,3); 1906 bool ldb_dn_remove_base_components(struct ldb_dn *dn, unsigned int num); 1907 bool ldb_dn_remove_child_components(struct ldb_dn *dn, unsigned int num); 1908 bool ldb_dn_add_child_val(struct ldb_dn *dn, 1909 const char *rdn, 1910 struct ldb_val value); 1911 1912 struct ldb_dn *ldb_dn_copy(TALLOC_CTX *mem_ctx, struct ldb_dn *dn); 1913 struct ldb_dn *ldb_dn_get_parent(TALLOC_CTX *mem_ctx, struct ldb_dn *dn); 1914 char *ldb_dn_canonical_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn); 1915 char *ldb_dn_canonical_ex_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn); 1916 int ldb_dn_get_comp_num(struct ldb_dn *dn); 1917 int ldb_dn_get_extended_comp_num(struct ldb_dn *dn); 1918 const char *ldb_dn_get_component_name(struct ldb_dn *dn, unsigned int num); 1919 const struct ldb_val *ldb_dn_get_component_val(struct ldb_dn *dn, unsigned int num); 1920 const char *ldb_dn_get_rdn_name(struct ldb_dn *dn); 1921 const struct ldb_val *ldb_dn_get_rdn_val(struct ldb_dn *dn); 1922 int ldb_dn_set_component(struct ldb_dn *dn, int num, const char *name, const struct ldb_val val); 1923 1924 bool ldb_dn_is_valid(struct ldb_dn *dn); 1925 bool ldb_dn_is_special(struct ldb_dn *dn); 1926 bool ldb_dn_check_special(struct ldb_dn *dn, const char *check); 1927 bool ldb_dn_is_null(struct ldb_dn *dn); 1928 int ldb_dn_update_components(struct ldb_dn *dn, const struct ldb_dn *ref_dn); 1929 1930 1931 /** 1932 Compare two attributes 1933 1934 This function compares to attribute names. Note that this is a 1935 case-insensitive comparison. 1936 1937 \param a the first attribute name to compare 1938 \param b the second attribute name to compare 1939 1940 \return 0 if the attribute names are the same, or only differ in 1941 case; non-zero if there are any differences 1942 1943 attribute names are restricted by rfc2251 so using 1944 strcasecmp and toupper here is ok. 1945 return 0 for match 1946 */ 1947 #define ldb_attr_cmp(a, b) strcasecmp(a, b) 1948 char *ldb_attr_casefold(TALLOC_CTX *mem_ctx, const char *s); 1949 int ldb_attr_dn(const char *attr); 1950 1951 /** 1952 Create an empty message 1953 1954 \param mem_ctx the memory context to create in. You can pass NULL 1955 to get the top level context, however the ldb context (from 1956 ldb_init()) may be a better choice 1957 */ 1958 struct ldb_message *ldb_msg_new(TALLOC_CTX *mem_ctx); 1959 1960 /** 1961 Find an element within an message 1962 */ 1963 struct ldb_message_element *ldb_msg_find_element(const struct ldb_message *msg, 1964 const char *attr_name); 1965 1966 /** 1967 Compare two ldb_val values 1968 1969 \param v1 first ldb_val structure to be tested 1970 \param v2 second ldb_val structure to be tested 1971 1972 \return 1 for a match, 0 if there is any difference 1973 */ 1974 int ldb_val_equal_exact(const struct ldb_val *v1, const struct ldb_val *v2); 1975 1976 /** 1977 find a value within an ldb_message_element 1978 1979 \param el the element to search 1980 \param val the value to search for 1981 1982 \note This search is case sensitive 1983 */ 1984 struct ldb_val *ldb_msg_find_val(const struct ldb_message_element *el, 1985 struct ldb_val *val); 1986 1987 /** 1988 add a new empty element to a ldb_message 1989 */ 1990 int ldb_msg_add_empty(struct ldb_message *msg, 1991 const char *attr_name, 1992 int flags, 1993 struct ldb_message_element **return_el); 1994 1995 /** 1996 add a element to a ldb_message 1997 */ 1998 int ldb_msg_add(struct ldb_message *msg, 1999 const struct ldb_message_element *el, 2000 int flags); 2001 int ldb_msg_add_value(struct ldb_message *msg, 2002 const char *attr_name, 2003 const struct ldb_val *val, 2004 struct ldb_message_element **return_el); 2005 int ldb_msg_add_steal_value(struct ldb_message *msg, 2006 const char *attr_name, 2007 struct ldb_val *val); 2008 int ldb_msg_add_steal_string(struct ldb_message *msg, 2009 const char *attr_name, char *str); 2010 int ldb_msg_add_string(struct ldb_message *msg, 2011 const char *attr_name, const char *str); 2012 int ldb_msg_add_linearized_dn(struct ldb_message *msg, const char *attr_name, 2013 struct ldb_dn *dn); 2014 int ldb_msg_add_fmt(struct ldb_message *msg, 2015 const char *attr_name, const char *fmt, ...) PRINTF_ATTRIBUTE(3,4); 2016 2017 /** 2018 compare two message elements - return 0 on match 2019 */ 2020 int ldb_msg_element_compare(struct ldb_message_element *el1, 2021 struct ldb_message_element *el2); 2022 int ldb_msg_element_compare_name(struct ldb_message_element *el1, 2023 struct ldb_message_element *el2); 2024 2025 /** 2026 Find elements in a message. 2027 2028 This function finds elements and converts to a specific type, with 2029 a give default value if not found. Assumes that elements are 2030 single valued. 2031 */ 2032 const struct ldb_val *ldb_msg_find_ldb_val(const struct ldb_message *msg, const char *attr_name); 2033 int ldb_msg_find_attr_as_int(const struct ldb_message *msg, 2034 const char *attr_name, 2035 int default_value); 2036 unsigned int ldb_msg_find_attr_as_uint(const struct ldb_message *msg, 2037 const char *attr_name, 2038 unsigned int default_value); 2039 int64_t ldb_msg_find_attr_as_int64(const struct ldb_message *msg, 2040 const char *attr_name, 2041 int64_t default_value); 2042 uint64_t ldb_msg_find_attr_as_uint64(const struct ldb_message *msg, 2043 const char *attr_name, 2044 uint64_t default_value); 2045 double ldb_msg_find_attr_as_double(const struct ldb_message *msg, 2046 const char *attr_name, 2047 double default_value); 2048 int ldb_msg_find_attr_as_bool(const struct ldb_message *msg, 2049 const char *attr_name, 2050 int default_value); 2051 const char *ldb_msg_find_attr_as_string(const struct ldb_message *msg, 2052 const char *attr_name, 2053 const char *default_value); 2054 2055 struct ldb_dn *ldb_msg_find_attr_as_dn(struct ldb_context *ldb, 2056 TALLOC_CTX *mem_ctx, 2057 const struct ldb_message *msg, 2058 const char *attr_name); 2059 2060 void ldb_msg_sort_elements(struct ldb_message *msg); 2061 2062 struct ldb_message *ldb_msg_copy_shallow(TALLOC_CTX *mem_ctx, 2063 const struct ldb_message *msg); 2064 struct ldb_message *ldb_msg_copy(TALLOC_CTX *mem_ctx, 2065 const struct ldb_message *msg); 2066 2067 /* 2068 * ldb_msg_canonicalize() is now depreciated 2069 * Please use ldb_msg_normalize() instead 2070 * 2071 * NOTE: Returned ldb_message object is allocated 2072 * into *ldb's context. Callers are recommended 2073 * to steal the returned object into a TALLOC_CTX 2074 * with short lifetime. 2075 */ 2076 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb, 2077 const struct ldb_message *msg) _DEPRECATED_; 2078 2079 int ldb_msg_normalize(struct ldb_context *ldb, 2080 TALLOC_CTX *mem_ctx, 2081 const struct ldb_message *msg, 2082 struct ldb_message **_msg_out); 2083 2084 2085 /* 2086 * ldb_msg_diff() is now depreciated 2087 * Please use ldb_msg_difference() instead 2088 * 2089 * NOTE: Returned ldb_message object is allocated 2090 * into *ldb's context. Callers are recommended 2091 * to steal the returned object into a TALLOC_CTX 2092 * with short lifetime. 2093 */ 2094 struct ldb_message *ldb_msg_diff(struct ldb_context *ldb, 2095 struct ldb_message *msg1, 2096 struct ldb_message *msg2) _DEPRECATED_; 2097 2098 /** 2099 * return a ldb_message representing the differences between msg1 and msg2. 2100 * If you then use this in a ldb_modify() call, 2101 * it can be used to save edits to a message 2102 * 2103 * Result message is constructed as follows: 2104 * - LDB_FLAG_MOD_ADD - elements found only in msg2 2105 * - LDB_FLAG_MOD_REPLACE - elements in msg2 that have 2106 * different value in msg1 2107 * Value for msg2 element is used 2108 * - LDB_FLAG_MOD_DELETE - elements found only in msg2 2109 * 2110 * @return LDB_SUCCESS or LDB_ERR_OPERATIONS_ERROR 2111 */ 2112 int ldb_msg_difference(struct ldb_context *ldb, 2113 TALLOC_CTX *mem_ctx, 2114 struct ldb_message *msg1, 2115 struct ldb_message *msg2, 2116 struct ldb_message **_msg_out); 2117 2118 /** 2119 Tries to find a certain string attribute in a message 2120 2121 \param msg the message to check 2122 \param name attribute name 2123 \param value attribute value 2124 2125 \return 1 on match and 0 otherwise. 2126 */ 2127 int ldb_msg_check_string_attribute(const struct ldb_message *msg, 2128 const char *name, 2129 const char *value); 2130 2131 /** 2132 Integrity check an ldb_message 2133 2134 This function performs basic sanity / integrity checks on an 2135 ldb_message. 2136 2137 \param ldb context in which to perform the checks 2138 \param msg the message to check 2139 2140 \return LDB_SUCCESS if the message is OK, or a non-zero error code 2141 (one of LDB_ERR_INVALID_DN_SYNTAX, LDB_ERR_ENTRY_ALREADY_EXISTS or 2142 LDB_ERR_INVALID_ATTRIBUTE_SYNTAX) if there is a problem with a 2143 message. 2144 */ 2145 int ldb_msg_sanity_check(struct ldb_context *ldb, 2146 const struct ldb_message *msg); 2147 2148 /** 2149 Duplicate an ldb_val structure 2150 2151 This function copies an ldb value structure. 2152 2153 \param mem_ctx the memory context that the duplicated value will be 2154 allocated from 2155 \param v the ldb_val to be duplicated. 2156 2157 \return the duplicated ldb_val structure. 2158 */ 2159 struct ldb_val ldb_val_dup(TALLOC_CTX *mem_ctx, const struct ldb_val *v); 2160 2161 /** 2162 this allows the user to set a debug function for error reporting 2163 */ 2164 int ldb_set_debug(struct ldb_context *ldb, 2165 void (*debug)(void *context, enum ldb_debug_level level, 2166 const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0), 2167 void *context); 2168 2169 /** 2170 this allows the user to set custom utf8 function for error reporting 2171 */ 2172 void ldb_set_utf8_fns(struct ldb_context *ldb, 2173 void *context, 2174 char *(*casefold)(void *, void *, const char *, size_t n)); 2175 2176 /** 2177 this sets up debug to print messages on stderr 2178 */ 2179 int ldb_set_debug_stderr(struct ldb_context *ldb); 2180 2181 /* control backend specific opaque values */ 2182 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value); 2183 void *ldb_get_opaque(struct ldb_context *ldb, const char *name); 2184 2185 const char **ldb_attr_list_copy(TALLOC_CTX *mem_ctx, const char * const *attrs); 2186 const char **ldb_attr_list_copy_add(TALLOC_CTX *mem_ctx, const char * const *attrs, const char *new_attr); 2187 int ldb_attr_in_list(const char * const *attrs, const char *attr); 2188 2189 int ldb_msg_rename_attr(struct ldb_message *msg, const char *attr, const char *replace); 2190 int ldb_msg_copy_attr(struct ldb_message *msg, const char *attr, const char *replace); 2191 void ldb_msg_remove_attr(struct ldb_message *msg, const char *attr); 2192 void ldb_msg_remove_element(struct ldb_message *msg, struct ldb_message_element *el); 2193 2194 2195 void ldb_parse_tree_attr_replace(struct ldb_parse_tree *tree, 2196 const char *attr, 2197 const char *replace); 2198 2199 /* 2200 shallow copy a tree - copying only the elements array so that the caller 2201 can safely add new elements without changing the message 2202 */ 2203 struct ldb_parse_tree *ldb_parse_tree_copy_shallow(TALLOC_CTX *mem_ctx, 2204 const struct ldb_parse_tree *ot); 2205 2206 /** 2207 Convert a time structure to a string 2208 2209 This function converts a time_t structure to an LDAP formatted 2210 GeneralizedTime string. 2211 2212 \param mem_ctx the memory context to allocate the return string in 2213 \param t the time structure to convert 2214 2215 \return the formatted string, or NULL if the time structure could 2216 not be converted 2217 */ 2218 char *ldb_timestring(TALLOC_CTX *mem_ctx, time_t t); 2219 2220 /** 2221 Convert a string to a time structure 2222 2223 This function converts an LDAP formatted GeneralizedTime string 2224 to a time_t structure. 2225 2226 \param s the string to convert 2227 2228 \return the time structure, or 0 if the string cannot be converted 2229 */ 2230 time_t ldb_string_to_time(const char *s); 2231 2232 /** 2233 convert a LDAP GeneralizedTime string in ldb_val format to a 2234 time_t. 2235 */ 2236 int ldb_val_to_time(const struct ldb_val *v, time_t *t); 2237 2238 /** 2239 Convert a time structure to a string 2240 2241 This function converts a time_t structure to an LDAP formatted 2242 UTCTime string. 2243 2244 \param mem_ctx the memory context to allocate the return string in 2245 \param t the time structure to convert 2246 2247 \return the formatted string, or NULL if the time structure could 2248 not be converted 2249 */ 2250 char *ldb_timestring_utc(TALLOC_CTX *mem_ctx, time_t t); 2251 2252 /** 2253 Convert a string to a time structure 2254 2255 This function converts an LDAP formatted UTCTime string 2256 to a time_t structure. 2257 2258 \param s the string to convert 2259 2260 \return the time structure, or 0 if the string cannot be converted 2261 */ 2262 time_t ldb_string_utc_to_time(const char *s); 2263 2264 2265 void ldb_qsort (void *const pbase, size_t total_elems, size_t size, void *opaque, ldb_qsort_cmp_fn_t cmp); 2266 2267 #ifndef discard_const 2268 #define discard_const(ptr) ((void *)((uintptr_t)(ptr))) 2269 #endif 2270 2271 /* 2272 a wrapper around ldb_qsort() that ensures the comparison function is 2273 type safe. This will produce a compilation warning if the types 2274 don't match 2275 */ 2276 #define LDB_TYPESAFE_QSORT(base, numel, opaque, comparison) \ 2277 do { \ 2278 if (numel > 1) { \ 2279 ldb_qsort(base, numel, sizeof((base)[0]), discard_const(opaque), (ldb_qsort_cmp_fn_t)comparison); \ 2280 comparison(&((base)[0]), &((base)[1]), opaque); \ 2281 } \ 2282 } while (0) 2283 2284 /* allow ldb to also call TYPESAFE_QSORT() */ 2285 #ifndef TYPESAFE_QSORT 2286 #define TYPESAFE_QSORT(base, numel, comparison) \ 2287 do { \ 2288 if (numel > 1) { \ 2289 qsort(base, numel, sizeof((base)[0]), (int (*)(const void *, const void *))comparison); \ 2290 comparison(&((base)[0]), &((base)[1])); \ 2291 } \ 2292 } while (0) 2293 #endif 2294 2295 2296 2297 /** 2298 Convert a control into its string representation. 2299 2300 \param mem_ctx TALLOC context to return result on, and to allocate error_string on 2301 \param control A struct ldb_control to convert 2302 2303 \return string representation of the control 2304 */ 2305 char* ldb_control_to_string(TALLOC_CTX *mem_ctx, const struct ldb_control *control); 2306 /** 2307 Convert a string representing a control into a ldb_control structure 2308 2309 \param ldb LDB context 2310 \param mem_ctx TALLOC context to return result on, and to allocate error_string on 2311 \param control_strings A string-formatted control 2312 2313 \return a ldb_control element 2314 */ 2315 struct ldb_control *ldb_parse_control_from_string(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *control_strings); 2316 /** 2317 Convert an array of string represention of a control into an array of ldb_control structures 2318 2319 \param ldb LDB context 2320 \param mem_ctx TALLOC context to return result on, and to allocate error_string on 2321 \param control_strings Array of string-formatted controls 2322 2323 \return array of ldb_control elements 2324 */ 2325 struct ldb_control **ldb_parse_control_strings(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char **control_strings); 2326 2327 /** 2328 return the ldb flags 2329 */ 2330 unsigned int ldb_get_flags(struct ldb_context *ldb); 2331 2332 /* set the ldb flags */ 2333 void ldb_set_flags(struct ldb_context *ldb, unsigned flags); 2334 2335 2336 struct ldb_dn *ldb_dn_binary_from_ldb_val(TALLOC_CTX *mem_ctx, 2337 struct ldb_context *ldb, 2338 const struct ldb_val *strdn); 2339 2340 int ldb_dn_get_binary(struct ldb_dn *dn, struct ldb_val *val); 2341 int ldb_dn_set_binary(struct ldb_dn *dn, struct ldb_val *val); 2342 2343 /* debugging functions for ldb requests */ 2344 void ldb_req_set_location(struct ldb_request *req, const char *location); 2345 const char *ldb_req_location(struct ldb_request *req); 2346 2347 /* set the location marker on a request handle - used for debugging */ 2348 #define LDB_REQ_SET_LOCATION(req) ldb_req_set_location(req, __location__) 2349 2350 /* 2351 minimise a DN. The caller must pass in a validated DN. 2352 2353 If the DN has an extended component then only the first extended 2354 component is kept, the DN string is stripped. 2355 2356 The existing dn is modified 2357 */ 2358 bool ldb_dn_minimise(struct ldb_dn *dn); 2359 2360 /* 2361 compare a ldb_val to a string 2362 */ 2363 int ldb_val_string_cmp(const struct ldb_val *v, const char *str); 2364 2365 #endif 2366