idnits 2.17.1 draft-ietf-ldapext-ldapv3-vlv-00.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-19) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 7 longer pages, the longest (page 2) being 60 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 8 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 166 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? ** There are 2 instances of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 11 has weird spacing: '...fts are worki...' == Line 12 has weird spacing: '...ments of the ...' == Line 13 has weird spacing: '...t other group...' == Line 17 has weird spacing: '...and may be ...' == Line 21 has weird spacing: '...atus of any ...' == (161 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (23 May 1998) is 9463 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'SSS' is mentioned on line 204, but not defined -- Looks like a reference, but probably isn't: '0' on line 212 -- Looks like a reference, but probably isn't: '1' on line 215 == Outdated reference: A later version (-09) exists of draft-ietf-asid-ldapv3-protocol-06 -- No information found for draft-ietf-asid-ldapv3-simple-paged - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SPaged' Summary: 11 errors (**), 0 flaws (~~), 12 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT David Boreham, Netscape 3 ldapext Working Group 20 November, 1997 5 LDAP Extensions for Scrolling View Browsing of Search Results 6 draft-ietf-ldapext-ldapv3-vlv-00.txt 7 This document expires on 23 May 1998 9 1. Status of this Memo 11 This document is an Internet-Draft. Internet-Drafts are working docu- 12 ments of the Internet Engineering Task Force (IETF), its areas, and its 13 working groups. Note that other groups may also distribute working 14 documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six months 17 and may be updated, replaced, or obsoleted by other documents at any 18 time. It is inappropriate to use Internet- Drafts as reference material 19 or to cite them other than as ``work in progress.'' 21 To learn the current status of any Internet-Draft, please check the 22 ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow 23 Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), 24 ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 26 2. Abstract 28 This document describes a Virtual List View control extension for the 29 LDAP Search operation. This control is designed to allow the ''virtual 30 list box'' feature, common in existing commercial e-mail address book 31 applications, to be supported efficiently by LDAP servers. LDAP servers' 32 inability to support this client feature is a significant impediment to 33 LDAP replacing proprietary protocols in commercial e-mail systems. 35 The control allows a client to specify that the server return, for a 36 given LDAP search with associated sort keys, a contiguous subset of the 37 search result set. This subset is specified in terms of indices into the 38 ordered list, or in terms of a greater than or equal comparison value. 40 3. Background 42 A Virtual List is a graphical user interface technique employed where 43 ordered lists containing a large number of entries need to be displayed. 44 A window containing a small number of visible list entries is drawn. The 45 visible portion of the list may be relocated to different points within 46 the list by means of user input. This input can be to a scroll bar 47 slider; from cursor keys; from page up/down keys; from alphanumeric keys 48 for "typedown". The user is given the impression that they may browse 50 RFC DRAFT November 1997 52 the complete list at will, even though it may contain millions of 53 entries. It is the fact that the complete list contents are never 54 required at any one time that characterizes Virtual List View. Rather 55 than fetch the complete list from wherever it is stored (typically from 56 disk or a remote server), only that information which is required to 57 display the part of the list currently in view is fetched. The subject 58 of this document is the interaction between client and server required 59 to implement this functionality in the context of the results from a 60 sorted LDAP search request. 62 For example, suppose an e-mail address book application displays a list 63 view onto the list containing the names of all the holders of e-mail 64 accounts at a large university. The list is sorted alphabetically. 65 While there may be tens of thousands of entries in this list, the 66 address book list view displays only 20 such accounts at any one time. 67 The list has an accompanying scroll bar and text input window for type- 68 down. When first displayed, the list view shows the first 20 entries in 69 the list, and the scroll bar slider is positioned at the top of its 70 range. Should the user drag the slider to the bottom of its range, the 71 displayed contents of the list view should be updated to show the last 72 20 entries in the list. Similarly, if the slider is positioned somewhere 73 in the middle of its travel, the displayed contents of the list view 74 should be updated to contain the 20 entries located at that relative 75 position within the complete list. Starting from any display point, if 76 the user uses the cursor keys or clicks on the scroll bar to request 77 that the list be scrolled up or down by one entry, the displayed con- 78 tents should be updated to reflect this. Similarly the list should be 79 displayed correctly when the user requests a page scroll up or down. 80 Finally, when the user types characters in the type-down window, the 81 displayed contents of the list should "jump" or "seek" to the appropri- 82 ate point within the list. For example, if the user types "B", the 83 displayed list could center around the first user with a name beginning 84 with the letter "B". When this happens, the scroll bar slider should 85 also be updated to reflect the new relative location within the list. 87 This document defines a request control which extends the LDAP search 88 operation. When used in conjunction with the server results sorting con- 89 trol, this allows a client to retrieve selected portions of large search 90 result set in a fashion suitable for the implementation of a virtual 91 list view. 93 The key words "MUST", "SHOULD", and "MAY" used in this document are to 94 be interpreted as described in [Bradner97]. 96 4. Client-Server Interaction 98 The Virtual List View control extends a regular LDAP Search operation 99 with mandatory server-side sorting control[SSS]. Rather than returning 101 RFC DRAFT November 1997 103 the complete set of appropriate SearchResultEntry messages, the server 104 is instructed to return a contiguous subset of those entries, taken from 105 the sorted result set, centered around a particular target entry. Hen- 106 ceforth, in the interests of brevity, the sorted search result set will 107 be referred to as "the list". 109 The sort control MAY contain any sort specification valid for the 110 server. The attributeType field in the first SortKeyList sequence ele- 111 ment has special significance for "typedown". 113 The desired target entry, and the number of entries to be returned 114 before and after that target entry in the list, are determined by the 115 client's VirtualListViewRequest control. 117 When the server returns the set of entries to the client, it attaches a 118 VirtualListViewResponse control to the searchResultDone message. The 119 server returns in this control: its current estimate for the list con- 120 tent count, the location within the list corresponding to the target 121 entry, and any error codes. 123 The target entry is specified in the VirtualListViewRequest control by 124 one of two methods. The first method is for the client to indicate the 125 target entry's index within the list. The second way is for the client 126 to supply an attribute assertion value. This value is used to determine 127 the target entry as follows. The value is compared against the values 128 of the attribute specified as the primary sort key in the sort control 129 attached to the search operation. The target entry is first entry in 130 the list having an attribute value for that attribute, but no value less 131 than (in the primary sort order), the presented value. Selection of the 132 target entry by this means is designed to implement "typedown". Note 133 that it is possible that no entry satisfies these conditions, in which 134 case there is no target entry. This condition is indicated by the server 135 returning the special value contentCount + 1 in the target position 136 field. 138 Because the server may not have a completely accurate estimate of the 139 number of entries in the list, and to take account of cases where the 140 list size is changing during the time the user browses the list, and 141 because the client needs a way to indicate specific list targets "begin- 142 ning" and "end", indices within the list are transmitted between client 143 and server as ratios---index to content count. The server sends its 144 latest estimate as to the number of entries in the list (content count) 145 to the client in every response control. The client sends its assumed 146 value for the content count in every request control. The server exam- 147 ines the content count and indices presented by the client and computes 148 the corresponding indices within the list, based on its own idea of the 149 content count. 151 RFC DRAFT November 1997 153 Si = Sc * (Ci / Cc) 155 Where: 156 Si is the actual list index used by the server 157 Sc is the server's estimate for content count 158 Ci is the client's submitted index 159 Cc is the client's submitted content count 160 The result is rounded to the nearest integer. 162 If the content count is stable, and the client returns to the server the 163 content count most recently received, Cc = Sc and the indices transmit- 164 ted become the actual server list offsets. 166 The following special cases are allowed: a client sending a content 167 count of zero means "client has no idea what the content count is, 168 server MUST use its own content count estimate in place of the 169 client's". An index value of one (Ci = 1) always means that the target 170 is the first entry in the list. Client specifying an index which equals 171 the content count specified in the same request control (Ci = Cc) means 172 that the target is the last entry in the list. 174 Because the server always returns contentCount and targetPosition, the 175 client can always determine which of the returned entries is the target 176 entry. Where the number of entries returned is the same as the number 177 requested, the client is able to identify the target by simple arith- 178 metic. Where the number of entries returned is not the same as the 179 number requested (because the requested range crosses the beginning or 180 end of the list, or both), the client must use the target position and 181 content count values returned by the server to identify the target 182 entry. For example, suppose that 10 entries before and after the target 183 were requested, but the server returns five entries, a content count of 184 100 and a target position of 3. The client can determine that the first 185 entry must be entry number 1 in the list, therefore the five entries 186 returned are the first five entries in the list, and the target is the 187 third one. 189 5. The Controls 191 Support for the virtual list view extended operation is indicated by the 192 presence of the OID "2.16.840.1.113730.3.4.9" in the supportedExtensions 193 attribute of a server's root DSE. 195 5.1. Request Control 197 This control is included in the searchRequest message as part of the 198 controls field of the LDAPMessage, as defined in Section 4.1.12 of 199 [LDAPv3]. The controlType is set to "2.16.840.1.113730.3.4.9". The cri- 200 ticality SHOULD be set to TRUE. If this control is included in a 202 RFC DRAFT November 1997 204 searchRequest message, a Server Side Sorting request control [SSS] MUST 205 also be present in the message. The controlValue is an OCTET STRING 206 whose value is the BER-encoding of the following SEQUENCE: 208 VirtualListViewRequest ::= SEQUENCE { 209 beforeCount INTEGER (0 .. maxInt), 210 afterCount INTEGER (0 .. maxInt), 211 CHOICE { 212 byIndex [0] SEQUENCE { 213 index INTEGER (0 .. maxInt), 214 contentCount INTEGER (0 .. maxInt) } 215 byValue [1] greaterThanOrEqual assertionValue } 217 beforeCount indicates how many entries before the target entry the 218 client wants the server to send. afterCount indicates the number of 219 entries after the target entry the client wants the server to send. 220 index and contentCount identify the target entry as detailed in section 221 4. greaterThanOrEqual is an attribute assertion value defined in 222 [LDAPv3]. If present, the value supplied in greaterThanOrEqual is used 223 to determine the target entry by comparison with the values of the 224 attribute specified as the primary sort key. The first list entry who's 225 value is no less than the supplied value is the target entry. 227 5.2. Response Control 229 This control is included in the searchResultDone message as part of the 230 controls field of the LDAPMessage, as defined in Section 4.1.12 of 231 [LDAPv3]. 233 The controlType is set to "2.16.840.1.113730.3.4.10". The criticality is 234 FALSE (MAY be absent). The controlValue is an OCTET STRING, whose value 235 is the BER encoding of a value of the following SEQUENCE: 237 VirtualListViewResponse ::= SEQUENCE { 238 targetPosition INTEGER (0 .. maxInt), 239 contentCount INTEGER (0 .. maxInt), 240 virtualListViewResult ENUMERATED { 241 success (0), 242 operatonsError (1), 243 unwillingToPerform (53), 244 insufficientAccessRights (50), 245 busy (51), 246 timeLimitExceeded (3), 247 adminLimitExceeded (11), 248 sortControlMissing (60), 249 indexRangeError (61), 250 other (80) } } 252 RFC DRAFT November 1997 254 targetPosition gives the list index for the target entry. contentCount 255 gives the server's estimate of the current number of entries in the 256 list. Together these give sufficient information for the client to 257 update a list box slider position to match the newly retrieved entries 258 and identify the target entry. The contentCount value returned SHOULD be 259 used in a subsequent virtualListViewRequest control. 261 6. Protocol Example 263 Here we walk through the client-server interaction for a specific vir- 264 tual list view example: The task is to display a list of all 78564 peo- 265 ple in the US company "Ace Industry". This will be done by creating a 266 graphical user interface object to display the list contents, and by 267 repeatedly sending different versions of the same virtual list view 268 search request to the server. The list view displays 20 entries on the 269 screen at a time. 271 We form a search with baseDN "o=Ace Industry, c=us"; search scope sub- 272 tree; filter "objectClass=inetOrgPerson". We attach a server sort order 273 control to the search, specifying ascending sort on attribute "cn". To 274 this base search, we attach a virtual list view request control with 275 contents determined by the user activity and send the search to the 276 server. We display the results from each search in the list window and 277 update the slider position. 279 When the list view is first displayed, we want to initialize the con- 280 tents showing the beginning of the list. Therefore, we set beforeCount = 281 0, afterCount = 19, contentCount = 0, index = 1 and send the request to 282 the server. The server duly returns the first 20 entries in the list, 283 plus the content count = 78564 and targetPosition = 1. We therefore 284 leave the scroll bar slider at its current location (the top of its 285 range). 287 Say that next the user drags the scroll bar slider down to the bottom of 288 its range. We now wish to display the last 20 entries in the list, so 289 we set beforeCount = 19, afterCount = 0, contentCount = 78564, index = 290 78564 and send the request to the server. The server returns the last 20 291 entries in the list, plus the content count = 78564 and targetPosition = 292 78564. 294 Next the user presses a page up key. Our page size is 20, so we set 295 beforeCount = 0, afterCount = 19, contentCount = 78564, index = 296 78564-19-20 and send the request to the server. The server returns the 297 preceeding 20 entries in the list, plus the content count = 78564 and 298 targetPosition = 78524. 300 Now the user grabs the scroll bar slider and drags it to 68% of the way 301 down its travel. 68% of 78564 is 52424 so we set beforeCount = 9, 303 RFC DRAFT November 1997 305 afterCount = 10, contentCount = 78564, index = 52424 and send the 306 request to the server. The server returns the preceeding 20 entries in 307 the list, plus the content count = 78564 and targetPosition = 78524. 309 Lastly, the user types the letter "B". We set beforeCount = 9, after- 310 Count = 10 and greaterThanOrEqual = "B". The server finds the first 311 entry in the list not less than "B", let's say "Babs Jensen", and 312 returns the nine preceeding entries, the target entry, and the proceed- 313 ing 10 entries. The server returns content count = 78564 and targetPo- 314 sition = 5234 and so the client updates its scroll bar slider to 6.6% of 315 full scale. 317 7. Notes for Implementers 319 While the feature is expected to be generally useful for arbitrary 320 search and sort specifications, it is specifically designed for those 321 cases where the result set is very large. The intention is that this 322 feature be implemented efficiently by means of pre-computed indices per- 323 taining to a set of specific cases. For example, an index relating to 324 "all the employees in the local organization, sorted by surname" would 325 be a common case. 327 The intention for client software is that the feature should fit easily 328 with the host platform's graphical user interface facilities for the 329 display of scrolling lists. Thus the task of the client implementers 330 should be one of reformatting up the requests for information received 331 from the list view code to match the format of the virtual list view 332 request and response controls. 334 8. Relationship to "Simple Paged Results" 336 These controls are designed to support the virtual list view, which has 337 proved hard to implement with the Simple Paged Results mechanism 338 [SPaged]. However, the controls described here support any operation 339 possible with the Simple Paged Results mechanism. The two mechanisms are 340 not complementary, rather one has a superset of the other's features. 342 9. Security Considerations 344 Server implementers may wish to consider whether clients are able to 345 consume excessive server resources in requesting virtual list opera- 346 tions. Access control to the feature itself; configuration options lim- 347 iting the feature's use to certain predetermined search base DNs and 348 filters; throttling mechanisms designed to limit the ability for one 349 client to soak up server resources, may be appropriate. 351 RFC DRAFT November 1997 353 Consideration should be given as to whether a client will be able to 354 retrieve the complete contents, or a significant subset of the complete 355 contents of the directory using this feature. This may be undesirable in 356 some circumstances and consequently it may be necessary to enforce some 357 access control. 359 Clients can, using this control, determine how many entries are con- 360 tained within a portion of the DIT. This may constitute a security 361 hazard. Again, access controls may be appropriate. 363 10. References 365 [LDAPv3] 366 Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Pro- 367 tocol (v3)", Internet Draft, 11 July, 1997. Available as draft- 368 ietf-asid-ldapv3-protocol-06.txt. 370 [SPaged] 371 Weider, C, A. Herron and T. Howes, "LDAP Control Extension for Sim- 372 ple Paged Results Manipulation", Internet Draft, March, 1997. 373 Available as draft-ietf-asid-ldapv3-simple-paged-01.txt. 375 [SSS]Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server 376 Side Sorting of Search Results", Internet Draft, March, 1997. 377 Available as draft-ietf-asid-ldapv3-sorting-00.txt. 379 [Bradner97] 380 Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement 381 Levels", Internet Draft, March, 1997. Available as RFC2119. 383 11. Author's Address 385 David Boreham 386 Netscape Communications Corp. 387 501 E. Middlefield Road 388 Mountain View, CA 94043, USA 389 dboreham@netscape.com 390 +1 650 937-5206 392 This document expires on 23 May 1998