diff options
author | Paolo T <tuscanhobbit@users.noreply.github.com> | 2013-10-25 00:09:42 -0700 |
---|---|---|
committer | Paolo T <tuscanhobbit@users.noreply.github.com> | 2013-10-25 00:09:42 -0700 |
commit | b23f3fc03b6bc751aab67fe2258a21f7c65bab8e (patch) | |
tree | 84c997aa781afa566536ca5f66eb8f90ef468476 /vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt | |
parent | d30f718e0836a031e43d5403480aa049561e736e (diff) | |
parent | 0b0bd3c20765d267ec6d7cc261c7713917a22582 (diff) | |
download | volse-hubzilla-b23f3fc03b6bc751aab67fe2258a21f7c65bab8e.tar.gz volse-hubzilla-b23f3fc03b6bc751aab67fe2258a21f7c65bab8e.tar.bz2 volse-hubzilla-b23f3fc03b6bc751aab67fe2258a21f7c65bab8e.zip |
Merge pull request #3 from friendica/master
Align to main project HEAD
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, 560 insertions, 0 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 new file mode 100644 index 000000000..63aa8b29c --- /dev/null +++ b/vendor/sabre/dav/docs/draft-daboo-carddav-directory-gateway-02.txt @@ -0,0 +1,560 @@ + + + +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] + |