Network Working Group M. Wahl Request for Comments: DRAFT Innosoft International, Inc. Expires in six months from August 7, 1998 Intended Category: Standards Track LDAPv3 Triggered Search Control 1. Status of this Memo This document is an Internet-Draft. Internet-Drafts are working docu- ments 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.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). Copyright Notice Copyright (C) The Internet Society (1998). All Rights Reserved. 2. Abstract This document defines a LDAPv3 [2] control to be used on the Search Request to allow a client to retrieve information on changes which are made to the directory information tree held by that server. 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 [1]. 3. Definition of control sent by client A client may provide a control of a particular type when invoking a search request. The controlType is "1.3.6.1.4.1.1466.29539.10", the criticality field may be TRUE or FALSE, and the controlValue field is absent. The search request size and time limits SHOULD both be 0. The server will return SearchResultEntry responses for all entries which match the client's search filter. However, the server will not return a SearchResultDone as it would normally. Wahl Page 1 INTERNET-DRAFT LDAPv3 Triggered Search Control August 1998 Instead, the server will preserve the client's message id, search filter and requested attribute list and associate it with the client's connection and this message id. The server will only return the SearchResultDone if there is an error condition (e.g. unwillingToPerform), and will not return the SearchResultDone if the request was successful. So long as the connection to the client is open and the client does not abandon the request or reuse the request message id, the server will return additional SearchResultEntry responses as entry addition, deletions and modifications occur resulting in entries which match the search. These responses have the same message id as the original request. The client may terminate the return of responses by abandoning the request. 4. Using the control in a naming context other than the changelog The client can use this control when performing a search of all or part of one or more naming contexts. When the naming context is not the change log [3], the server includes a control defined in section 4.1 with each SearchResultEntry returned by the server. The entries in the naming contexts to which the client has access, are in the scope of the search and match the filter are termed the result set. As entries enter the result set, leave the result set, or are modified in place, then an additional SearchResultEntry is returned to the client. An entry can enter the result set for the following reasons: - a new entry is added which matches the scope and filter, - an entry which did not match the filter is modified to add attributes which cause it to now match the filter, - an entry which matches the filter but was outside of the scope is renamed (or one of its superior entries is renamed) so that it is now in scope, or - a change to access control or other administrative function cause an entry which matches the scope and filter to be visible to the client. An entry can leave the result set for the following reasons: - an entry which matched the scope and filter is deleted, - an entry which matched the scope and filter is modified so that it no longer matches the filter, - an entry which matched the scope and filter is renamed (or one of its superior entries is renamed) so that it is no longer in scope, Wahl Page 2 INTERNET-DRAFT LDAPv3 Triggered Search Control August 1998 - a change to access control or other administrative function cause an entry which was visible to the client and matched the scope and filter to no longer be visible, and the resulting access control allows the client to be notified of this. 4.1. Definition of control returned by server The controlType is 1.3.6.1.4.1.1466.29539.13, the criticality is TRUE, and the controlValue contains the bytes of the BER-encoding of the following ASN.1 type: TriggerResultControl ::= SEQUENCE { resultType ENUMERATED { notChange (0), enteredSet (1), leftSet (2), modified (3) }, [1] changeType LDAPString OPTIONAL, [2] previousDN LDAPDN OPTIONAL, [3] changeNumber LDAPString OPTIONAL } The resultType is defined as follows: - notChange: the entry existed in the directory and matched the search at the time the operation is being performed, - enteredSet: the entry entered the result set for one of the reasons defined in section 4 above, - leftSet: the entry left the result set for one of the reasons defined in section 4 above, - modified: the entry was part of the result set, was modified or renamed, and still is in the result set. The changeType field is as defined to have the same value as the changeType attribute in the change log, such as "add", "delete", "modify" or "modrdn". If the changeType is "modrdn", then the previousDN field contains the name of the entry before the rename. The changeNumber is defined to have the same value as the changeNumber attribute in the change log: the string representation of change number assigned by the server for the change. It SHOULD be present if the server supports the change log. 4.2. Example To be provided in a later revision of this draft. Wahl Page 3 INTERNET-DRAFT LDAPv3 Triggered Search Control August 1998 5. Using the triggered search control in the changelog The client can also use this control when performing a search of the change log [3]. In this case, the search request MUST have the baseObject field set to the name of the base of the server's change log and the scope MUST be either singleLevel or wholeSubtree. 5.1. Example To be provided in a later revision of this draft. 5.2. Matching Rule A matching rule is defined to allow the client to request changes from only a particular portion of the tree when using the changelog. A server will advertise support for this matching rule by having the following rule definition present in the subschema subentry governing the changelog. (A client can determine the subschema subentry for the changelog by retrieving the attribute subschemaSubentry from the base entry of the changelog.) ( 1.3.6.1.4.1.1466.29539.10.1 NAME 'dnSubordinateTo' SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) An extensibleMatch filter will evaluate to TRUE for an entry to which the client has access if the matchingRule field is 1.3.6.1.4.1.1466.29539.10.1, the type field is any attribute with DN syntax (1.3.6.1.4.1.1466.115.121.1.12), and there is a value of that attribute present in an entry which is the same as or subordinate to the matchValue field. For example, if a client presented the following filter: (targetDN:1.3.6.1.4.1.1466.29539.10.1:=dc=acme,dc=com) the filter would evaluate as follows for the following values, assuming the client had sufficient access rights to perform the filtering: targetDn: dc=org FALSE targetDn: dc=com FALSE targetDn: dc=acme,dc=com TRUE targetDn: dc=www,dc=acme,dc=com TRUE targetDn: dc=www,dc=acme,dc=com,dc=sg FALSE targetDn: cn=server,dc=www,dc=acme,dc=com TRUE Wahl Page 4 INTERNET-DRAFT LDAPv3 Triggered Search Control August 1998 6. Scaling Considerations The use of this control may greatly increase the amount of server processing for modification operations, as well as the amount of network traffic as clients are notified of changes. Server implementations used on the Internet MUST have support administrative restrictions on the use of search triggers. 7. Security Considerations The changes attribute of the change log entries should not be generally readable. The administrator will typically configure specific users who are authorized to retrieve this attribute. 8. Acknowledgements This document is a product of the LDAPEXT working group. The ideas of Mark Smith, Gordon Good, Tim Howes and Rob Weltman in their persistent search draft are particularly acknowledged as contributing to this document. 9. Bibliography [1] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119. [2] "Lightweight Directory Access Protocol (v3)", RFC 2251. [3] "Definition of An Object Class to Hold LDAP Change Records", INTERNET DRAFT . 10. Authors Address Mark Wahl Innosoft International Inc. 8911 Capital of Texas Hwy Suite 4140 Austin, TX 78759 USA Phone: +1 626 919 3600 EMail: M.Wahl@innosoft.com Full Copyright Statement Copyright (C) The Internet Society (1998). All Rights Reserved. Wahl Page 5 INTERNET-DRAFT LDAPv3 Triggered Search Control August 1998 This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Expires: February 1999 Page 6