idnits 2.17.1 draft-ietf-ldapext-c-api-vlv-01.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: ---------------------------------------------------------------------------- ** 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. == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 60 lines 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.) ** There are 9 instances of too long lines in the document, the longest one being 2 characters in excess of 72. ** The abstract seems to contain references ([KEYWORDS]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? RFC 2119 keyword, line 67: '... the "virtual list box" feature SHOULD...' RFC 2119 keyword, line 71: '... VLV feature, it MUST construct a Virt...' RFC 2119 keyword, line 74: '...ical. Client applications MAY use the...' RFC 2119 keyword, line 78: '...processing, the server SHOULD return a...' RFC 2119 keyword, line 80: '...Response control MAY be parsed to extr...' (5 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 99 has weird spacing: '...ed long ldvl...' == Line 100 has weird spacing: '...ed long ldvl...' == Line 102 has weird spacing: '...ed long ldvl...' == Line 103 has weird spacing: '...ed long ldvl...' == Line 271 has weird spacing: '...for the purpo...' -- 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 (12 March 1998) is 9542 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 section? 'KEYWORDS' on line 292 looks like a reference -- Missing reference section? 'CAPI' on line 288 looks like a reference -- Missing reference section? 'LDAP' on line 295 looks like a reference -- Missing reference section? 'VLV' on line 306 looks like a reference -- Missing reference section? 'SSS' on line 298 looks like a reference -- Missing reference section? 'SSSAPI' on line 302 looks like a reference Summary: 11 errors (**), 0 flaws (~~), 7 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 LDAPEXT Working Group M. Smith 3 INTERNET-DRAFT Netscape Communications Corp. 4 Intended Category: Standards Track 5 Expires: 12 September 1998 7 12 March 1998 9 LDAP C API Extensions for Scrolling View Browsing of Search Results 10 12 1. Status of this Memo 14 This draft document will be submitted to the RFC Editor as a Standards 15 Track document. Distribution of this memo is unlimited. Technical dis- 16 cussion of this document will take place on the IETF LDAP Extension 17 Working Group mailing list . Please send 18 editorial comments directly to the author . 20 This document is an Internet-Draft. Internet-Drafts are working docu- 21 ments of the Internet Engineering Task Force (IETF), its areas, and its 22 working groups. Note that other groups may also distribute working 23 documents as Internet-Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference material 28 or to cite them other than as ``work in progress.'' 30 To learn the current status of any Internet-Draft, please check the 31 ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow 32 Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), 33 ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 35 Copyright (C) The Internet Society (1998). All Rights Reserved. 37 Please see the Copyright section near the end of this document for more 38 information. 40 2. Abstract 42 This document defines extensions to the LDAP C API to support the LDAP 43 Extensions for Scrolling View Browsing of Search Results. More specifi- 44 cally, this document defines functions to create Virtual List View 45 Request controls and to parse Virtual List View Response controls. 47 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 48 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are 49 to be interpreted as described in RFC 2119 [KEYWORDS]. 51 3. Background and Intended Usage 53 The LDAP C API [CAPI] defines a C language application programming 54 interface (API) to the Lightweight Directory Access Protocol [LDAP]. 55 This document defines extensions to that API to support an optional LDAP 56 extension for scrolling view browsing of search results, also known as 57 Virtual List View [VLV]. 59 The scrolling view browsing LDAP extension itself is designed to allow a 60 "virtual list box" feature to be supported efficiently by LDAP servers 61 and clients. The protocol extension consists of two LDAP controls: a 62 Virtual List View (VLV) Request control which is sent by a client to a 63 server along with an LDAP search request and a Virtual List View 64 Response control which is returned by the server to send back status 65 information about the VLV request. 67 LDAP clients that wish to use the "virtual list box" feature SHOULD 68 first check the supportedControls attribute in a server's rootDSE to 69 determine if a value identical to the Virtual List View Request 70 control's OID is present. If the OID is present and the client chooses 71 to use the VLV feature, it MUST construct a Virtual List View Request 72 control and a Server Side Sorting Control [SSS] and send both controls 73 to the server within an LDAP searchRequest message. Both controls 74 SHOULD be marked critical. Client applications MAY use the 75 ldap_create_virtuallist_control() function described in this document to 76 create a Virtual List View Request control. 78 At the end of the search request processing, the server SHOULD return a 79 Virtual List View Response control in the LDAP searchResultDone message. 80 A Virtual List View Response control MAY be parsed to extract its con- 81 tents by using the ldap_parse_virtuallist_control() function described 82 in this document. 84 4. Creating a Virtual List View Request Control 86 The LDAPVirtualList structure describes a Virtual List View Request con- 87 trol and is passed to the ldap_create_virtuallist_control() function to 88 create a VLV Request control. The resulting control SHOULD be passed to 89 the ldap_search_ext() or ldap_search_ext_s() functions described in 90 [CAPI] to send them to the server. The ldap_create_sort_control() func- 91 tion described in [SSSAPI] MAY be used to create a Sort control that 92 MUST be passed to the server along with the VLV request. 94 The LDAPVirtualList structure MAY also be used by applications to manage 95 the state information associated with a series of virtual list view 96 client/server interactions. 98 typedef struct ldapvirtuallist { 99 unsigned long ldvlist_before_count; 100 unsigned long ldvlist_after_count; 101 char *ldvlist_attrvalue; 102 unsigned long ldvlist_index; 103 unsigned long ldvlist_size; 104 void *ldvlist_extradata; 105 } LDAPVirtualList; 107 int ldap_create_virtuallist_control( 108 LDAP *ld, 109 LDAPVirtualList *ldvlistp, 110 LDAPControl **ctrlp 111 ); 113 #define LDAP_CONTROL_VLVREQUEST "2.16.840.1.113730.3.4.9" 115 The parameters to the ldap_create_virtuallist_control() function are: 117 ld An LDAP session handle, as obtained from a call to 118 ldap_init(). 120 ldvlistp The address of an LDAPVirtualList structure whose 121 contents are used to construct the value of the 122 control that is created. 124 ctrlp A result parameter that will be assigned the 125 address of an LDAPControl structure that contains 126 the VLV Request control created by this function. 127 The memory occupied by the LDAPControl structure 128 should be freed when it is no longer in use by cal- 129 ling ldap_control_free(). 131 The ldap_create_virtuallist_control() function returns an LDAP error 132 code to indicate success or failure (LDAP_SUCCESS if all goes well). 134 The members of the LDAPVirtualList structure are: 136 ldvlist_before_count A count of the number of entries before the target 137 entry the client wants the server to send back. 138 This field corresponds to the beforeCount element 139 of the BER-encoded VirtualListViewRequest control 140 value itself. 142 ldvlist_after_count A count of the number of entries after the target 143 entry the client wants the server to send back. 144 This field corresponds to the afterCount element of 145 the BER-encoded VirtualListViewRequest control 146 value itself. 148 ldvlist_attrvalue If this is not NULL, it indicates that the byValue 149 choice within the VirtualListViewRequest is to be 150 used, and corresponds to the assertionValue element 151 of the BER-encoded VirtualListViewRequest control 152 value itself. This value is compared by the server 153 with the values of the attribute specified by the 154 primary sort key to determine the target entry. 156 ldvlist_index This field is only used if ldvlist_attrvalue is 157 NULL, i.e, if the byIndex choice within the Virtu- 158 alListViewRequest control is to be used. 159 ldvlist_index is used along with the ldvlist_size 160 value by the server to determine the target entry. 161 This field corresponds to the index element within 162 the BER-encoded VirtualListViewRequest control 163 value itself. 165 ldvlist_size This field is only used if ldvlist_attrvalue is 166 NULL, i.e., if the byIndex choice within the Virtu- 167 alListViewRequest control is to be used. 168 ldvlist_size is used along with the ldvlist_index 169 value by the server to determine the target entry. 170 This field corresponds to the contentCount element 171 within the BER-encoded VirtualListViewRequest con- 172 trol value itself. 174 ldvlist_extradata This field is reserved for application-specific use 175 and is not used by the 176 ldap_create_virtuallist_control() function; it has 177 no effect on the control that is created. 179 5. Parsing a Virtual List View Response Control 181 When an application receives the result from a VLV search, it SHOULD use 182 the ldap_parse_virtuallist_control() function to look for and parse the 183 Virtual List View Response control returned by the server. 185 int ldap_parse_virtuallist_control( 186 LDAP *ld, 187 LDAPControl **ctrls, 188 unsigned long *target_posp, 189 unsigned long *list_sizep, 190 int *errcodep 191 ); 193 #define LDAP_CONTROL_VLVRESPONSE "2.16.840.1.113730.3.4.10" 195 #define LDAP_SORT_CONTROL_MISSING 0x3C /* 60 */ 196 #define LDAP_INDEX_RANGE_ERROR 0x3D /* 61 */ 198 The parameters to the ldap_parse_virtuallist_control() function are: 200 ld An LDAP session handle. 202 ctrls The address of a NULL-terminated array of LDAPCon- 203 trol structures, typically obtained by a call to 204 ldap_parse_result(). 206 target_posp This result parameter is filled in with the list 207 index of the target entry. If this parameter is 208 NULL, the target position is not returned. The 209 value for this result parameter is pulled from the 210 targetPosition element of the BER-encoded Virtual- 211 ListViewResponse control value itself. 213 list_sizep This result parameter is filled in with the 214 server's estimate of the size of the list. If this 215 parameter is NULL, the size is not returned. The 216 value for this result parameter is pulled from the 217 contentCount element of the BER-encoded Virtual- 218 ListViewResponse control value itself. 220 errcodep This result parameter is filled in with the VLV 221 result code. If this parameter is NULL, the result 222 code is not returned. The value for this result 223 parameter is pulled from the virtualListViewResult 224 element of the BER-encoded VirtualListViewResponse 225 control value itself. It SHOULD have one of the 226 following values: 228 LDAP_SUCCESS (0); defined in [CAPI] 229 LDAP_OPERATIONS_ERROR (1); defined in [CAPI] 230 LDAP_UNWILLING_TO_PERFORM (53); defined in [CAPI] 231 LDAP_INSUFFICIENT_ACCESS (50); defined in [CAPI] 232 LDAP_BUSY (51); defined in [CAPI] 233 LDAP_TIMELIMIT_EXCEEDED (3); defined in [CAPI] 234 LDAP_ADMINLIMIT_EXCEEDED (11); defined in [CAPI] 235 LDAP_SORT_CONTROL_MISSING (60); defined above 236 LDAP_INDEX_RANGE_ERROR (61); defined above 237 LDAP_OTHER (50); defined in [CAPI] 239 The ldap_parse_virtuallist_control() function returns an LDAP error code 240 that indicates whether a VLV Result control was found and whether the 241 parsing was successful. LDAP_SUCCESS is returned if all goes well, 242 LDAP_CONTROL_NOT_FOUND is returned if the ctrls array does not include a 243 VLV Response control, and another LDAP error code that is defined in 244 [CAPI] is returned if a parsing error or other problem occurs. 246 6. Security Considerations 248 Most servers will be configured to restrict access to the Virtual List 249 View feature since poorly-behaved or malicious clients may cause many 250 resources to be consumed on the server, or allow users to retrieve too 251 many entries, or allow users to get an accurate count of the number of 252 entries present in a portion of the DIT. Clients should take care to 253 not abuse the VLV feature and should be prepared for servers to refuse 254 to service a particular VLV request due to access control or other 255 site-defined policies. 257 Please see the protocol extension document [VLV] for a discussion of 258 related security considerations. 260 7. Copyright 262 Copyright (C) The Internet Society (1998). All Rights Reserved. 264 others, and derivative works that comment on or otherwise explain it or 265 assist in its implementation may be prepared, copied, published and dis- 266 tributed, in whole or in part, without restriction of any kind, provided 267 that the above copyright notice and this paragraph are included on all 268 such copies and derivative works. However, this document itself may not 269 be modified in any way, such as by removing the copyright notice or 270 references to the Internet Society or other Internet organizations, 271 except as needed for the purpose of developing Internet standards in 272 which case the procedures for copyrights defined in the Internet Stan- 273 dards process must be followed, or as required to translate it into 274 languages other than English. 276 The limited permissions granted above are perpetual and will not be 277 revoked by the Internet Society or its successors or assigns. 279 This document and the information contained herein is provided on an "AS 280 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 281 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 282 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 283 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT- 284 NESS FOR A PARTICULAR PURPOSE. 286 8. Bibliography 288 [CAPI] M. Smith, T. Howes, A. Herron, C. Weider, M. Wahl, A. Anan- 289 tha, "The C LDAP Application Program Interface", INTERNET- 290 DRAFT, , March 1998. 292 [KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Require- 293 ment Levels", RFC 2119, March 1997. 295 [LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access 296 Protocol (v3)", RFC 2251, December 1997. 298 [SSS] A. Herron, T. Howes, M. Wahl, C.Weider, A. Anantha, "LDAP 299 Control Extension for Server Side Sorting of Search 300 Results", INTERNET-DRAFT, March 1997. 302 [SSSAPI] C. Weider, A. Herron, T. Howes, M. Smith, M. Wahl, "LDAP API 303 Extensions for Sort and Simple Paged Results", INTERNET- 304 DRAFT, , July 1997. 306 [VLV] David Boreham, "LDAP Extensions for Scrolling View Browsing 307 of Search Results", INTERNET-DRAFT , March 1998. 310 9. Author's Address 312 Mark Smith 313 Netscape Communications Corp. 314 501 E. Middlefield Rd., Mailstop MV068 315 Mountain View, CA 94043 316 USA 317 +1 650 937-3477 318 mcs@netscape.com 320 1. Status of this Memo............................................1 321 2. Abstract.......................................................2 322 3. Background and Intended Usage..................................2 323 4. Creating a Virtual List View Request Control...................3 324 5. Parsing a Virtual List View Response Control...................5 325 6. Security Considerations........................................6 326 7. Copyright......................................................6 327 8. Bibliography...................................................7 328 9. Author's Address...............................................7