idnits 2.17.1 draft-ietf-ldapext-ldapv3-vlv-02.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-18) 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 9 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 10 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 190 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 15 has weird spacing: '...fts are worki...' == Line 16 has weird spacing: '...ments of the ...' == Line 17 has weird spacing: '...t other group...' == Line 21 has weird spacing: '...and may be ...' == Line 25 has weird spacing: '...atus of any ...' == (185 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 (17 May 1999) is 9103 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 213, but not defined -- Looks like a reference, but probably isn't: '0' on line 221 -- Looks like a reference, but probably isn't: '1' on line 224 ** Obsolete normative reference: RFC 2251 (ref. 'LDAPv3') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) -- No information found for draft-ietf-asid-ldapv3-simple-paged - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SPaged' Summary: 12 errors (**), 0 flaws (~~), 11 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT David Boreham, Netscape 3 Jim Sermersheim, Novell 4 Chris Weider, Microsoft 5 ldapext Working Group 18 November, 1998 7 LDAP Extensions for Scrolling View Browsing of Search Results 9 draft-ietf-ldapext-ldapv3-vlv-02.txt 11 This document expires on 17 May 1999 13 1. Status of this Memo 15 This document is an Internet-Draft. 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 To learn the current status of any Internet-Draft, please check the 26 ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow 27 Directories on ftp.ietf.org (US East Coast), nic.nordu.net (Europe), 28 ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 30 2. Abstract 32 This document describes a Virtual List View control extension for the 33 LDAP Search operation. This control is designed to allow the 'virtual 34 list box' feature, common in existing commercial e-mail address book 35 applications, to be supported efficiently by LDAP servers. LDAP servers' 36 inability to support this client feature is a significant impediment to 37 LDAP replacing proprietary protocols in commercial e-mail systems. 39 The control allows a client to specify that the server return, for a 40 given LDAP search with associated sort keys, a contiguous subset of the 41 search result set. This subset is specified in terms of offsets into the 42 ordered list, or in terms of a greater than or equal comparison value. 44 3. Background 46 A Virtual List is a graphical user interface technique employed where 47 ordered lists containing a large number of entries need to be displayed. 48 A window containing a small number of visible list entries is drawn. The 50 RFC DRAFT November 1998 52 visible portion of the list may be relocated to different points within 53 the list by means of user input. This input can be to a scroll bar 54 slider; from cursor keys; from page up/down keys; from alphanumeric keys 55 for "typedown". The user is given the impression that they may browse 56 the complete list at will, even though it may contain millions of 57 entries. It is the fact that the complete list contents are never 58 required at any one time that characterizes Virtual List View. Rather 59 than fetch the complete list from wherever it is stored (typically from 60 disk or a remote server), only that information which is required to 61 display the part of the list currently in view is fetched. The subject 62 of this document is the interaction between client and server required 63 to implement this functionality in the context of the results from a 64 sorted LDAP search request. 66 For example, suppose an e-mail address book application displays a list 67 view onto the list containing the names of all the holders of e-mail 68 accounts at a large university. The list is sorted alphabetically. 69 While there may be tens of thousands of entries in this list, the 70 address book list view displays only 20 such accounts at any one time. 71 The list has an accompanying scroll bar and text input window for type- 72 down. When first displayed, the list view shows the first 20 entries in 73 the list, and the scroll bar slider is positioned at the top of its 74 range. Should the user drag the slider to the bottom of its range, the 75 displayed contents of the list view should be updated to show the last 76 20 entries in the list. Similarly, if the slider is positioned somewhere 77 in the middle of its travel, the displayed contents of the list view 78 should be updated to contain the 20 entries located at that relative 79 position within the complete list. Starting from any display point, if 80 the user uses the cursor keys or clicks on the scroll bar to request 81 that the list be scrolled up or down by one entry, the displayed con- 82 tents should be updated to reflect this. Similarly the list should be 83 displayed correctly when the user requests a page scroll up or down. 84 Finally, when the user types characters in the type-down window, the 85 displayed contents of the list should "jump" or "seek" to the appropri- 86 ate point within the list. For example, if the user types "B", the 87 displayed list could center around the first user with a name beginning 88 with the letter "B". When this happens, the scroll bar slider should 89 also be updated to reflect the new relative location within the list. 91 This document defines a request control which extends the LDAP search 92 operation. Always used in conjunction with the server side sorting 93 control[SSS], this allows a client to retrieve selected portions of 94 large search result set in a fashion suitable for the implementation of 95 a virtual list view. 97 The key words "MUST", "SHOULD", and "MAY" used in this document are to 98 be interpreted as described in [Bradner97]. 100 RFC DRAFT November 1998 102 4. Client-Server Interaction 104 The Virtual List View control extends a regular LDAP Search operation 105 which must also include a server-side sorting control[SSS]. Rather than 106 returning the complete set of appropriate SearchResultEntry messages, 107 the server is instructed to return a contiguous subset of those entries, 108 taken from the sorted result set, centered around a particular target 109 entry. Henceforth, in the interests of brevity, the sorted search result 110 set will be referred to as "the list". 112 The sort control MAY contain any sort specification valid for the 113 server. The attributeType field in the first SortKeyList sequence ele- 114 ment has special significance for "typedown". 116 The desired target entry, and the number of entries to be returned both 117 before, and after, that target entry in the list, are determined by the 118 client's VirtualListViewRequest control. 120 When the server returns the set of entries to the client, it attaches a 121 VirtualListViewResponse control to the searchResultDone message. The 122 server returns in this control: its current estimate for the list con- 123 tent count, the location within the list corresponding to the target 124 entry, and any error codes. 126 The target entry is specified in the VirtualListViewRequest control by 127 one of two methods. The first method is for the client to indicate the 128 target entry's offset within the list. The second way is for the client 129 to supply an attribute assertion value. The value is compared against 130 the values of the attribute specified as the primary sort key in the 131 sort control attached to the search operation. The target entry is 132 first entry in the list with value greater than or equal to (in the pri- 133 mary sort order), the presented value. The order is determined by rules 134 defined in [SSS]. Selection of the target entry by this means is 135 designed to implement "typedown". Note that it is possible that no 136 entry satisfies these conditions, in which case there is no target 137 entry. This condition is indicated by the server returning the special 138 value contentCount + 1 in the target position field. 140 Because the server may not have an accurate estimate of the number of 141 entries in the list, and to take account of cases where the list size is 142 changing during the time the user browses the list, and because the 143 client needs a way to indicate specific list targets "beginning" and 144 "end", offsets within the list are transmitted between client and server 145 as ratios---offset to content count. The server sends its latest esti- 146 mate as to the number of entries in the list (content count) to the 147 client in every response control. The client sends its assumed value 148 for the content count in every request control. The server examines the 149 content count and offsets presented by the client and computes the 151 RFC DRAFT November 1998 153 corresponding offsets within the list, based on its own idea of the con- 154 tent count. 156 Si = Sc * (Ci / Cc) 158 Where: 159 Si is the actual list offset used by the server 160 Sc is the server's estimate for content count 161 Ci is the client's submitted offset 162 Cc is the client's submitted content count 163 The result is rounded to the nearest integer. 165 If the content count is stable, and the client returns to the server the 166 content count most recently received, Cc = Sc and the offsets transmit- 167 ted become the actual server list offsets. 169 The following special cases are allowed: a client sending a content 170 count of zero (Cc = 0) means "client has no idea what the content count 171 is, server MUST use its own content count estimate in place of the 172 client's". An offset value of one (Ci = 1) always means that the target 173 is the first entry in the list. Client specifying an offset which equals 174 the content count specified in the same request control (Ci = Cc) means 175 that the target is the last entry in the list. Ci may only equal zero 176 when Cc is also zero. This signifies the last entry in the list. 178 Because the server always returns contentCount and targetPosition, the 179 client can always determine which of the returned entries is the target 180 entry. Where the number of entries returned is the same as the number 181 requested, the client is able to identify the target by simple arith- 182 metic. Where the number of entries returned is not the same as the 183 number requested (because the requested range crosses the beginning or 184 end of the list, or both), the client must use the target position and 185 content count values returned by the server to identify the target 186 entry. For example, suppose that 10 entries before and 10 after the tar- 187 get were requested, but the server returns 13 entries, a content count 188 of 100 and a target position of 3. The client can determine that the 189 first entry must be entry number 1 in the list, therefore the 13 entries 190 returned are the first 13 entries in the list, and the target is the 191 third one. 193 A server-generated context identifier MAY be returned to clients. A 194 client receiving a context identifier SHOULD return it unchanged in a 195 subsequent request which relates to the same list. The purpose of this 196 interaction is to enhance the performance and effectiveness of servers 197 which employ approximate positioning. 199 RFC DRAFT November 1998 201 5. The Controls 203 Support for the virtual list view extended operation is indicated by the 204 presence of the OID "2.16.840.1.113730.3.4.9" in the supportedExtensions 205 attribute of a server's root DSE. 207 5.1. Request Control 209 This control is included in the searchRequest message as part of the 210 controls field of the LDAPMessage, as defined in Section 4.1.12 of 211 [LDAPv3]. The controlType is set to "2.16.840.1.113730.3.4.9". The cri- 212 ticality SHOULD be set to TRUE. If this control is included in a sear- 213 chRequest message, a Server Side Sorting request control [SSS] MUST also 214 be present in the message. The controlValue is an OCTET STRING whose 215 value is the BER-encoding of the following SEQUENCE: 217 VirtualListViewRequest ::= SEQUENCE { 218 beforeCount INTEGER (0 .. maxInt), 219 afterCount INTEGER (0 .. maxInt), 220 CHOICE { 221 byoffset [0] SEQUENCE { 222 offset INTEGER (0 .. maxInt), 223 contentCount INTEGER (0 .. maxInt) } 224 [1] greaterThanOrEqual assertionValue }, 225 contextID OCTET STRING OPTIONAL } 227 beforeCount indicates how many entries before the target entry the 228 client wants the server to send. afterCount indicates the number of 229 entries after the target entry the client wants the server to send. 230 offset and contentCount identify the target entry as detailed in section 231 4. greaterThanOrEqual is an attribute assertion value defined in 232 [LDAPv3]. If present, the value supplied in greaterThanOrEqual is used 233 to determine the target entry by comparison with the values of the 234 attribute specified as the primary sort key. The first list entry who's 235 value is no less than the supplied value is the target entry. If 236 present, the contextID field contains the value of the most recently 237 received contextID field from a VirtualListViewResponse control. 239 5.2. Response Control 241 This control is included in the searchResultDone message as part of the 242 controls field of the LDAPMessage, as defined in Section 4.1.12 of 243 [LDAPv3]. 245 The controlType is set to "2.16.840.1.113730.3.4.10". The criticality is 246 FALSE (MAY be absent). The controlValue is an OCTET STRING, whose value 247 is the BER encoding of a value of the following SEQUENCE: 249 RFC DRAFT November 1998 251 VirtualListViewResponse ::= SEQUENCE { 252 targetPosition INTEGER (0 .. maxInt), 253 contentCount INTEGER (0 .. maxInt), 254 virtualListViewResult ENUMERATED { 255 success (0), 256 operatonsError (1), 257 unwillingToPerform (53), 258 insufficientAccessRights (50), 259 busy (51), 260 timeLimitExceeded (3), 261 adminLimitExceeded (11), 262 sortControlMissing (60), 263 offsetRangeError (61), 264 other (80) }, 265 contextID OCTET STRING OPTIONAL } 267 targetPosition gives the list offset for the target entry. contentCount 268 gives the server's estimate of the current number of entries in the 269 list. Together these give sufficient information for the client to 270 update a list box slider position to match the newly retrieved entries 271 and identify the target entry. The contentCount value returned SHOULD be 272 used in a subsequent virtualListViewRequest control. contextID is a 273 server-defined octet string. If present, the contents of the contextID 274 field SHOULD be returned to the server by a client in a subsequent Vir- 275 tualListViewRequest control. 277 If the server determines that the results of the search presented exceed 278 the range provided by the 32-bit offset values, it MUST return 279 offsetRangeError. 281 6. Protocol Example 283 Here we walk through the client-server interaction for a specific vir- 284 tual list view example: The task is to display a list of all 78564 peo- 285 ple in the US company "Ace Industry". This will be done by creating a 286 graphical user interface object to display the list contents, and by 287 repeatedly sending different versions of the same virtual list view 288 search request to the server. The list view displays 20 entries on the 289 screen at a time. 291 We form a search with baseDN "o=Ace Industry, c=us"; search scope sub- 292 tree; filter "objectClass=inetOrgPerson". We attach a server sort order 293 control to the search, specifying ascending sort on attribute "cn". To 294 this base search, we attach a virtual list view request control with 295 contents determined by the user activity and send the search to the 296 server. We display the results from each search in the list window and 297 update the slider position. 299 RFC DRAFT November 1998 301 When the list view is first displayed, we want to initialize the con- 302 tents showing the beginning of the list. Therefore, we set beforeCount = 303 0, afterCount = 19, contentCount = 0, offset = 1 and send the request to 304 the server. The server duly returns the first 20 entries in the list, 305 plus the content count = 78564 and targetPosition = 1. We therefore 306 leave the scroll bar slider at its current location (the top of its 307 range). 309 Say that next the user drags the scroll bar slider down to the bottom of 310 its range. We now wish to display the last 20 entries in the list, so 311 we set beforeCount = 19, afterCount = 0, contentCount = 78564, offset = 312 78564 and send the request to the server. The server returns the last 20 313 entries in the list, plus the content count = 78564 and targetPosition = 314 78564. 316 Next the user presses a page up key. Our page size is 20, so we set 317 beforeCount = 0, afterCount = 19, contentCount = 78564, offset = 318 78564-19-20 and send the request to the server. The server returns the 319 preceeding 20 entries in the list, plus the content count = 78564 and 320 targetPosition = 78524. 322 Now the user grabs the scroll bar slider and drags it to 68% of the way 323 down its travel. 68% of 78564 is 52424 so we set beforeCount = 9, after- 324 Count = 10, contentCount = 78564, offset = 52424 and send the request to 325 the server. The server returns the preceeding 20 entries in the list, 326 plus the content count = 78564 and targetPosition = 78524. 328 Lastly, the user types the letter "B". We set beforeCount = 9, after- 329 Count = 10 and greaterThanOrEqual = "B". The server finds the first 330 entry in the list not less than "B", let's say "Babs Jensen", and 331 returns the nine preceeding entries, the target entry, and the proceed- 332 ing 10 entries. The server returns content count = 78564 and targetPo- 333 sition = 5234 and so the client updates its scroll bar slider to 6.6% of 334 full scale. 336 7. Server Publication of Indexed VLV Searches 338 It is considered important that a client should be able to discover the 339 set of search and sort specifications for which a server is able to pro- 340 vide efficient (i.e. indexed) service. It is expected that this will be 341 accomplished via means similar to the mechanism by which clients can 342 already discover LDAPv3 server supported naming contexts, namely the 343 rootDSE. The schema employed for this publication mechanism is to be 344 determined. 346 8. Notes for Implementers 348 While the feature is expected to be generally useful for arbitrary 350 RFC DRAFT November 1998 352 search and sort specifications, it is specifically designed for those 353 cases where the result set is very large. The intention is that this 354 feature be implemented efficiently by means of pre-computed indices per- 355 taining to a set of specific cases. For example, an offset relating to 356 "all the employees in the local organization, sorted by surname" would 357 be a common case. 359 The intention for client software is that the feature should fit easily 360 with the host platform's graphical user interface facilities for the 361 display of scrolling lists. Thus the task of the client implementers 362 should be one of reformatting up the requests for information received 363 from the list view code to match the format of the virtual list view 364 request and response controls. 366 Client implementers should note that any offset value returned by the 367 server may be approximate. Do not design clients which fail to operate 368 correctly unless offsets are exact. 370 Server implementers using indexing technology which features approximate 371 positioning should consider returning context identifiers to clients. 372 The use of a context identifier will allow the server to distinguish 373 between client requests which relate to different displayed lists on the 374 client. Consequently the server can decide more intelligently whether to 375 reposition an existing database cursor accurately to within a short dis- 376 tance of its current position, or to reposition to an approximate posi- 377 tion. Thus the client will see precise offsets for "short" repositioning 378 (e.g. paging up or down), but approximate offsets for a "long" reposi- 379 tion (e.g. a slider movement). 381 Server implementers are free to return status code unwillingToPerform 382 should their server be unable to service any particular VLV search. 383 This might be because the resolution of the search is computationally 384 infeasible, or because the excessive server resources would be required 385 to service the search. 387 Client implementers should note that this control is only defined on a 388 client interaction with a single server. If a server returns referrals 389 as a part of its response to the search request, the client is responsi- 390 ble for deciding when and how to apply this control to the referred-to 391 servers, and how to collate the results from multiple servers. 393 Search result entries are returned by the server according to the core 394 LDAPv3 protocol [LDAPv3]. However, the content of those entries may be 395 affected by access controls within the server. Consider the case where 396 access to some entries within the list is controlled such that the 397 client is not permitted to discover that they exist. In a simple search, 398 these entries would not be returned to the client. However, in servicing 399 a VLV search, a server implementation might be required to maintain a 401 RFC DRAFT November 1998 403 different index for each potential client authentication identity. This 404 is in order that it may efficiently compute the responses to all 405 clients. This may present an intolerable burden on the server. Accord- 406 ingly, servers are permitted to return a minimal entry as a placeholder 407 for an entry which would otherwise, due to access control, be "invisi- 408 ble" to the client. This minimal entry contains only a distinguised 409 name. The distinguished name MAY be either that of the real entry, or a 410 "fake" one, designed to make the actual value obscure to the client. 412 9. Relationship to "Simple Paged Results" 414 These controls are designed to support the virtual list view, which has 415 proved hard to implement with the Simple Paged Results mechanism 416 [SPaged]. However, the controls described here support any operation 417 possible with the Simple Paged Results mechanism. The two mechanisms are 418 not complementary, rather one has a superset of the other's features. 419 One area where the mechanism presented here is not a strict superset of 420 the Simple Paged Results scheme is that here we require a sort order to 421 be specified. No such requirement is made for paged results. 423 10. Security Considerations 425 Server implementers may wish to consider whether clients are able to 426 consume excessive server resources in requesting virtual list opera- 427 tions. Access control to the feature itself; configuration options lim- 428 iting the feature's use to certain predetermined search base DNs and 429 filters; throttling mechanisms designed to limit the ability for one 430 client to soak up server resources, may be appropriate. 432 Consideration should be given as to whether a client will be able to 433 retrieve the complete contents, or a significant subset of the complete 434 contents of the directory using this feature. This may be undesirable in 435 some circumstances and consequently it may be necessary to enforce some 436 access control. 438 Clients can, using this control, determine how many entries are con- 439 tained within a portion of the DIT. This may constitute a security 440 hazard. Again, access controls may be appropriate. 442 11. References 444 [LDAPv3] 445 Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Pro- 446 tocol (v3)", Internet Standard, December, 1997. Available as 447 RFC2251. 449 RFC DRAFT November 1998 451 [SPaged] 452 Weider, C, A. Herron and T. Howes, "LDAP Control Extension for Sim- 453 ple Paged Results Manipulation", Internet Draft, March, 1998. 454 Available as draft-ietf-asid-ldapv3-simple-paged-02.txt. 456 [SSS]Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server 457 Side Sorting of Search Results", Internet Draft, March, 1998. 458 Available as draft-ietf-asid-ldapv3-sorting-01.txt. 460 [Bradner97] 461 Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement 462 Levels", Internet Draft, March, 1997. Available as RFC2119. 464 12. Author's Address 466 David Boreham 467 Netscape Communications Corp. 468 501 E. Middlefield Road 469 Mountain View, CA 94043, USA 470 dboreham@netscape.com 471 +1 650 937-5206 473 Jim Sermersheim 474 Novell 475 122 East 1700 South 476 Provo, Utah 84606, USA 477 jimse@novell.com 479 Chris Weider 480 Microsoft Corp. 481 1 Microsoft Way 482 Redmond, WA 98052 483 +1 425 703-2947 484 cweider@microsoft.com 486 This document expires on 17 May 1999