idnits 2.17.1 draft-ietf-ldapext-ldapv3-vlv-04.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): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** 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? == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 10 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 11 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 198 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 14 has weird spacing: '...ormance with ...' == Line 15 has weird spacing: '...visions of Se...' == Line 16 has weird spacing: '...as, and its...' == Line 17 has weird spacing: '...working group...' == Line 21 has weird spacing: '...and may be ...' == (193 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 (5 October 2000) is 8604 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 216, but not defined -- Looks like a reference, but probably isn't: '0' on line 224 -- Looks like a reference, but probably isn't: '1' on line 227 ** Obsolete normative reference: RFC 2251 (ref. 'LDAPv3') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Downref: Normative reference to an Informational RFC: RFC 2696 (ref. 'SPaged') Summary: 9 errors (**), 0 flaws (~~), 11 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT David Boreham, Netscape 2 Jim Sermersheim, Novell 3 Anoop Anantha, Microsoft 4 Michael Armijo, Microsoft 5 ldapext Working Group 6 April, 2000 7 LDAP Extensions for Scrolling View Browsing of Search Results 9 draft-ietf-ldapext-ldapv3-vlv-04.txt 10 This document expires on 5 October 2000 12 1. Status of this Memo 14 This document is an Internet-Draft and is in full conformance with all 15 provisions of Section 10 of RFC2026. Internet-Drafts are working docu- 16 ments of the Internet Engineering Task Force (IETF), its areas, and its 17 working groups. Note that other groups may also distribute working 18 documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet- Drafts as reference material 23 or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 2. Abstract 33 This document describes a Virtual List View control extension for the 34 LDAP Search operation. This control is designed to allow the "virtual 35 list box" feature, common in existing commercial e-mail address book 36 applications, to be supported efficiently by LDAP servers. LDAP servers' 37 inability to support this client feature is a significant impediment to 38 LDAP replacing proprietary protocols in commercial e-mail systems. 40 The control allows a client to specify that the server return, for a 41 given LDAP search with associated sort keys, a contiguous subset of the 42 search result set. This subset is specified in terms of offsets into the 43 ordered list, or in terms of a greater than or equal comparison value. 45 3. Background 47 A Virtual List is a graphical user interface technique employed where 49 RFC DRAFT April 2000 51 ordered lists containing a large number of entries need to be displayed. 52 A window containing a small number of visible list entries is drawn. The 53 visible portion of the list may be relocated to different points within 54 the list by means of user input. This input can be to a scroll bar 55 slider; from cursor keys; from page up/down keys; from alphanumeric keys 56 for "typedown". The user is given the impression that they may browse 57 the complete list at will, even though it may contain millions of 58 entries. It is the fact that the complete list contents are never 59 required at any one time that characterizes Virtual List View. Rather 60 than fetch the complete list from wherever it is stored (typically from 61 disk or a remote server), only that information which is required to 62 display the part of the list currently in view is fetched. The subject 63 of this document is the interaction between client and server required 64 to implement this functionality in the context of the results from a 65 sorted LDAP search request. 67 For example, suppose an e-mail address book application displays a list 68 view onto the list containing the names of all the holders of e-mail 69 accounts at a large university. The list is sorted alphabetically. 70 While there may be tens of thousands of entries in this list, the 71 address book list view displays only 20 such accounts at any one time. 72 The list has an accompanying scroll bar and text input window for type- 73 down. When first displayed, the list view shows the first 20 entries in 74 the list, and the scroll bar slider is positioned at the top of its 75 range. Should the user drag the slider to the bottom of its range, the 76 displayed contents of the list view should be updated to show the last 77 20 entries in the list. Similarly, if the slider is positioned somewhere 78 in the middle of its travel, the displayed contents of the list view 79 should be updated to contain the 20 entries located at that relative 80 position within the complete list. Starting from any display point, if 81 the user uses the cursor keys or clicks on the scroll bar to request 82 that the list be scrolled up or down by one entry, the displayed con- 83 tents should be updated to reflect this. Similarly the list should be 84 displayed correctly when the user requests a page scroll up or down. 85 Finally, when the user types characters in the type-down window, the 86 displayed contents of the list should "jump" or "seek" to the appropri- 87 ate point within the list. For example, if the user types "B", the 88 displayed list could center around the first user with a name beginning 89 with the letter "B". When this happens, the scroll bar slider should 90 also be updated to reflect the new relative location within the list. 92 This document defines a request control which extends the LDAP search 93 operation. Always used in conjunction with the server side sorting 94 control[SSS], this allows a client to retrieve selected portions of 95 large search result set in a fashion suitable for the implementation of 96 a virtual list view. 98 The key words "MUST", "SHOULD", and "MAY" used in this document are to 100 RFC DRAFT April 2000 102 be interpreted as described in [Bradner97]. 104 4. Client-Server Interaction 106 The Virtual List View control extends a regular LDAP Search operation 107 which must also include a server-side sorting control[SSS]. Rather than 108 returning the complete set of appropriate SearchResultEntry messages, 109 the server is instructed to return a contiguous subset of those entries, 110 taken from the sorted result set, centered around a particular target 111 entry. Henceforth, in the interests of brevity, the sorted search result 112 set will be referred to as "the list". 114 The sort control MAY contain any sort specification valid for the 115 server. The attributeType field in the first SortKeyList sequence ele- 116 ment has special significance for "typedown". 118 The desired target entry, and the number of entries to be returned both 119 before, and after, that target entry in the list, are determined by the 120 client's VirtualListViewRequest control. 122 When the server returns the set of entries to the client, it attaches a 123 VirtualListViewResponse control to the SearchResultDone message. The 124 server returns in this control: its current estimate for the list con- 125 tent count, the location within the list corresponding to the target 126 entry, and any error codes. 128 The target entry is specified in the VirtualListViewRequest control by 129 one of two methods. The first method is for the client to indicate the 130 target entry's offset within the list. The second way is for the client 131 to supply an attribute assertion value. The value is compared against 132 the values of the attribute specified as the primary sort key in the 133 sort control attached to the search operation. The first sort key in 134 the SortKeyList is the primary sort key. The target entry is the first 135 entry in the list with value greater than or equal to (in the primary 136 sort order), the presented value. The order is determined by rules 137 defined in [SSS]. Selection of the target entry by this means is 138 designed to implement "typedown". Note that it is possible that no 139 entry satisfies these conditions, in which case there is no target 140 entry. This condition is indicated by the server returning the special 141 value contentCount + 1 in the target position field. 143 Because the server may not have an accurate estimate of the number of 144 entries in the list, and to take account of cases where the list size is 145 changing during the time the user browses the list, and because the 146 client needs a way to indicate specific list targets "beginning" and 147 "end", offsets within the list are transmitted between client and server 148 as ratios---offset to content count. The server sends its latest esti- 149 mate as to the number of entries in the list (content count) to the 151 RFC DRAFT April 2000 153 client in every response control. The client sends its assumed value 154 for the content count in every request control. The server examines the 155 content count and offsets presented by the client and computes the 156 corresponding offsets within the list, based on its own idea of the con- 157 tent count. 159 Si = Sc * (Ci / Cc) 161 Where: 162 Si is the actual list offset used by the server 163 Sc is the server's estimate for content count 164 Ci is the client's submitted offset 165 Cc is the client's submitted content count 166 The result is rounded to the nearest integer. 168 If the content count is stable, and the client returns to the server the 169 content count most recently received, Cc = Sc and the offsets transmit- 170 ted become the actual server list offsets. 172 The following special cases are allowed: a client sending a content 173 count of zero (Cc = 0) means "client has no idea what the content count 174 is, server MUST use its own content count estimate in place of the 175 client's". An offset value of one (Ci = 1) always means that the target 176 is the first entry in the list. Client specifying an offset which equals 177 the content count specified in the same request control (Ci = Cc) means 178 that the target is the last entry in the list. Ci may only equal zero 179 when Cc is also zero. This signifies the last entry in the list. 181 Because the server always returns contentCount and targetPosition, the 182 client can always determine which of the returned entries is the target 183 entry. Where the number of entries returned is the same as the number 184 requested, the client is able to identify the target by simple arith- 185 metic. Where the number of entries returned is not the same as the 186 number requested (because the requested range crosses the beginning or 187 end of the list, or both), the client must use the target position and 188 content count values returned by the server to identify the target 189 entry. For example, suppose that 10 entries before and 10 after the tar- 190 get were requested, but the server returns 13 entries, a content count 191 of 100 and a target position of 3. The client can determine that the 192 first entry must be entry number 1 in the list, therefore the 13 entries 193 returned are the first 13 entries in the list, and the target is the 194 third one. 196 A server-generated context identifier MAY be returned to clients. A 197 client receiving a context identifier SHOULD return it unchanged in a 198 subsequent request which relates to the same list. The purpose of this 199 interaction is to enhance the performance and effectiveness of servers 200 which employ approximate positioning. 202 RFC DRAFT April 2000 204 5. The Controls 206 Support for the virtual list view control extension is indicated by the 207 presence of the OID "2.16.840.1.113730.3.4.9" in the supportedControl 208 attribute of a server's root DSE. 210 5.1. Request Control 212 This control is included in the SearchRequest message as part of the 213 controls field of the LDAPMessage, as defined in Section 4.1.12 of 214 [LDAPv3]. The controlType is set to "2.16.840.1.113730.3.4.9". The cri- 215 ticality SHOULD be set to TRUE. If this control is included in a Sear- 216 chRequest message, a Server Side Sorting request control [SSS] MUST also 217 be present in the message. The controlValue is an OCTET STRING whose 218 value is the BER-encoding of the following SEQUENCE: 220 VirtualListViewRequest ::= SEQUENCE { 221 beforeCount INTEGER (0..maxInt), 222 afterCount INTEGER (0..maxInt), 223 CHOICE { 224 byoffset [0] SEQUENCE { 225 offset INTEGER (0 .. maxInt), 226 contentCount INTEGER (0 .. maxInt) }, 227 greaterThanOrEqual [1] AssertionValue }, 228 contextID OCTET STRING OPTIONAL } 230 beforeCount indicates how many entries before the target entry the 231 client wants the server to send. afterCount indicates the number of 232 entries after the target entry the client wants the server to send. 233 offset and contentCount identify the target entry as detailed in section 234 4. greaterThanOrEqual is an attribute assertion value defined in 235 [LDAPv3]. If present, the value supplied in greaterThanOrEqual is used 236 to determine the target entry by comparison with the values of the 237 attribute specified as the primary sort key. The first list entry who's 238 value is no less than (less than or equal to when the sort order is 239 reversed) the supplied value is the target entry. If present, the con- 240 textID field contains the value of the most recently received contextID 241 field from a VirtualListViewResponse control. The type AssertionValue 242 and value maxInt are defined in [LDAPv3]. contextID values have no 243 validity outwith the connection on which they were received. That is, a 244 client should not submit a contextID which it received from another con- 245 nection, a connection now closed, or a different server. 247 5.2. Response Control 249 This control is included in the SearchResultDone message as part of the 250 controls field of the LDAPMessage, as defined in Section 4.1.12 of 252 RFC DRAFT April 2000 254 [LDAPv3]. 256 The controlType is set to "2.16.840.1.113730.3.4.10". The criticality is 257 FALSE (MAY be absent). The controlValue is an OCTET STRING, whose value 258 is the BER encoding of a value of the following SEQUENCE: 260 VirtualListViewResponse ::= SEQUENCE { 261 targetPosition INTEGER (0 .. maxInt), 262 contentCount INTEGER (0 .. maxInt), 263 virtualListViewResult ENUMERATED { 264 success (0), 265 operationsError (1), 266 unwillingToPerform (53), 267 insufficientAccessRights (50), 268 busy (51), 269 timeLimitExceeded (3), 270 adminLimitExceeded (11), 271 sortControlMissing (60), 272 offsetRangeError (61), 273 other (80) }, 274 contextID OCTET STRING OPTIONAL } 276 targetPosition gives the list offset for the target entry. contentCount 277 gives the server's estimate of the current number of entries in the 278 list. Together these give sufficient information for the client to 279 update a list box slider position to match the newly retrieved entries 280 and identify the target entry. The contentCount value returned SHOULD be 281 used in a subsequent VirtualListViewRequest control. contextID is a 282 server-defined octet string. If present, the contents of the contextID 283 field SHOULD be returned to the server by a client in a subsequent Vir- 284 tualListViewRequest control. 286 The virtualListViewResult codes which are common to the LDAP sear- 287 chResponse (adminLimitExceeded, timeLimitExceeded, busy, operationsEr- 288 ror, unwillingToPerform, insufficientAccessRights) have the same mean- 289 ings as defined in [LDAPv3], but they pertain specifically to the VLV 290 operation. For example, the server could exceed an administration limit 291 processing a SearchRequest with a VirtualListViewRequest control. How- 292 ever, the same administration limit would not be exceeded should the 293 same SearchRequest be submitted by the client without the VirtualList- 294 ViewRequest control. In this case, the client can determine that an 295 administration limit has been exceeded in servicing the VLV request, and 296 can if it chooses resubmit the SearchRequest without the VirtualList- 297 ViewRequest control. 299 insufficientAccessRights means that the server denied the client permis- 300 sion to perform the VLV operation. 302 RFC DRAFT April 2000 304 If the server determines that the results of the search presented exceed 305 the range provided by the 32-bit offset values, it MUST return 306 offsetRangeError. 308 6. Protocol Example 310 Here we walk through the client-server interaction for a specific vir- 311 tual list view example: The task is to display a list of all 78564 peo- 312 ple in the US company "Ace Industry". This will be done by creating a 313 graphical user interface object to display the list contents, and by 314 repeatedly sending different versions of the same virtual list view 315 search request to the server. The list view displays 20 entries on the 316 screen at a time. 318 We form a search with baseDN "o=Ace Industry, c=us"; search scope sub- 319 tree; filter "objectClass=inetOrgPerson". We attach a server sort order 320 control to the search, specifying ascending sort on attribute "cn". To 321 this base search, we attach a virtual list view request control with 322 contents determined by the user activity and send the search to the 323 server. We display the results from each search in the list window and 324 update the slider position. 326 When the list view is first displayed, we want to initialize the con- 327 tents showing the beginning of the list. Therefore, we set beforeCount = 328 0, afterCount = 19, contentCount = 0, offset = 1 and send the request to 329 the server. The server duly returns the first 20 entries in the list, 330 plus the content count = 78564 and targetPosition = 1. We therefore 331 leave the scroll bar slider at its current location (the top of its 332 range). 334 Say that next the user drags the scroll bar slider down to the bottom of 335 its range. We now wish to display the last 20 entries in the list, so 336 we set beforeCount = 19, afterCount = 0, contentCount = 78564, offset = 337 78564 and send the request to the server. The server returns the last 20 338 entries in the list, plus the content count = 78564 and targetPosition = 339 78564. 341 Next the user presses a page up key. Our page size is 20, so we set 342 beforeCount = 0, afterCount = 19, contentCount = 78564, offset = 343 78564-19-20 and send the request to the server. The server returns the 344 preceding 20 entries in the list, plus the content count = 78564 and 345 targetPosition = 78525. 347 Now the user grabs the scroll bar slider and drags it to 68% of the way 348 down its travel. 68% of 78564 is 53424 so we set beforeCount = 9, after- 349 Count = 10, contentCount = 78564, offset = 53424 and send the request to 350 the server. The server returns the preceding 20 entries in the list, 351 plus the content count = 78564 and targetPosition = 53424. 353 RFC DRAFT April 2000 355 Lastly, the user types the letter "B". We set beforeCount = 9, after- 356 Count = 10 and greaterThanOrEqual = "B". The server finds the first 357 entry in the list not less than "B", let's say "Babs Jensen", and 358 returns the nine preceding entries, the target entry, and the proceeding 359 10 entries. The server returns content count = 78564 and targetPosition 360 = 5234 and so the client updates its scroll bar slider to 6.7% of full 361 scale. 363 7. Notes for Implementers 365 While the feature is expected to be generally useful for arbitrary 366 search and sort specifications, it is specifically designed for those 367 cases where the result set is very large. The intention is that this 368 feature be implemented efficiently by means of pre-computed indices per- 369 taining to a set of specific cases. For example, an offset relating to 370 "all the employees in the local organization, sorted by surname" would 371 be a common case. 373 The intention for client software is that the feature should fit easily 374 with the host platform's graphical user interface facilities for the 375 display of scrolling lists. Thus the task of the client implementers 376 should be one of reformatting up the requests for information received 377 from the list view code to match the format of the virtual list view 378 request and response controls. 380 Client implementers should note that any offset value returned by the 381 server may be approximate. Do not design clients > which only operate 382 correctly when offsets are exact. 384 Server implementers using indexing technology which features approximate 385 positioning should consider returning context identifiers to clients. 386 The use of a context identifier will allow the server to distinguish 387 between client requests which relate to different displayed lists on the 388 client. Consequently the server can decide more intelligently whether to 389 reposition an existing database cursor accurately to within a short dis- 390 tance of its current position, or to reposition to an approximate posi- 391 tion. Thus the client will see precise offsets for "short" repositioning 392 (e.g. paging up or down), but approximate offsets for a "long" reposi- 393 tion (e.g. a slider movement). 395 Server implementers are free to return status code unwillingToPerform 396 should their server be unable to service any particular VLV search. 397 This might be because the resolution of the search is computationally 398 infeasible, or because excessive server resources would be required to 399 service the search. 401 Client implementers should note that this control is only defined on a 402 client interaction with a single server. If a server returns referrals 404 RFC DRAFT April 2000 406 as a part of its response to the search request, the client is responsi- 407 ble for deciding when and how to apply this control to the referred-to 408 servers, and how to collate the results from multiple servers. 410 8. Relationship to "Simple Paged Results" 412 These controls are designed to support the virtual list view, which has 413 proved hard to implement with the Simple Paged Results mechanism 414 [SPaged]. However, the controls described here support any operation 415 possible with the Simple Paged Results mechanism. The two mechanisms are 416 not complementary, rather one has a superset of the other's features. 417 One area where the mechanism presented here is not a strict superset of 418 the Simple Paged Results scheme is that here we require a sort order to 419 be specified. No such requirement is made for paged results. 421 9. Security Considerations 423 Server implementers may wish to consider whether clients are able to 424 consume excessive server resources in requesting virtual list opera- 425 tions. Access control to the feature itself; configuration options lim- 426 iting the feature's use to certain predetermined search base DNs and 427 filters; throttling mechanisms designed to limit the ability for one 428 client to soak up server resources, may be appropriate. 430 Consideration should be given as to whether a client will be able to 431 retrieve the complete contents, or a significant subset of the complete 432 contents of the directory using this feature. This may be undesirable in 433 some circumstances and consequently it may be necessary to enforce some 434 access control. 436 Clients can, using this control, determine how many entries are con- 437 tained within a portion of the DIT. This may constitute a security 438 hazard. Again, access controls may be appropriate. 440 Server implementers SHOULD exercise caution concerning the content of 441 the contextID. Should the contextID contain internal server state, it 442 may be possible for a malicious client to use that information to gain 443 unauthorized access to information. 445 10. Acknowledgements 447 Chris Weider of Microsoft co-authored a previous version of this docu- 448 ment. 450 RFC DRAFT April 2000 452 11. References 454 [LDAPv3] 455 Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Pro- 456 tocol (v3)", Internet Standard, December, 1997. RFC2251. 458 [SPaged] 459 Weider, C, A. Herron, A. Anantha, and T. Howes, "LDAP Control 460 Extension for Simple Paged Results Manipulation", September 461 1999. RFC2696 463 [SSS]Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server 464 Side Sorting of Search Results", Internet Draft, April, 1999. 465 Available as draft-ietf-asid-ldapv3-sorting-02.txt. 467 [Bradner97] 468 Bradner, S., "Key Words for use in RFCs to Indicate Requirement 469 Levels", BCP 14, RFC 2119, March 1997. 471 12. Authors' Addresses 473 David Boreham 474 iPlanet e-commerce solutions 475 501 E. Middlefield Road 476 Mountain View, CA 94043, USA 477 +1 650 937-5206 478 dboreham@netscape.com 480 Jim Sermersheim 481 Novell 482 122 East 1700 South 483 Provo, Utah 84606, USA 484 jimse@novell.com 486 Anoop Anantha 487 Microsoft Corp. 488 1 Microsoft Way 489 Redmond, WA 98052, USA 490 +1 425 882-8080 491 anoopa@microsoft.com 493 Michael Armijo 494 Microsoft Corp. 495 1 Microsoft Way 496 Redmond, WA 98052, USA 497 +1 425 882-8080 498 micharm@microsoft.com 499 This document expires on 5 October 2000 501 RFC DRAFT April 2000