idnits 2.17.1 draft-daboo-carddav-directory-gateway-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 8, 2010) is 5160 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) ** Obsolete normative reference: RFC 2426 (Obsoleted by RFC 6350) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Daboo 3 Internet-Draft Apple Inc. 4 Intended status: Standards Track March 8, 2010 5 Expires: September 9, 2010 7 CardDAV Directory Gateway Extension 8 draft-daboo-carddav-directory-gateway-01 10 Abstract 12 This document defines and extension to the vCard Extensions to WebDAV 13 (CardDAV) protocol that allows a server to expose a directory as a 14 read-only address book collection. 16 Status of this Memo 18 This Internet-Draft is submitted to IETF in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This Internet-Draft will expire on September 9, 2010. 39 Copyright Notice 41 Copyright (c) 2010 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the BSD License. 54 Table of Contents 56 1. Introduction and Overview . . . . . . . . . . . . . . . . . . . 3 57 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. CARDDAV:directory-gateway Property . . . . . . . . . . . . . . 4 59 4. Client Guidelines . . . . . . . . . . . . . . . . . . . . . . . 4 60 5. Server Guidelines . . . . . . . . . . . . . . . . . . . . . . . 5 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 62 7. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 6 63 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 6 64 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 65 9.1. Normative References . . . . . . . . . . . . . . . . . . . 7 66 9.2. Informative References . . . . . . . . . . . . . . . . . . 7 67 Appendix A. Change History (to be removed prior to 68 publication as an RFC) . . . . . . . . . . . . . . . . 7 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 1. Introduction and Overview 73 The CardDAV [I-D.ietf-vcarddav-carddav] protocol defines a standard 74 way of accessing, managing, and sharing contact information based on 75 the vCard [RFC2426] format. Often, in an enterprise or service 76 provider environment, a directory of all users hosted on the server 77 (or elsewhere) is available (for example via Lightweight Directory 78 Access Protocol (LDAP) [RFC4510] or some direct database access). It 79 would be convenient for CardDAV clients if this directory were 80 exposed as a "global" address book on the CardDAV server so it could 81 be searched just as personal address books are. This specification 82 defines a "directory gateway" feature extension to CardDAV to enable 83 this. 85 This specification adds one new WebDAV property to principal 86 resources that contains the URL to the directory gateway address book 87 collection resource. It is important for clients to be able to 88 distinguish this address book collection from others because there 89 are specific limitations involved in using it as described below. 91 Note that this feature is in no way intended to replace full 92 directory access - it is meant to simply provide a convenient way for 93 CardDAV clients to query contact-related attributes in directory 94 records. 96 2. Conventions 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 100 document are to be interpreted as described in [RFC2119]. 102 The term "protected" is used in the Conformance field of property 103 definitions as defined in Section 15 of [RFC4918]. 105 This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section 106 3.2) as a purely notational convention. WebDAV request and response 107 bodies cannot be validated by a DTD due to the specific extensibility 108 rules defined in Section 17 of [RFC4918] and due to the fact that all 109 XML elements defined by this specification use the XML namespace name 110 "DAV:". In particular: 112 1. element names use the "DAV:" namespace, 114 2. element ordering is irrelevant unless explicitly stated, 116 3. extension elements (elements not already defined as valid child 117 elements) may be added anywhere, except when explicitly stated 118 otherwise, 120 4. extension attributes (attributes not already defined as valid for 121 this element) may be added anywhere, except when explicitly 122 stated otherwise. 124 When XML element types in the namespaces "DAV:" and 125 "urn:ietf:params:xml:ns:carddav" are referenced in this document 126 outside of the context of an XML fragment, the strings "DAV:" and 127 "CARDDAV:" will be prefixed to the element types, respectively. 129 3. CARDDAV:directory-gateway Property 131 Name: directory-gateway 133 Namespace: urn:ietf:params:xml:ns:carddav 135 Purpose: Identifies the URL of a CardDAV address book collection 136 acting as the directory gateway for the server. 138 Protected: MUST be protected. 140 allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop 141 request. 143 Description: The CARDDAV:directory-gateway identifies an address 144 book collection resource that is the directory gateway address 145 book for the server. 147 Definition: 149 151 Example: 153 155 /directory 156 158 4. Client Guidelines 160 Clients wishing to make use of the directory gateway address book can 161 request the CARDDAV:directory-gateway property when examining other 162 properties on the principal resource for the user. If the property 163 is not present, then the directory gateway feature is not supported 164 by the server at that time. 166 Since the directory being exposed via the directory gateway address 167 book collection could be large, clients SHOULD use the feature to 168 limit the number of results returned in an CARDDAV:addressbook-query 169 REPORT as defined in Section 8.6.1 of [I-D.ietf-vcarddav-carddav]. 171 Clients MUST treat the directory gateway address book collection as a 172 read-only collection, so HTTP methods that modify resource data or 173 properties in the address book collection MUST NOT be used. 175 Clients SHOULD NOT attempt to cache the entire contents of the 176 directory gateway address book collection resource by retrieving all 177 resources. Instead, CARDDAV:addressbook-query REPORTs are used to 178 search for specific address book object resources. 180 5. Server Guidelines 182 Servers wishing to expose a directory gateway as an address book 183 collection MUST include the CARDDAV:directory-gateway property on all 184 principal resources of users expected to use the feature. 186 Since the directory being exposed via the directory gateway address 187 book collection could be large, servers SHOULD use the feature to 188 truncate the number of results returned in an CARDDAV:addressbook- 189 query REPORT as defined in Section 8.6.2 of 190 [I-D.ietf-vcarddav-carddav]. In addition, servers SHOULD disallow 191 requests that effectively enumerate the collection contents (e.g., 192 PROPFIND Depth:1, trivial CARDDAV:addressbook-query, DAV:sync- 193 collection REPORT). 195 Servers need to expose the directory information as a set of address 196 book object resources in the directory gateway address book 197 collection resource. To do that, a mapping between the directory 198 record format and the vCard data has to be applied. In general, only 199 directory record attributes that have a direct equivalent in vCard 200 SHOULD be mapped. It is up to individual implementations to 201 determine which attributes to map. But in all cases servers MUST 202 generate valid vCard data as returned to the client. In addition, as 203 required by CardDAV, the UID vCard property MUST be present in the 204 vCard data, and this value MUST be persistent from query to query for 205 the same directory record. 207 Multiple directory sources could be available to the server. If the 208 server wished to expose data from all of these, it MUST use the 209 single directory gateway resource to do so, aggregating results from 210 each directory source. When doing so care is needed when dealing 211 with potential records that refer to the same entity. Servers MAY 212 suppress any duplicates that they are able to determine themselves. 214 Records in a directory can include data for more than just people, 215 e.g, resources such as rooms or projectors, groups, computer systems 216 etc. It is up to individual implementations to determine the most 217 appropriate "scope" for the data returned via the directory gateway 218 by filtering the appropriate record types. 220 Servers MAY apply implementation defined access rules to determine, 221 on a per-user basis, what records are returned to a particularly user 222 and the content of those records exposed via vCard data. This per- 223 user behavior is in addition to the general security requirements 224 detailed below. 226 6. Security Considerations 228 Servers MUST ensure that client requests against the directory 229 gateway address book collection cannot use excessive resources (CPU, 230 memory, network bandwidth etc), given that the directory could be 231 large. 233 Servers MUST take care not to expose sensitive directory record 234 attributes in the vCard data via the directory gateway address book. 235 In general only those properties that have direct correspondence in 236 vCard SHOULD be exposed. 238 Servers need to determine whether it is appropriate for the directory 239 information to be available via CardDAV to unauthenticated users. If 240 not, servers MUST ensure that unauthenticated users do not have 241 access to the directory gateway address book object resource and its 242 contents. If unauthenticated access is allowed, servers MAY choose 243 to limit the set of vCard properties that are searchable or returned 244 in the address book object resources when unauthenticated requests 245 are made. 247 7. IANA Consideration 249 This document does not require any actions on the part of IANA. 251 8. Acknowledgments 253 9. References 254 9.1. Normative References 256 [I-D.ietf-vcarddav-carddav] 257 Daboo, C., "vCard Extensions to WebDAV (CardDAV)", 258 draft-ietf-vcarddav-carddav-10 (work in progress), 259 November 2009. 261 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 262 Requirement Levels", BCP 14, RFC 2119, March 1997. 264 [RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile", 265 RFC 2426, September 1998. 267 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed 268 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 270 [W3C.REC-xml-20081126] 271 Paoli, J., Yergeau, F., Bray, T., Sperberg-McQueen, C., 272 and E. Maler, "Extensible Markup Language (XML) 1.0 (Fifth 273 Edition)", World Wide Web Consortium Recommendation REC- 274 xml-20081126, November 2008, 275 . 277 9.2. Informative References 279 [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol 280 (LDAP): Technical Specification Road Map", RFC 4510, 281 June 2006. 283 Appendix A. Change History (to be removed prior to publication as an 284 RFC) 286 Changes in -01 288 1. Remove duplicated text in a couple of sections 290 2. Add example of LDAP/generic database as possible directory 291 "sources" 293 3. Add text to explain why the client needs to treat this as special 294 and thus the need for a property 296 4. Added text to server guidelines indicating requirements for 297 handling vCard UID properties 299 5. Added text to server guidelines explain that different record 300 "types" may exist in the directory and the server is free to 301 filter those as appropriate 303 6. Added text to server guidelines indicating that server are free 304 to aggregate directory records from multiple sources 306 7. Added text to server guidelines indicating that servers are free 307 to apply implementation defined access control to the returned 308 data on a per-user basis 310 Author's Address 312 Cyrus Daboo 313 Apple Inc. 314 1 Infinite Loop 315 Cupertino, CA 95014 316 USA 318 Email: cyrus@daboo.name 319 URI: http://www.apple.com/