diff options
Diffstat (limited to 'vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt')
| -rw-r--r-- | vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt | 560 |
1 files changed, 0 insertions, 560 deletions
diff --git a/vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt b/vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt deleted file mode 100644 index 63aa8b29c..000000000 --- a/vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt +++ /dev/null @@ -1,560 +0,0 @@ - - - -Network Working Group C. Daboo -Internet-Draft Apple Inc. -Updates: XXXX-CardDAV August 24, 2010 -(if approved) -Intended status: Standards Track -Expires: February 25, 2011 - - - CardDAV Directory Gateway Extension - draft-daboo-carddav-directory-gateway-02 - -Abstract - - This document defines an extension to the vCard Extensions to WebDAV - (CardDAV) protocol that allows a server to expose a directory as a - read-only address book collection. - -Status of this Memo - - This Internet-Draft is submitted in full conformance with the - provisions of BCP 78 and BCP 79. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF). Note that other groups may also distribute - working documents as Internet-Drafts. The list of current Internet- - Drafts is at http://datatracker.ietf.org/drafts/current/. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - This Internet-Draft will expire on February 25, 2011. - -Copyright Notice - - Copyright (c) 2010 IETF Trust and the persons identified as the - document authors. All rights reserved. - - This document is subject to BCP 78 and the IETF Trust's Legal - Provisions Relating to IETF Documents - (http://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. - - - -Daboo Expires February 25, 2011 [Page 1] - -Internet-Draft CardDAV Directory Gateway Extension August 2010 - - -Table of Contents - - 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 - 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 3. CARDDAV:directory-gateway Property . . . . . . . . . . . . . . 4 - 4. XML Element Definitions . . . . . . . . . . . . . . . . . . . 5 - 4.1. CARDDAV:directory . . . . . . . . . . . . . . . . . . . . 5 - 5. Client Guidelines . . . . . . . . . . . . . . . . . . . . . . 5 - 6. Server Guidelines . . . . . . . . . . . . . . . . . . . . . . 6 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 - 8. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 8 - 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 8 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 - 10.1. Normative References . . . . . . . . . . . . . . . . . . . 8 - 10.2. Informative References . . . . . . . . . . . . . . . . . . 9 - Appendix A. Change History (to be removed prior to - publication as an RFC) . . . . . . . . . . . . . . . 9 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Daboo Expires February 25, 2011 [Page 2] - -Internet-Draft CardDAV Directory Gateway Extension August 2010 - - -1. Introduction and Overview - - The CardDAV [I-D.ietf-vcarddav-carddav] protocol defines a standard - way of accessing, managing, and sharing contact information based on - the vCard [RFC2426] format. Often, in an enterprise or service - provider environment, a directory of all users hosted on the server - (or elsewhere) is available (for example via Lightweight Directory - Access Protocol (LDAP) [RFC4510] or some direct database access). It - would be convenient for CardDAV clients if this directory were - exposed as a "global" address book on the CardDAV server so it could - be searched in the same way as personal address books are. This - specification defines a "directory gateway" feature extension to - CardDAV to enable this. - - This specification adds one new WebDAV property to principal - resources that contains the URL to one or more directory gateway - address book collection resources. It is important for clients to be - able to distinguish this address book collection from others because - there are specific limitations involved in using it as described - below. To aid that, this specification defines an XML element that - can be included as a child element of the DAV:resourcetype property - of address book collections to identify them as directory gateways. - - Note that this feature is in no way intended to replace full - directory access - it is meant to simply provide a convenient way for - CardDAV clients to query contact-related attributes in directory - records. - - -2. Conventions - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in [RFC2119]. - - The term "protected" is used in the Conformance field of property - definitions as defined in Section 15 of [RFC4918]. - - This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section - 3.2) as a purely notational convention. WebDAV request and response - bodies cannot be validated by a DTD due to the specific extensibility - rules defined in Section 17 of [RFC4918] and due to the fact that all - XML elements defined by this specification use the XML namespace name - "DAV:". In particular: - - 1. element names use the "DAV:" namespace, - - - - - -Daboo Expires February 25, 2011 [Page 3] - -Internet-Draft CardDAV Directory Gateway Extension August 2010 - - - 2. element ordering is irrelevant unless explicitly stated, - - 3. extension elements (elements not already defined as valid child - elements) may be added anywhere, except when explicitly stated - otherwise, - - 4. extension attributes (attributes not already defined as valid for - this element) may be added anywhere, except when explicitly - stated otherwise. - - When XML element types in the namespaces "DAV:" and - "urn:ietf:params:xml:ns:carddav" are referenced in this document - outside of the context of an XML fragment, the strings "DAV:" and - "CARDDAV:" will be prefixed to the element types, respectively. - - -3. CARDDAV:directory-gateway Property - - Name: directory-gateway - - Namespace: urn:ietf:params:xml:ns:carddav - - Purpose: Identifies URLs of CardDAV address book collections acting - as a directory gateway for the server. - - Protected: MUST be protected. - - allprop behavior: SHOULD NOT be returned by a PROPFIND DAV:allprop - request. - - Description: The CARDDAV:directory-gateway identifies address book - collection resources that are directory gateway address books for - the server. - - Definition: - - <!ELEMENT directory-gateway (DAV:href*)> - - Example: - - <C:directory-gateway xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:carddav"> - <D:href>/directory</D:href> - </C:directory-gateway> - - - - - - - -Daboo Expires February 25, 2011 [Page 4] - -Internet-Draft CardDAV Directory Gateway Extension August 2010 - - -4. XML Element Definitions - -4.1. CARDDAV:directory - - Name: directory - - Namespace: urn:ietf:params:xml:ns:carddav - - Purpose: Used to indicate that an address book collection is a - directory gateway. - - Description: This element appears in the DAV:resourcetype property - on a address book collection resources that are directory - gateways. Clients can use the presence of this element to - identify directory gateway collections when doing PROPFINDs to - list collection contents. - - Definition: - - <!ELEMENT directory EMPTY> - - Example: - - <D:resourcetype xmlns:D="DAV:" - xmlns:C="urn:ietf:params:xml:ns:carddav"> - <D:collection/> - <C:addressbook/> - <C:directory/> - </D:resourcetype> - - -5. Client Guidelines - - Clients wishing to make use of directory gateway address books can - request the CARDDAV:directory-gateway property (Section 3) when - examining other properties on the principal resource for the user. - If the property is not present, then the directory gateway feature is - not supported by the server at that time. - - Clients can also detect the presence of directory gateway address - book collections by retrieving the DAV:resourcetype property on - collections that it lists, and look for the presence of the CARDDAV: - directory element (Section 4.1). - - Since the directory being exposed via a directory gateway address - book collection could be large, clients SHOULD limit the number of - results returned in an CARDDAV:addressbook-query REPORT as defined in - Section 8.6.1 of [I-D.ietf-vcarddav-carddav]. - - - -Daboo Expires February 25, 2011 [Page 5] - -Internet-Draft CardDAV Directory Gateway Extension August 2010 - - - Clients MUST treat the directory gateway address book collection as a - read-only collection, so HTTP methods that modify resource data or - properties in the address book collection MUST NOT be used. - - Clients SHOULD NOT attempt to cache the entire contents of the - directory gateway address book collection resource by retrieving all - resources, or trying to examine all the properties of all resources - (e.g., via a PROPFIND Depth:1 request). Instead, CARDDAV: - addressbook-query REPORTs are used to search for specific address - book object resources, and CARDDAV:multiget REPORTs and individual - GET requests can be made to retrieve the actual vCard data for - address book object resources found via a query. - - When presenting directory gateway collections to the user, clients - SHOULD use the DAV:displayname property on the corresponding address - book collections as the name of the directory gateway. This is - important in the case where more than one directory gateway is - available. Clients MAY also provide descriptive information about - each directory gateway by examining the CARDDAV:addressbook- - description property (see Section 6.2.1 of - [I-D.ietf-vcarddav-carddav]) on the resource. - - -6. Server Guidelines - - Servers wishing to expose a directory gateway as an address book - collection MUST include the CARDDAV:directory-gateway property on all - principal resources of users expected to use the feature. - - Since the directory being exposed via the directory gateway address - book collection could be large, servers SHOULD truncate the number of - results returned in an CARDDAV:addressbook-query REPORT as defined in - Section 8.6.2 of [I-D.ietf-vcarddav-carddav]. In addition, servers - SHOULD disallow requests that effectively enumerate the collection - contents (e.g., PROPFIND Depth:1, trivial CARDDAV:addressbook-query, - DAV:sync-collection REPORT). - - Servers need to expose the directory information as a set of address - book object resources in the directory gateway address book - collection resource. To do that, a mapping between the directory - record format and the vCard data has to be applied. In general, only - directory record attributes that have a direct equivalent in vCard - SHOULD be mapped. It is up to individual implementations to - determine which attributes to map. But in all cases servers MUST - generate valid vCard data as returned to the client. In addition, as - required by CardDAV, the UID vCard property MUST be present in the - vCard data, and this value MUST be persistent from query to query for - the same directory record. - - - -Daboo Expires February 25, 2011 [Page 6] - -Internet-Draft CardDAV Directory Gateway Extension August 2010 - - - Multiple directory sources could be available to the server. The - server MAY use a single directory gateway resource to aggregate - results from each directory source. When doing so care is needed - when dealing with potential records that refer to the same entity. - Servers MAY suppress any duplicates that they are able to determine - themselves. Alternatively, multiple directory sources can be exposed - as separate directory gateway resources. - - For any directory source, a server MAY expose multiple directory - gateway resources where each represents a different query "scope" for - the directory. Different scopes MAY be offered to different - principals on the server. For example, the server might expose an - entire company directory for searching as the resource "/directory- - all" to all principals, but then provide "/directory-department-XYZ" - as another directory gateway that has a search scope that implicitly - limits the search results to just the "XYZ" department. Users in - that department would then have a CARDDAV:directory-gateway property - on their principal resource that included the "/directory-department- - XYZ" resource. Users in other departments would have corresponding - directory gateway resources available to them. - - Records in a directory can include data for more than just people, - e.g, resources such as rooms or projectors, groups, computer systems - etc. It is up to individual implementations to determine the most - appropriate "scope" for the data returned via the directory gateway - by filtering the appropriate record types. As above, servers could - choose to expose people and resources under different directory - gateway resources by implicitly limiting the search "scope" for each - of those. - - Servers MAY apply implementation defined access rules to determine, - on a per-user basis, what records are returned to a particularly user - and the content of those records exposed via vCard data. This per- - user behavior is in addition to the general security requirements - detailed below. - - When multiple directory gateway collections are present, servers - SHOULD provide a DAV:displayname property on each that disambiguates - them. Servers MAY include a CARDDAV:addressbook-description property - (see Section 6.2.1 of [I-D.ietf-vcarddav-carddav]) on each directory - gateway resource to provide a description of the directory and any - search "scope" that might be used, or any other useful information - for users. - - -7. Security Considerations - - Servers MUST ensure that client requests against the directory - - - -Daboo Expires February 25, 2011 [Page 7] - -Internet-Draft CardDAV Directory Gateway Extension August 2010 - - - gateway address book collection cannot use excessive resources (CPU, - memory, network bandwidth etc), given that the directory could be - large. - - Servers MUST take care not to expose sensitive directory record - attributes in the vCard data via the directory gateway address book. - In general only those properties that have direct correspondence in - vCard SHOULD be exposed. - - Servers need to determine whether it is appropriate for the directory - information to be available via CardDAV to unauthenticated users. If - not, servers MUST ensure that unauthenticated users do not have - access to the directory gateway address book object resource and its - contents. If unauthenticated access is allowed, servers MAY choose - to limit the set of vCard properties that are searchable or returned - in the address book object resources when unauthenticated requests - are made. - - -8. IANA Consideration - - This document does not require any actions on the part of IANA. - - -9. Acknowledgments - - -10. References - -10.1. Normative References - - [I-D.ietf-vcarddav-carddav] - Daboo, C., "vCard Extensions to WebDAV (CardDAV)", - draft-ietf-vcarddav-carddav-10 (work in progress), - November 2009. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile", - RFC 2426, September 1998. - - [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed - Authoring and Versioning (WebDAV)", RFC 4918, June 2007. - - [W3C.REC-xml-20081126] - Paoli, J., Yergeau, F., Bray, T., Sperberg-McQueen, C., - and E. Maler, "Extensible Markup Language (XML) 1.0 (Fifth - - - -Daboo Expires February 25, 2011 [Page 8] - -Internet-Draft CardDAV Directory Gateway Extension August 2010 - - - Edition)", World Wide Web Consortium Recommendation REC- - xml-20081126, November 2008, - <http://www.w3.org/TR/2008/REC-xml-20081126>. - -10.2. Informative References - - [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol - (LDAP): Technical Specification Road Map", RFC 4510, - June 2006. - - -Appendix A. Change History (to be removed prior to publication as an - RFC) - - Changes in -02 - - 1. Added CARDDAV:directory element for use in DAV:resourcetype - - 2. Allow CARDDAV:directory-gateway to be multi-valued - - 3. Explain how a server could implicit "scope" queries on different - directory gateway resources - - Changes in -01 - - 1. Remove duplicated text in a couple of sections - - 2. Add example of LDAP/generic database as possible directory - "sources" - - 3. Add text to explain why the client needs to treat this as special - and thus the need for a property - - 4. Added text to server guidelines indicating requirements for - handling vCard UID properties - - 5. Added text to server guidelines explain that different record - "types" may exist in the directory and the server is free to - filter those as appropriate - - 6. Added text to server guidelines indicating that server are free - to aggregate directory records from multiple sources - - 7. Added text to server guidelines indicating that servers are free - to apply implementation defined access control to the returned - data on a per-user basis - - - - - -Daboo Expires February 25, 2011 [Page 9] - -Internet-Draft CardDAV Directory Gateway Extension August 2010 - - -Author's Address - - Cyrus Daboo - Apple Inc. - 1 Infinite Loop - Cupertino, CA 95014 - USA - - Email: cyrus@daboo.name - URI: http://www.apple.com/ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Daboo Expires February 25, 2011 [Page 10] - |