INTERNET-DRAFT Haripriya S., Novell 20 July 2000 Expiry: January 20 2001 EntrySelection control for LDAP modify and delete operations on multiple entries 1. Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet Draft expires January 20, 2001. 2. Abstract This document defines an LDAPv3 control that can select multiple entries in a subtree of a container entry for modification or deletion. This control extends the scope of the LDAPv3 modify and delete operations as defined in [RFC 2251]. This control is useful for modifying or deleting multiple entries on the basis of a single selection criterion. This may be useful for maintenance of an LDAP directory having a large number of objects. Example of Usage - This control can be used by client applications who have the need to modify or delete a large number of entries in an LDAP directory based on a selection criterion. One example of such a usage is when two departments in an organization merge. In this case the "department" name or number given to a number of employees need to change, and all the employees in a given department are to be assigned the new "department". Here the EntrySelection control can be used to select the entries to be modified based on the "department" value, and the modify operation can change the "department" value for all the selected entries to the given value. Haripriya S. INTERNET-DRAFT 1 EntrySelection control for LDAP modify and delete on multiple entries, July 2000 The EntrySelection control is useful when a large number of entries have to be modified or deleted, because what can be achieved in 1 LDAP client operation with the EntrySelection control will take a minimum of 1 + n LDAP operations (1 search, n modifies) otherwise. This will save a lot of time and bandwidth, and hence very useful in situations where the clients are connected over low bandwidth and/or high latency links. Also low-end clients which cannot handle a large number of objects, can use this feature. This also prevents cache pollution or false caching, where a large number of search results are returned only to be immediately modified or deleted, thus invalidating cached information for those results. 3. RFC Key Words The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. 4. EntrySelection request control A multi-entry modify or delete operation can be thought of as a combination of a search operation followed by modify or delete operation. The search operation in this case is used to select the entries for modification or deletion. For the purpose of selecting entries, an entry selection control is added. This control will be similar to a search request. The ControlType is , the Criticality field may be TRUE or FALSE, and the controlValue is EntrySelection which is encoded as per the following syntax. EntrySelection ::= SEQUENCE { scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefAliases (0), -- 1, 2 not used -- derefAlways (3) }, timeLimit INTEGER (0 .. maxInt), -- for the search -- optimeLimit INTEGER (0 .. maxInt), -- for the total operation -- errorLimit INTEGER (0 .. maxInt), -- for the operation -- filter Filter, returnFailedDNs [0] BOOLEAN DEFAULT FALSE -- return matched DNs for -- which the operation failed, -- and return codes } The following definitions are the same as the corresponding Haripriya S. INTERNET-DRAFT 2 EntrySelection control for LDAP modify and delete on multiple entries, July 2000 definitions in [RFC 2251] 4.5.1. They are just repeated here for completeness. Filter ::= CHOICE { and [0] SET of Filter, or [1] SET of Filter, not [2] Filter, equalityMatch [3] AttributeValueAssertion, subStrings [4] SubstringFilter, greaterOrEqual [5] AttributeValueAssertion, lessOrEqual [6] AttributeValueAssertion, present [7] AttributeDescription, approxMatch [8] AttributeValueAssertion, extensibleMatch [9] MatchingRuleAssertion } SubstringFilter ::= SEQUENCE { type AttributeDescription, -- at least one must be present substrings SEQUENCE OF CHOICE { initial [0] LDAPString, any [1] LDAPString, final [2] LDAPString } } MatchingRuleAssertion ::= SEQUENCE { matchingRule [1] MatchingRuleOd OPTIONAL, type [2] AttributeDescription OPTIONAL, matchValue [3] AssertionValue, dnAttributes [4] BOOLEAN DEFAULT FALSE } errorLimit: This INTEGER field specifies the number of selected entries on which the modify/delete operation can fail before the server stops the operation and sends the results to the client. optimeLimit: Similar to timeLimit but for the entire operation. returnFailedDNs: This optional field specifies whether or not to return information about all the entries for which the modify or delete operation failed. If this is FALSE or is not present, then only the last error value and the corresponding DN are returned in the LDAPresult message as part of the modify or delete reply. The control is used to select the entries that are to be modified or deleted as per the LDAP request message that this attaches to. This control MUST only be used with an LDAP Modify or Delete request message. The server MUST ignore the control if used with any other message unless the criticality field is set to TRUE. If the criticality field is set to TRUE, then the server MUST return the resultCode unavailableCriticalExtension ( RFC 2251 Section 4.1.12 ). The server MUST list this control as recognized in the supportedControl attribute in the root DSE. Haripriya S. INTERNET-DRAFT 3 EntrySelection control for LDAP modify and delete on multiple entries, July 2000 4.1 EntrySelectionResponse Control This control can be included in a delete or modify result message as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [LDAPv3]. The EntrySelectionResponse is optional in a ModifyResponse or DeleteResponse. The controlType is set to "TBD". The criticality is FALSE (MAY be absent). The controlValue is an OCTET STRING, whose value is the BER encoding of a value of the following sequence. EntrySelectionResponse ::= [1] SEQUENCE { selectResult ENUMERATED { success (0), -- search successful operationsError (1), -- server internal failure -- while attempting to do the -- search for bulk operation timeLimitExceeded (2), -- timelimit exceeded before -- search completed referral (10), -- referral returned for -- further searching adminLimitExceeded(11), -- too many matching entries -- for the server to process undefinedAttributeType(17),-- An attribute type specified -- in EntrySelection filter -- is undefined inappropriateMatching(18),-- Inappropriate matching rule -- in an extendible match busy (51), -- too busy to -- search for entries unwillingToPerform(53), -- unable to process -- matched entries other (80) } failedCount INTEGER (0..maxCount) failedDNs [0] DNList OPTIONAL searchContinuation [1] SearchReference OPTIONAL referral [2] Referral OPTIONAL } DNList ::= SEQUENCE OF LDAPResult SearchReference ::= SEQUENCE OF LDAPURL Referral is already defined in RFC 2251. failedCount: The number of entries on whom the modify or delete failed. failedDNs: The information about all the DNs of the entries on which the modify or delete operation failed. The information includes the DN as well as the resultcode corresponding to the failure. This field is optional and is set only if the request Haripriya S. INTERNET-DRAFT 4 EntrySelection control for LDAP modify and delete on multiple entries, July 2000 control has the returnFailedDNs field set to TRUE. searchContinuation: This field contains the list of URLs that are the continuation references returned by the server for the particular selection. This is a SEQUENCE of type LDAPURL. searchContinuation field must not be returned if the baseDN itself is not present, or returns a referral. This is an optional field. referral: When the baseDN in the request is not available on the server, the server can return a referral if available. This field is also optional. The EntrySelectionResponse control is used to return the appropriate error values to the client. The optional DNList is filled with the list of DNs which matched the EntrySelection criterion, but failed for the LDAP (modify or delete) operation, and their corresponding error codes so that the client can retry as it needs. If there are referrals returned in the search they can also be returned. 4.2 Semantics of the EntrySelection and EntrySelectionResponse Controls The EntrySelection control, will behave just like an LDAP search at the server. The server MUST select all the entries that are selected as per the EntrySelection control, before starting the modify or delete operation on any of the matched entries. If deleting entries, the server MUST make sure that all the child entries in the selected list are processed before their parents are processed for deletion. The server SHOULD NOT process the entries in such a way that it would orphan the entries. The modify or delete operation on each selected entry MUST be done atomically, but the server need not ensure that the modify/delete operation across all selected entries are done as one atomic operation. The atomicity of the entire operation will be the same as if a client first did a search, and then based on the entries selected, gave a series of modify or delete requests. If a client makes changes to some of the entries that are selected by the EntrySelection filter, while the operation is in progress, the combined result of the operations is undefined. If the search timelimit in the EntrySelection control is exceeded before the search is over, only the entries selected will be considered for modification. If the condition of the EntryCriterion evaluates to TRUE with respect to a given DN (either the base DN if the scope is base, or any of the subtree/children DNs if the subtree or onelevel scope is set), then the LDAP server should do the modify or the delete operation that has been specified in the delete or modify request. If the condition evaluates to UNKNOWN or FALSE, then the operation should not be done on the corresponding DN. Haripriya S. INTERNET-DRAFT 5 EntrySelection control for LDAP modify and delete on multiple entries, July 2000 4.3 Errors and Return Codes If modify or delete operations succeed on all the objects where one or more objects are selected, then the LDAP operation MUST return a result code of success. If in addition, no search continuation references are generated and time limit did not exceed during the search, then the EntrySelectionResponse control is NOT returned. (See section 4.3.4). If one or more operations fail, then the error from the last operation will be returned as the result code for the LDAP operation. The EntrySelectionResponse control is also returned, and the searchresult in the control is as per the following decision function, discussed as a pseudo-code in the following subsection section. 4.3.1 Deciding on the return values The server MUST decide what values and error codes to return based on the decision function below, and on the return values of LDAP modify and delete operations. The decision logic to be followed at the server end is discussed as a pseudo-code below, and each tagged branch (eg. // 4.3.1.5 ) represents a sub-section describing a specific decision that must be followed by the server. LDAPopn: The LDAP operation (modify or delete) LDAPopnresult: Result Code of the LDAP operation ( modify or delete). This could be the result of that LDAP operation on a single matched entry, the result codes being as specified in [rescodes]. LDAPopnDN: The DN on which the LDAP operation was done (modify or delete) selectResult: The result code for the search operation due to EntrySelection control. failedDNresult: The result code associated with each entry for which the operation failed to be filled in failedDNs. searchContinuation: the continuation DNs that were returned by the search. The following conditions are possible: if (baseDN does not exist) if (there are no referrals) // 4.3.1.1 LDAPopnresult = noSuchObject LDAPopnDN = BaseDN EntrySelectionResponse control NOT returned else (if there are referrals) // 4.3.1.2 Haripriya S. INTERNET-DRAFT 6 EntrySelection control for LDAP modify and delete on multiple entries, July 2000 LDAPopnresult = noSuchObject LDAPopnDN = BaseDN EntrySelectionResponse control returned selectResult = referral Fill the referrals with referral endif else /* baseDN exists */ if (search is successful or resulted in timeLimitExceeded or adminLimitExceeded) // 4.3.1.3 searchcode = result (success/timeLimitExceeded/adminLimitExceeded) if (no entries are returned by the search) // 4.3.1.4 LDAPopnresult = success EntrySelectionResponse control returned selectResult = else /* Entries are returned by search */ if (operations on all matched entries successful) // 4.3.1.5 LDAPopnresult = success if (success and no search continuation references found) // 4.3.1.6 EntrySelectionResponse control NOT returned else /* continuation references or timeLimitExceeded */ // 4.3.1.7 EntrySelectionResponse control returned else if (one or more operations failed OR adminLimit OR optimeLimit exceeded while modify/delete) if (nooferrors > errorLimit OR all matched entried exhausted OR lasterror == adminLimitExceeded OR lasterror == timeLimitExceeded) // 4.3.1.8 LDAPopnresult = lasterror LDAPopnDN = lastfailedDN/lastDN EntrySelectionResponse control returned selectResult = failedcount = number of entries for which operation failed if (returnFailedDN is set) // 4.3.1.9 fill failedDNs with DNs of failed entries and corresponding failedDNResults endif else if (one or more entries are yet to be processed) // 4.3.1.10 continue processing with the next entry endif /* some entries remaining */ endif /* one or more entries failed */ endif /* some entries were returned by the search */ if (EntrySelectionResponse control returned and search continuation results available) // 4.3.1.11 fill up SearchContinuation with the search continuation LDAPURLs. endif / * Search continuation results */ else /* search was not successful */ // 4.3.1.12 LDAPopnresult = noSuchObject LDAPopnDN = NULL dn EntrySelectionResponse control returned selectResult = the LDAP error returned by the search endif /* search failed */ endif /* baseDN exists */ Haripriya S. INTERNET-DRAFT 7 EntrySelection control for LDAP modify and delete on multiple entries, July 2000 The user can decide to stop on the first error, and can set the errorLimit value to 0, so that if even one error is found the operation will return an error. In this case when the first error occurs, the server SHOULD stop processing the modify or delete for further entries. If errorLimit is set to 0, then the client can get the failed DN, by just looking at the LdapDN field in the ModifyResponse or DeleteResponse, even if returnFailedDNs is set to FALSE. If the number of modifies or deletes possible in a single LDAP operation is reached, then the server SHOULD return adminLimitExceeded(11). In this case objects should have been processed till the error was reached, and the situation will be treated the same as in 4.3.1.8. 4.4 Behavior of server with respect to Criticality The default behavior in the absence of the Criticality field is as if the Criticality field is set to false for the control. If the control is not recognized, and the Criticality is set to TRUE, then the server MUST return an unavailableCriticalExtension result code. If the control is not recognized and the criticality is set to False, then the server should try to perform the operation specified on the BaseDN alone and ignore the control. In case unavailablecriticalextension is returned, then the server should not send the EntrySelectionResponse control. 5. Making the operation idempotent with respect to retries Multi-entry deletions even if done partially (only on a subset of all the entries that were selected) will result in idempotent retries, because the deleted entries will not be returned by the EntrySelection filter the next time. But in an entry modify, an add or a delete value, and or an add or delete attribute could cause a AttributeOrValueAlreadyExists or noSuchAttribute, if the operation has already been done. Example: Let ou=hr,o=org be an organizationalUnit in company org. Let cn=jsmith,ou=hr,o=org and cn=mwhite,ou=hr,o=org be two objects of class "inetOrgPerson" under this ou. A multivalued attribute "telephoneNumber" and a singlevalued attribute "preferredLanguage" are optional attributes for "inetOrgPerson". Let the client request, a modify operation on "ou=hr,o=org", with an EntrySelection control with the LDAP search filter[RFC 2254] "objectclass=inetOrgPerson", be as follows (in [ldif] format): dn: ou=hr,o=org changetype: modify add: telephoneNumber telephoneNumber: 801-861-2222 - delete: preferredLanguage If the first time around both entries "jsmith" and "mwhite" had Haripriya S. INTERNET-DRAFT 8 EntrySelection control for LDAP modify and delete on multiple entries, July 2000 "preferredLanguage", and the operation failed on "mwhite" but succeeded on "jsmith", then when the retry is done the operation on "jsmith" would fail due to two reasons: i) The value "801-861-2222" for "telephoneNumber" already exists - AttributeOrValueAlreadyExists ii) The attribute "preferredLanguage" is already deleted - noSuchAttribute One approach to avoid this is to say that errorLimit will not take into account an AttributeOrValueAlreadyExists and noSuchAttribute, but return them as errors if that is the last error after processing all entries. This would still not let the client really decide if its operation is successful and the errors are due to retries, or whether the operation itself failed. Another approach is to let the client's filter take care of such conditions creating noSuchAttribute (modify or delete a attribute that does not exist), or AttributeOrValueAlreadyExists (adding an already existing value to a multivalued attribute or adding a single valued attribute which already exists). The argument behind this approach is that such conditions could even happen the first time around (without a retry), if the entry was already in that state. In the latter case, where the client takes care of these two error conditions, the client's filter in the EntrySelection should be the equivalent of '(&(objectclass=inetOrgPerson)(!(telephoneNumber="801-861-2222")) (preferredLanguage=*))' so that it can avoid changing the same attributes twice and thus getting an error. NOTE: There is no [ldif] format available for specifying the information in an EntrySelection control yet. These examples are not working examples but just to illustrate a situation. 6. Interaction with TreeDelete Control [treedelete] If a TreeDelete control is set for a delete operation, then its semantics is the same as if an EntrySelection control is given with the search filter being "objectclass=*", and the scope being "sub". This similarity is with respect to the functionality of the operation, but error handling and behavior with respect to referrals etc. may vary. Also, the semantics for partial processing of the operation for the EntrySelection control are different from the TreeDelete control. If both the TreeDelete control and the EntrySelection control are present on a given LDAP delete request, then the server SHOULD Haripriya S. INTERNET-DRAFT 9 EntrySelection control for LDAP modify and delete on multiple entries, July 2000 return an LDAP resultcode of unwillingToPerform(53). 7. Security Considerations There are no direct security related issues discussed in this document. But this control could indirectly cause a server to deny service to legitimate clients because of the server being loaded by a huge number of modifies and deletes due to this control. Administrative limits MAY be set for a given server to cope with such situations, and if exceeded the server SHOULD return with an adminLimitExceeded error. 8. References [RFC 2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC 2254] T. Howes, "The String Representation of LDAP Search Filters", RFC 2254, December 1997. [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels, "RFC 2119, Harvard University, March 1997. [rescodes] Mike Just, K. Leclair, Jim Sermersheim, Mark smith, "LDAPv3 Result Codes: Definitions and Appropriate Use", INTERNET-DRAFT, April 2000, [ldif] Gordon Good, "The LDAP Data Interchange Format (LDIF) - Technical Specification", Netscape Communications, INTERNET-DRAFT, March 2000, [treedelete] M. P. Armijo, "Tree Delete Control", Microsoft Corporation, INTERNET-DRAFT November 12, 1999, [ASN.1] ITU-T Rec. X.680, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", 1994 9. Acknowledgements I sincerely thank K. K. Subramaniam, VithalPrasad Gaitonde, Dinakar Sitaram, and Girish Elchuri who reviewed this document and gave their valuable suggestions, and the Novell Standards Board for their review. Special thanks to K. K. Subramaniam for his suggestions in making the examples and the abstract clearer. Haripriya S. INTERNET-DRAFT 10 EntrySelection control for LDAP modify and delete on multiple entries, July 2000 10. Address Haripriya S. Novell Inc. 49/1, 49/3, Garvebhavi Palya, 7th Mile, Hosur Road, Bangalore - 560068 India Phone: +91-80-5721858 Extn:2121 Email: sharipriya@novell.com This internet draft expires on 20 January 2001